From 3caa0857484d8da93227dd927583ebcc5f238142 Mon Sep 17 00:00:00 2001 From: NoahMaizels Date: Mon, 27 Oct 2025 21:00:04 +0700 Subject: [PATCH 1/9] first draft of host a website page --- .../access-the-swarm/host-your-website.md | 195 +++++++++++++----- docs/develop/introduction.md | 4 +- 2 files changed, 143 insertions(+), 56 deletions(-) diff --git a/docs/develop/access-the-swarm/host-your-website.md b/docs/develop/access-the-swarm/host-your-website.md index 97dc00b0..d6c1f8e9 100644 --- a/docs/develop/access-the-swarm/host-your-website.md +++ b/docs/develop/access-the-swarm/host-your-website.md @@ -3,97 +3,184 @@ title: Host a Webpage id: host-your-website --- -Bee treats ENS as a first class citizen, wherever you can use a Swarm reference, you can also use an ENS domain where the `content` ENS Resolver record is set to be a `bzz://` reference. +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -:::info -You may substitute ENS names for Swarm references in any of the [API methods](/api/) where you would normally use a Swarm reference. -::: +# Hosting a Website on Swarm and Linking it to ENS -### Enable ENS on Your Node +This guide explains how to host a static website on Bee using `swarm-cli` and make it accessible through [Ethereum Name Service (ENS)](https://ens.domains/). -In order to resolve ENS names using your API endpoints, you must specify a valid ENS resolver endpoint when starting your Bee node. We recommend that users run their own Geth node, which can be trusted absolutely, however service providers such as [https://cloudflare-eth.com](https://cloudflare-eth.com) or [Infura](https://infura.io) may suffice. Public gateways such as [gateway.ethswarm.org](https://gateway.ethswarm.org) will also usually provide ENS resolution. +Part one covers uploading and accessing your site through the raw Swarm hash. -```bash -bee start --resolver-options "https://cloudflare-eth.com" +Part two shows how to register your Swarm hash with your ENS domain so it can be easily accessed by anyone through public ENS gateways like `eth.limo`, `bzz.link`, or `localhost` on a Bee node. + +## 1. Hosting and Accessing Your Website on Swarm + +### Prerequisites + +* A running Bee node (either a [standard installation](/docs/bee/installation/quick-start) or [Swarm Desktop](/docs/desktop/install)) +* A valid postage batch +* [`swarm-cli` installed](https://docs.ethswarm.org/docs/bee/working-with-bee/swarm-cli) +* A valid postage stamp batch +* Your static website files (you can also use the example website files provided below) + +You can download the example website files from the [ethersphere/examples](https://github.com/ethersphere/examples) repository. + + +### Uploading the Website + +1. Go to the folder containing your website files. + +The example website files look like this: + +``` +my-website/ +├── index.html # main landing page +├── 404.html # custom error page +├── styles.css # basic styling +├── script.js # optional script +├── favicon.svg # site icon +└── robots.txt # default robots config ``` -If specifying using your `bee.yaml` configuration file, the syntax is as follows: +* `index.html` will be served by default when users visit the root URL. +* `404.html` will be served for non-existent paths. +* The other files are optional and can be customized. + + +2. Run: + + + + + +```powershell +swarm-cli upload . ` + --stamp 3d98a22f522377ae9cc2aa3bca7f352fb0ed6b16bad73f0246b0a5c155f367bc ` + --index-document index.html ` + --error-document index.html +```` + + + + ```bash -resolver-options: [ "https://cloudflare-eth.com" ] +swarm-cli upload . \ + --stamp 3d98a22f522377ae9cc2aa3bca7f352fb0ed6b16bad73f0246b0a5c155f367bc \ + --index-document index.html \ + --error-document index.html ``` -Once you have restarted your node, you should be able to see the Swarm homepage at: + + -[http://localhost:1633/bzz/swarm.eth/](http://localhost:1633/bzz/swarm.eth/) -:::info -Use the `resolver-options` flag to point the Bee resolver to any ENS compatible smart-contract on any EVM compatible chain -::: +* Replace `` with your postage batch ID. +* `--index-document` tells Bee which file to serve at the root. +* `--error-document` defines the fallback file for missing paths. -:::warning -Make sure you trust the gateway you are interacting with! To ensure that you are retrieving the correct content, run your own ENS resolver and Bee node. -::: +3. The upload will return a Swarm reference hash, for example: + +``` +cf50756e6115445fd283691673fa4ad2204849558a6f3b3f4e632440f1c3ab7c +``` -### Link an ENS domain to a website. +Copy this and save it. You’ll need it for both direct access and ENS integration. -First we will need to upload the website assets to Swarm in order to -get its Swarm reference hash, see -[uploading a directory](/docs/develop/access-the-swarm/upload-and-download) -for more information. -This time we will also include the `Swarm-Index-Document` header set to the `index.html`. This will cause Bee to serve each directories `index.html` file as default when browsing to the directory root `/` url. We will also provide a custom error page, using the `Swarm-Error-Document` header. +### Accessing the Website -In the case that your website is a single page app, where you would like to direct to the JavaScript history API powered router, you may provide the `index.html` page for both settings. +Anyone with a Bee node can now access the site using the Swarm hash you just saved: -```bash - curl -X POST -H "Content-Type: application/x-tar" -H "swarm-postage-batch-id: 81c4520b47a434738d14fd38053a32c20aaf1a36d7f35f0d86ef25c70403d7a8" -H "Swarm-Index-Document: index.html" -H "Swarm-Error-Document: index.html" --data-binary @website.tar http://localhost:1633/bzz +``` +http://localhost:1633/bzz// +``` + + + +## 2. Connecting Your Website to ENS + +Once the site is uploaded, you can make it accessible via an easy to remember ENS domain name: + +``` +https://yourname.eth.limo/ +https://yourname.bzz.link/ +``` + +or through your own node: + +``` +http://localhost:1633/bzz/yourname.eth/ ``` -```json -{ - "reference": "b25c89a401d9f26811680476619a1eb4a4e189e614bc6161cbfd8b343214917b" -} +:::tip +If the site doesn’t load from localhost, it’s probably an with the resolver RPC (the RPC endpoint for the Ethereum node used to resolve your ENS domain name). + +Some endpoints, such as: + +``` +https://cloudflare-eth.com ``` -Next, we add a `Content` record to your ENS domain's resolver contract. +may not resolve properly on localhost. + +As of the writing of this guide, both of these free and public endpoints work reliably for localhost resolution: + +``` +https://mainnet.infura.io/v3/ +https://eth-mainnet.public.blastapi.io +``` -We recommend the excellent [ENS Domains Dapp](https://app.ens.domains/) used -with the [MetaMask](https://metamask.io/) browser extension for registering and -administrating your ENS domain. +Alternatively, you can run your own Ethereum node and use that as the RPC. +::: -Once you have registered your name, and have connected MetaMask with the -relevant Ethereum account, you must first set the resolver to use the public ENS -if you have not already done so. +### Using the Official ENS Guide -First, navigate to 'My Names', and select the name you would like to link your Swarm content to. +The ENS team provides a clear walkthrough with screenshots showing how to add a content hash to your domain with their [easy to use app](https://app.ens.domains/): -Press 'Set' next to your resolver record. +[How to add a Decentralized website to an ENS name](https://support.ens.domains/en/articles/12275979-how-to-add-a-decentralized-website-to-an-ens-name) -![alt text](/img/ens-1.png "Press set resolver.") +The guide covers: -Select 'Use Public Resolver'. +* Opening your ENS domain in the ENS Manager +* Navigating to the Records tab +* Adding a Content Hash +* Confirming the transaction -![alt text](/img/ens-2.png "Use Public Resolver.") -Select '+' to add a record. +### Swarm-Specific Step -![alt text](/img/ens-3.png "Press add a record.") +When you reach Step 2 in the ENS guide (“Add content hash record”), enter your Swarm reference in the following format: -Choose the 'Content' record type from the drop down menu. +``` +bzz:// +``` -![alt text](/img/ens-4.png "Choose the content record type from the drop down menu.") +Example: -Add the Swarm reference you created earlier and press 'Save'. +``` +bzz://cf50756e6115445fd283691673fa4ad2204849558a6f3b3f4e632440f1c3ab7c +``` -![alt text](/img/ens-5.png "Add the Swarm reference you created earlier and press 'Save'.") +This works across: -Verify the Content Record has been created! +* eth.limo and bzz.link +* localhost (with a compatible RPC) +* any ENS-compatible Swarm resolver -![alt text](/img/ens-6.png "Verify the Content Record has been created.") +You do not need to encode the hash or use any additional tools. `bzz://` is sufficient. -Done! 👏 +## Summary -Now you will be able to see your website hosted using the ENS name instead of the Swarm Reference! +* Upload your website using `swarm-cli`. +* Access it directly with the Swarm hash or through your local Bee node. +* Link it to an ENS name by adding a `bzz://` content hash in the ENS Manager. +* Use a reliable RPC such as `https://eth-mainnet.public.blastapi.io` or `https://rpc.ankr.com/eth` or your own Ethereum node RPC if you want localhost resolution to work. -![alt text](/img/ens-7.png "View your website using the ENS name.") +This setup gives you a fully decentralized website hosted on Swarm and accessible through ENS without relying on centralized infrastructure. diff --git a/docs/develop/introduction.md b/docs/develop/introduction.md index b44049a8..49490c60 100644 --- a/docs/develop/introduction.md +++ b/docs/develop/introduction.md @@ -52,16 +52,16 @@ pagination_next: null Open guide -