Skip to main content

Upload a Directory

It is possible to use Bee to upload directories of files all at once.

tip

Comfortable with nodeJS and JavaScript? Check out swarm-cli, a command line tool you can use to easily interact with your Bee node!

info

If an uploaded directory contains an index.html file, when you navigate to the directory in a web browser it will automatically be served to users from our Swarm gateways as if it were a website hosted by a normal web server. Use this feature to host your unstoppable website on Swarm!

This feature makes use of the tar command line utility to package the directory into a single file that can then be uploaded to the Bee API for processing and distributed into the swarm for later retrieval.

caution

GZIP compression is not supported in the current version of Bee, so make sure not to use the -z flag when using the tar command!

Upload the Directory Containing Your Website​

First, use the tar command line utility to create an archive containing all the files of your directory. If uploading a website, we must take care to ensure that the index.html file is at the root of the directory tree.

tree my_website
>
my_website
├── assets
│   └── style.css
├── index.html
└── error.html

Use the following command to ensure that the tar package maintains the correct directory structure:

cd my_website
tar -cf ../my_website.tar .
cd ..

Next, simply POST the tar file as binary data to Bee's dir endpoint, taking care to include the header Content Type: application/x-tar.

info

In order to upload your data to swarm, you must agree to burn some of your xBZZ to signify to storer and fowarder nodes that the content is important. Before you progress to the next step, you must buy stamps! See this guide on how to purchase an appropriate batch of stamps.

curl \
    -X POST \
    -H "Content-Type: application/x-tar" \
    -H "Swarm-Index-Document: index.html" \
    -H "Swarm-Error-Document: error.html" \
    -H "Swarm-Collection: true" \
    -H "Swarm-Postage-Batch-Id: 78a26be9b42317fe6f0cbea3e47cbd0cf34f533db4e9c91cf92be40eb2968264" \
    --data-binary @my_website.tar http://localhost:1633/bzz
info

For instances where a single page app has a JavaScript router that handles url queries itself, simply pass index.html as the error document. Bee will pass over control to the JavaScript served by the index.html file in the circumstance that a path does not yield a file from the manifest.

When the upload is successful, Bee will return a JSON document containing the Swarm Reference.

{
  "reference": "b25c89a401d9f26811680476619a1eb4a4e189e614bc6161cbfd8b343214917b"
}

Now, simply navigate your browser to view the reference using the bzz endpoint and your website will be served!

http://localhost:1633/bzz/b25c89a...214917b/

Other files are served at their relative paths, e.g:

http://localhost:1633/bzz/b25c89a...214917b/assets/style.css

Once your data has been fully processed into the network, you will then be able to retrieve it from any Bee node.

https://gateway.ethswarm.org/bzz/b25c89a...214917b/index.html

If you are not able to download your file from a different Bee node, you may be experiencing connection issues, see troubleshooting connectivity for assistance.