Merge pull request #764 from ethersphere/gateway-update

EchinopsisMonstrose · web-flow · commit e35bb3d6a83f · 2026-02-02T16:52:25.000+07:00
draft of updated gateway content
diff --git a/docs/develop/gateway.md b/docs/develop/gateway.md
@@ -0,0 +1,301 @@
+---
+title: Run a Gateway
+id: gateway-proxy
+---
+
+This guide explains how to use the [swarm-gateway](https://github.com/ethersphere/swarm-gateway) tool to set up your node in gateway mode. Running your node in gateway mode exposes it publicly, allowing access through any typical browser or http API. 
+
+It is divided into several parts:
+
+* Part 1 - Basic setup 
+* Part 2 - Securing your gateway with TLS
+* Part 3 - Optional features
+
+## Part 1 — Running a Swarm Gateway (HTTP, minimal setup)
+
+:::info
+Historically, the main tool for running a Swarm HTTP gateway was [gateway-proxy](https://github.com/ethersphere/gateway-proxy), however it is planned to be deprecated in favor of [swarm-gateway](https://github.com/ethersphere/swarm-gateway).
+
+At the time of writing, `gateway-proxy` still contains some features that are not yet implemented in `swarm-gateway` - unless you have a specific need for these features however, `swarm-gateway` is strongly recommended.
+:::
+
+This guide describes how to run a Swarm HTTP gateway using `swarm-gateway` and Bee with a minimal configuration.
+
+At the end of this section, the gateway will be reachable at:
+
+```text
+http://your-domain.example
+```
+
+Swarm content will be accessible at:
+
+```text
+http://your-domain.example/bzz/<reference>/
+```
+
+:::warning Security notice
+This setup uses plain HTTP.
+
+Traffic is not encrypted and any `Authorization` headers can be observed by intermediaries on the network path. This configuration is not suitable for production use.
+
+The purpose of this section is to verify that the gateway is working. HTTPS is added in a later part of the guide.
+:::
+
+The guide in this section:
+
+* Runs `swarm-gateway` using Docker
+* Connects it to an existing Bee node
+* Exposes it publicly over HTTP
+
+:::danger
+This part of the guide does not cover setting up TLS, so your gateway will be accessible through plain HTTP, not HTTPS, making it highly insecure. It should not be exposed publicly without first setting up TLS, which is covered in the next section.
+:::
+
+### Prerequisites
+
+
+* A VPS with:
+  * A public IP address 
+  * Port **80** open
+* Docker 
+* A domain for hosting your gateway publicly
+* A running Bee node in Docker
+* A valid stamp batch
+
+### 1. Configure DNS for your domain
+
+Create an A record in your DNS provider:
+
+```text
+your-domain.example -> <your-server-ip>
+```
+
+ADD SCREENSHOT 
+
+After DNS propagation, verify that the domain resolves to your server (this may take some time, to verify more quickly, try pinging from a different machine or VPS):
+
+```bash
+ping your-domain.example
+```
+
+### 2. Create a Docker network
+
+The gateway container must be able to communicate with your Bee node, for this, both containers must be on the same Docker network.
+
+Create a network and attach the Bee container to it:
+
+```bash
+docker network create swarm-net
+docker network connect swarm-net bee-1
+```
+
+Verify:
+
+```bash
+docker network inspect swarm-net
+```
+
+The output should list `bee-1` as an attached container.
+
+### 3. Pull the gateway image
+
+```bash
+docker pull ethersphere/swarm-gateway:0.1.3
+```
+
+### 4. Run the gateway
+
+Start the gateway container:
+
+```bash
+docker run -d --restart unless-stopped \
+  --name swarm-gateway \
+  --network swarm-net \
+  -p 80:3000 \
+  -e HOSTNAME="your-domain.example" \
+  -e BEE_API_URL="http://bee-1:1633" \
+  -e DATABASE_CONFIG="{}" \
+  ethersphere/swarm-gateway:0.1.3
+```
+
+In this configuration, database-backed features such as subdomain rewrites and moderation are not configured.
+
+### 5. Verify operation
+
+From your local machine (not the server on your VPS):
+
+```bash
+curl http://your-domain.example/health
+```
+
+Expected output:
+
+```text
+OK
+```
+
+### 6. Test with uploaded content
+
+Upload a file using Bee:
+
+```bash
+echo "hello swarm" > test.txt
+swarm-cli upload test.txt
+```
+
+This will print a Swarm reference.
+
+Open the file through the gateway:
+
+```text
+http://your-domain.example/bzz/<REFERENCE>/
+```
+
+The file contents should be returned.
+
+### 7. Optional: restrict uploads using authentication
+
+By default, the gateway allows anyone to upload content using your Bee node.
+
+To restrict uploads, set:
+
+* `AUTH_SECRET` — a long random string
+* `SOFT_AUTH=true` — only require authentication for POST requests
+
+Example (add these lines to the `docker run` command):
+
+```bash
+-e AUTH_SECRET="replace-with-a-long-random-secret" \
+-e SOFT_AUTH="true" \
+```
+
+At this point, you have:
+
+* A working Swarm HTTP gateway
+* Connected to your Bee node
+* Exposing content publicly over `/bzz/<reference>`
+
+The setup is intentionally minimal and suitable for testing and development, however without TLS, it is not secure and should never be used in production or publicly exposed. 
+
+The next section explains how to enable TLS so that your gateway can be securely accessed through HTTPS.
+
+
+## Part 2 — Securing your gateway with TLS (HTTPS)
+
+This section explains how to secure your gateway using **TLS (HTTPS)** with **Caddy**.
+
+Caddy is used here as a front-facing web server that automatically manages TLS certificates and forwards traffic to `swarm-gateway`.
+
+In this setup:
+
+* Caddy is responsible only for HTTPS and certificate management
+* `swarm-gateway` continues to act as the application gateway and reverse proxy for Bee
+
+At the end of this section, your gateway will be reachable at:
+
+```text
+https://your-domain.example
+```
+
+And all HTTP traffic will be automatically redirected to HTTPS.
+
+### Prerequisites
+
+In addition to the prerequisites from Part 1:
+
+* Your domain must already point to your VPS IP address
+* Ports **80** and **443** must be open on your VPS firewall
+
+
+### 1. Reconfigure the gateway to not expose port 80
+
+Caddy will become the public entry point, so `swarm-gateway` should no longer be exposed directly.
+
+Stop and remove the existing container:
+
+```bash
+docker stop swarm-gateway
+docker rm swarm-gateway
+```
+
+Recreate it **without** publishing port 80:
+
+```bash
+docker run -d --restart unless-stopped \
+  --name swarm-gateway \
+  --network swarm-net \
+  -e HOSTNAME="your-domain.example" \
+  -e BEE_API_URL="http://bee-1:1633" \
+  -e DATABASE_CONFIG="{}" \
+  ethersphere/swarm-gateway:0.1.3
+```
+
+The gateway is now only accessible from within the Docker network.
+
+
+### 2. Create a Caddy configuration
+
+Create a directory for the Caddy configuration:
+
+```bash
+mkdir -p ~/caddy
+cd ~/caddy
+```
+
+Create a file named `Caddyfile`:
+
+```bash
+nano Caddyfile
+```
+
+Add the following configuration (replace the domain):
+
+```caddy
+your-domain.example {
+  reverse_proxy swarm-gateway:3000
+}
+```
+
+### 3. Run Caddy
+
+Start Caddy in Docker and attach it to the same Docker network:
+
+```bash
+docker run -d --restart unless-stopped \
+  --name caddy \
+  --network swarm-net \
+  -p 80:80 \
+  -p 443:443 \
+  -v $HOME/caddy/Caddyfile:/etc/caddy/Caddyfile \
+  -v caddy_data:/data \
+  -v caddy_config:/config \
+  caddy:2
+```
+
+Caddy will automatically:
+
+* Obtain a TLS certificate for your domain
+* Renew it before it expires
+* Redirect all HTTP traffic to HTTPS
+
+
+### 4. Verify operation
+
+From your local machine:
+
+```bash
+curl https://your-domain.example/health
+```
+
+Expected output:
+
+```text
+OK
+```
+
+You can also verify that HTTP is redirected to HTTPS:
+
+```bash
+curl -I http://your-domain.example/health
+```
+
diff --git a/docs/develop/image.png b/docs/develop/image.png
diff --git a/docs/develop/introduction.md b/docs/develop/introduction.md
@@ -80,6 +80,15 @@ This is the go-to starting point for web3 developers who want to build with Swar
           <span class="hub-card__cta">Open Guide</span>
         </a>
       </li>
+      <li class="hub-card">
+        <a class="hub-card__link" href="/docs/develop/gateway-proxy">
+          <h3 class="hub-card__title">Run a Gateway</h3>
+          <p class="hub-card__desc">
+            Run your own Swarm HTTP gateway to serve content from the network and make it accessible to browsers and other HTTP clients.
+          </p>
+          <span class="hub-card__cta">Open guide</span>
+        </a>
+      </li>
       <!--
       <li class="hub-card">
         <a class="hub-card__link" href="/docs/develop/dynamic-content">
diff --git a/docs/develop/tools-and-features/gateway-proxy.md b/docs/develop/tools-and-features/gateway-proxy.md
@@ -3,17 +3,50 @@ title: Gateway Proxy
 id: gateway-proxy
 ---
 
-The [Gateway Proxy tool](https://github.com/ethersphere/gateway-proxy) is more than just a proxy, it offers a range of useful functionalities for node operators and Swarm developers. For more in depth documentation of its features, refer to its [README doc](https://github.com/ethersphere/gateway-proxy/blob/master/README.md) on GitHub.
+The [Swarm Gateway](https://github.com/ethersphere/swarm-gateway) is the standard way to expose a Bee node over HTTP.
 
-### Public Gateway
+:::info
+Another tool which is currently popular for running Bee in gateway mode is [Gateway Proxy](https://github.com/ethersphere/gateway-proxy). It offers several features not yet included in Swarm Gateway. However, since it is set for deprecation, unless you have a specific need, it is recommended to use Swarm Gateway instead.
+:::
 
-The tool can be used to set up a public gateway which can be used to host public facing applications or websites to users on the web who aren't running Bee nodes.
+It acts as a reverse proxy that runs in front of a Bee node, allowing you to expose your node publicly. It proxies the Bee HTTP API and content endpoints, while optionally adding access control, postage batch auto-buy, and other optional features.
+
+### Public Access to Swarm
+
+A gateway can be used to run a public endpoint that allows users to:
+
+* Access content stored on Swarm using standard HTTP URLs
+* Browse websites hosted on Swarm
+* Interact with Swarm through a familiar web interface
+
+This makes Swarm content accessible to any web client, even if the user is not running a Bee node locally.
+
+### Authentication, Access Control, and Policy
+
+The Swarm Gateway also acts as an access control and content moderation layer in front of a Bee node.
+
+Rather than exposing a Bee node directly to the public internet, the gateway allows operators to place a managed HTTP interface in front of it. Through this interface, the gateway can:
+
+* Expose a Bee node through a single public HTTP endpoint
+* Restrict or control uploads and other sensitive operations
+* Require authentication for selected endpoints or request types
+* Apply basic access control and usage policies before requests reach the Bee node
+
+This makes it possible to run public, private, or semi-public gateways while retaining control over how the underlying Bee node is used.
+
+For production deployments, the gateway is typically run behind an HTTPS reverse proxy to ensure encrypted connections.
 
 ### Stamp Management
 
-In addition to acting as a proxy, it also includes convenient features for managing stamps such as automatically buying new stamps or automatically extending the life of existing stamps.
+The Swarm Gateway can optionally manage postage stamps on behalf of the operator, including:
+
+* Automatically buying new batches
+* Monitoring batch usage and expiration
+* Keeping batches alive based on specified TTL
+
+This is especially useful for gateways that accept uploads from users or applications.
 
-### Security
 
-Authentication can also be enabled so that only authorized requests are fulfilled. This is a useful feature for protecting your node if its API endpoint is publicly exposed. 
+## Setting up a Gateway
 
+For a step by step guide on setting up a gateway yourself, refer to the [guide in the Develop on Swarm section](/docs/develop/gateway-proxy/).
diff --git a/sidebars.js b/sidebars.js
@@ -91,7 +91,8 @@ module.exports = {
         'develop/upload-and-download',
         'develop/host-your-website',
         'develop/files',
-        'develop/routing',        
+        'develop/routing', 
+        'develop/gateway-proxy',       
         // 'develop/dynamic-content',
         'develop/act',
       ],
