From c6cafd9c755d3c1b51cec212718cdbe391ca8992 Mon Sep 17 00:00:00 2001 From: NoahMaizels Date: Mon, 2 Feb 2026 17:32:15 +0700 Subject: [PATCH 1/3] edits --- docs/develop/gateway.md | 69 ++++++++++++++++++++++++++++++++--------- 1 file changed, 55 insertions(+), 14 deletions(-) diff --git a/docs/develop/gateway.md b/docs/develop/gateway.md index de13b82a..0841fadc 100644 --- a/docs/develop/gateway.md +++ b/docs/develop/gateway.md @@ -3,15 +3,9 @@ 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. +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) +## Part 1 - Basic 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). @@ -145,13 +139,41 @@ swarm-cli upload test.txt This will print a Swarm reference. -Open the file through the gateway: +Open the file through the gateway in your browser: -```text +```bash http://your-domain.example/bzz// ``` -The file contents should be returned. +Or from the terminal: + +```bash +url -i http://your-domain.example/bzz// +``` + +The file contents should be returned. + +Example terminal output: + +```bash +600/ +HTTP/1.1 200 OK +X-Powered-By: Express +Access-Control-Allow-Origin: * +Access-Control-Allow-Methods: GET, POST, OPTIONS +Access-Control-Allow-Headers: Content-Type, Authorization, swarm-postage-batch-id, swarm-deferred-upload +accept-ranges: bytes +access-control-expose-headers: Content-Disposition +content-disposition: inline; filename="test.txt" +content-type: text/plain; charset=utf-8 +date: Mon, 02 Feb 2026 10:21:39 GMT +Content-Length: 12 +ETag: W/"c-5RZWYiFSSX7yHMJRTWWjxA9B9oo" +Connection: keep-alive +Keep-Alive: timeout=5 + +hello swarm +``` ### 7. Optional: restrict uploads using authentication @@ -169,11 +191,13 @@ Example (add these lines to the `docker run` command): -e SOFT_AUTH="true" \ ``` +See the [Swarm Gateway README](https://github.com/ethersphere/swarm-gateway) for more information about authentication and other options. + At this point, you have: * A working Swarm HTTP gateway * Connected to your Bee node -* Exposing content publicly over `/bzz/` +* Content accessible publicly over `/bzz/` 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. @@ -245,12 +269,12 @@ cd ~/caddy Create a file named `Caddyfile`: ```bash -nano Caddyfile +vim Caddyfile ``` Add the following configuration (replace the domain): -```caddy +```bash your-domain.example { reverse_proxy swarm-gateway:3000 } @@ -299,3 +323,20 @@ You can also verify that HTTP is redirected to HTTPS: curl -I http://your-domain.example/health ``` +Example terminal output: + +```bash +HTTP/1.1 308 Permanent Redirect +Connection: close +Location: https://your-domain.example/health +Server: Caddy +Date: Mon, 02 Feb 2026 10:31:17 GMT +``` + +## Part 3 — Options + +:::caution +This section is under construction. Further guidance will be available in the near future. For the time being, please join the [#builders channel](https://discord.gg/udBg6ctH) on the Swarm Discord server. +::: + +You can find a [list](https://github.com/ethersphere/swarm-gateway/blob/main/README.md#overview) of all available options on the [Swarm Gateway README](github.com/ethersphere/swarm-gateway/blob/main/README.md) on GitHub. [Database options](https://github.com/ethersphere/swarm-gateway/blob/main/README.md#database) can also be set using the DATABASE_CONFIG environment variable. \ No newline at end of file From c4e27d30bc31881e6c59a9fd7e98647fd9574140 Mon Sep 17 00:00:00 2001 From: NoahMaizels Date: Tue, 3 Feb 2026 20:51:04 +0700 Subject: [PATCH 2/3] update url and redirect --- docs/develop/introduction.md | 2 +- docs/develop/tools-and-features/gateway-proxy.md | 6 +++--- docusaurus.config.mjs | 2 ++ sidebars.js | 4 ++-- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/develop/introduction.md b/docs/develop/introduction.md index 55e6b2a9..aaac5eca 100644 --- a/docs/develop/introduction.md +++ b/docs/develop/introduction.md @@ -81,7 +81,7 @@ This is the go-to starting point for web3 developers who want to build with Swar
  • - +

    Run a Gateway

    Run your own Swarm HTTP gateway to serve content from the network and make it accessible to browsers and other HTTP clients. diff --git a/docs/develop/tools-and-features/gateway-proxy.md b/docs/develop/tools-and-features/gateway-proxy.md index 1b285345..84bcff6c 100644 --- a/docs/develop/tools-and-features/gateway-proxy.md +++ b/docs/develop/tools-and-features/gateway-proxy.md @@ -1,6 +1,6 @@ --- -title: Gateway Proxy -id: gateway-proxy +title: Swarm Gateway +id: swarm-gateway --- The [Swarm Gateway](https://github.com/ethersphere/swarm-gateway) is the standard way to expose a Bee node over HTTP. @@ -49,4 +49,4 @@ This is especially useful for gateways that accept uploads from users or applica ## 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/). \ No newline at end of file +For a step by step guide on setting up a gateway yourself, refer to the [guide in the Develop on Swarm section](/docs/develop/run-a-gateway/). \ No newline at end of file diff --git a/docusaurus.config.mjs b/docusaurus.config.mjs index 52a8c957..8a60a6e6 100644 --- a/docusaurus.config.mjs +++ b/docusaurus.config.mjs @@ -80,6 +80,8 @@ export default { { to: '/docs/develop/act', from: '/docs/develop/access-the-swarm/act' }, { to: '/docs/develop/ultra-light-nodes', from: '/docs/develop/access-the-swarm/ultra-light-nodes' }, { to: '/docs/develop/introduction', from: '/docs/develop/access-the-swarm' }, + { to: '/docs/develop/run-a-gateway', from: '/docs/develop/gateway-proxy' }, + ], }, ], diff --git a/sidebars.js b/sidebars.js index 29d814cc..33f45b7d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -92,7 +92,7 @@ module.exports = { 'develop/host-your-website', 'develop/files', 'develop/routing', - 'develop/gateway-proxy', + 'develop/run-a-gateway', // 'develop/dynamic-content', 'develop/act', ], @@ -106,7 +106,7 @@ module.exports = { 'develop/tools-and-features/introduction', 'develop/tools-and-features/buy-a-stamp-batch', 'develop/tools-and-features/bee-js', - 'develop/tools-and-features/gateway-proxy', + 'develop/tools-and-features/swarm-gateway', 'develop/tools-and-features/chunk-types', 'develop/tools-and-features/feeds', 'develop/tools-and-features/manifests', From fbcba15d7ff13c76586e486120e5d59e786b2ccf Mon Sep 17 00:00:00 2001 From: NoahMaizels Date: Tue, 3 Feb 2026 21:07:09 +0700 Subject: [PATCH 3/3] update id --- docs/develop/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/gateway.md b/docs/develop/gateway.md index 0841fadc..5be2d07a 100644 --- a/docs/develop/gateway.md +++ b/docs/develop/gateway.md @@ -1,6 +1,6 @@ --- title: Run a Gateway -id: gateway-proxy +id: run-a-gateway --- 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.