How to Build Your Own Walrus Site

Want to try something new with web hosting? Walrus Sites lets you create decentralized, serverless websites using the Sui blockchain and Walrus technology. Think of it as hosting your site without worrying about servers, plus some useful blockchain perks like NFT integration and tamper-proof reliability.

This guide will walk you through everything—from creation to publishing to keeping your site updated. You’ll also find code snippets and examples to help you get started. 

If you are not sure if Walrus Site is for you, here are some of the most exciting features:

1. Serverless Deployment: Publish sites without managing servers or complex configurations. With Walrus, your files and metadata are stored directly on the blockchain, eliminating the need for traditional hosting solutions. For example, you could host game frontends that interact directly with smart contracts.
2. NFT Integration: Link sites to Sui objects, enabling features like personalized websites for NFTs. For instance, showcase an NFT collection or provide exclusive content accessible only to token holders.
3. Ownership and Flexibility: Sites are owned by Sui addresses, meaning you have full control. They can be transferred or updated at any time. For easier navigation, use the SuiNS naming system to assign memorable, human-readable domain names.
4. High Availability: Walrus Sites are decentralized and tamper-proof, ensuring resilience against downtime or censorship. For example, you could create a decentralized blog, owning your content without relying on centralized platforms.
5. Programmability: Enhance interactivity by integrating Sui wallets and leveraging Sui’s smart contracts for dynamic site functionality.

For a quick demo, visit the NFT minting example at https://flatland.walrus.site/.

Let’s dive in!

Setting Up the Site Builder

Walrus Sites consist of two main components:

1. Frontend Files: Your static assets (HTML, CSS, JS, etc.) are stored on Walrus, ensuring they’re decentralized and tamper-proof.
2. Metadata: Stored on the Sui blockchain, the metadata points to the Walrus blob IDs for your site’s assets.

Prerequisites:

To begin, ensure you have the following:

• A recent version of Rust installed on your system. Rust is essential for compiling and running Sui and Walrus tools.
• Walrus and Sui setup completed. Follow the official documentation to install the necessary dependencies.

Installation:

Download the pre-built site-builder binary for your operating system. This tool is used to create, publish, and update Walrus Sites.

You can download the latest build from Google Cloud Storage (GCS) bucket (correctly setting the $SYSTEM variable):

SYSTEM= # set this to your system: ubuntu-x86_64, ubuntu-x86_64-generic, macos-x86_64, macos-arm64, windows-x86_64.exe
curl https://storage.googleapis.com/mysten-walrus-binaries/site-builder-testnet-latest-$SYSTEM -o site-builder
mv site-builder /usr/local/bin/

Once this is done, you should be able to simply type site-builder in your terminal to verify the installation.

$ site-builder
Usage: site-builder [OPTIONS] <COMMAND>

Commands:
  publish  Publish a new site on Sui
  update   Update an existing site
  convert  Convert an object ID in hex format to the equivalent Base36
               format
  sitemap  Show the pages composing the Walrus site at the given object ID
  help     Print this message or the help of the given subcommand(s)

Configuration:

The sites-config.yaml file is critical for defining the behavior and settings of the site-builder. Here’s an example configuration:

# module: site
# portal: walrus.site
package: 0xdf9033cac39b7a9b9f76fb6896c9fc5283ba730d6976a2b1d85ad1e6036c3272
# general:
#   rpc_url: https://fullnode.testnet.sui.io:443
#   wallet: /path/to/.sui/sui_config/client.yaml
#   walrus_binary: /path/to/walrus
#   walrus_config: /path/to/devnet_deployment/client_config.yaml
#   gas_budget: 500000000

As you can see, the configuration file is quite simple. The only mandatory field is the package field, which represents the Sui object ID of the Walrus Sites smart contract. You can find the latest version of the package in the Walrus Sites repository on the testnet branch.

You can also define the location of the sites-config.yaml file using the --config flag when running the site-builder commands like so:

site-builder --config /path/to/sites-config.yaml publish <build-directory-of-a-site>

To get started quickly, download the default configuration, and place it in one of the aforementioned default locations. To illustrate, we will use the ~/.config/walrus directory, like so:

curl https://raw.githubusercontent.com/MystenLabs/walrus-sites/refs/heads/testnet/sites-config.yaml -o ~/.config/walrus/sites-config.yaml

Publishing a Walrus Site

Step 1: Prepare Your Site Files

Before publishing, ensure you have everything installed and configured correctly in the previous step. The site-builder tool works by uploading a directory of web files to Walrus and linking them to Sui with metadata. The directory must contain an index.html file at its root, which serves as the entry point for your Walrus site.

To get started, clone the example Walrus sites repository, which contains various sample sites:

git clone https://github.com/MystenLabs/example-walrus-sites.git && cd example-walrus-sites

For this guide, we will use the walrus-snake game as our example.

Step 2: Publish Your Site

Since we have already set up the walrus and site-builder binaries and configuration, publishing the site is straightforward. Run the following command to publish the walrus-snake site:

site-builder publish ./walrus-snake --epochs 100

• The --epochs 100 flag specifies that the site should remain active for 100 epochs (each epoch on Walrus Testnet lasts two days).
• Once the process completes, you’ll receive output confirming that resources were created and providing a site object ID and URL where the site can be accessed.

Example output:

Execution completed
Resource operations performed:
  - created resource /Oi-Regular.ttf with blob ID 76npyqDyGF10-jP_ov-UBHpi-RaRFnxcWgslueGEfr0
  - created resource /file.svg with blob ID w70pYgtLmi--38Jg1sTGaLlZkQtximNMHXjxDQdXKa0
  - created resource /index.html with blob ID LVLk9VSnBrEgQ2HJHAgU3p8IarKypQpfn38aSeUZzzE
  - created resource /walrus.svg with blob ID 866UDjMAy_BB8SsTcgjGEOFp2uAO9BbcVbLh5-_oBNE
The site routes were modified

Created new site: test site
New site object ID: [your_site_object_ID]
Browse the resulting site at: https://[your_url_ID].walrus.site

Step 3: Extend Expiration

By default, your site will only stay active for the duration you specified in epochs. To extend its availability, use the update command with additional epochs:

site-builder update --epochs 100 ./walrus-snake 0x407a3081...

• Replace 0x407a3081... with the actual site object ID from your output.
• The maximum allowed duration is 183 epochs.

Also keep in mind that:

• The publishing process generates a Walrus blob for each file in your site directory.
• The site object ID allows you to track your site on the Sui Explorer and set a SuiNS name if needed.
• The site-builder tool uses a default sites-config.yaml file to manage configuration settings. For advanced customization, refer to the Advanced Configuration section in the official documentation.

Updating a Walrus Site

If you need to update your site, such as changing the title from "Eat all the blobs!" to "Glob all the Blobs!", follow these steps:

1. Edit the index.html file inside the ./walrus-snake/ directory to reflect the desired changes.
2. Run the following command to update your existing site, specifying the directory and the object ID of your Walrus site:

site-builder update --epochs 100 ./walrus-snake 0x407a3081...

• Replace 0x407a3081... with your actual site object ID.
• The update command will replace only the modified files, keeping the rest intact.

Example output:

Execution completed
Resource operations performed:
  - deleted resource /index.html with blob ID LVLk9VSnBrEgQ2HJHAgU3p8IarKypQpfn38aSeUZzzE
  - created resource /index.html with blob ID pcZaosgEFtmP2d2IV3QdVhnUjajvQzY2ev8d9U_D5VY
The site routes were left unchanged

Site object ID: [your_site_object_ID]
Browse the resulting site at: https://[your_url_ID].walrus.site

To extend the expiration date of an already-published site, use the update command with the --force flag and specify additional epochs:

site-builder update --force --epochs 100 ./walrus-snake 0x407a3081...

This ensures your site remains accessible for the specified duration without republishing.

Assigning a SuiNS Name

Browsing a URL like https://[your_url_ID].walrus.site  is not particularly nice. Therefore, Walrus Sites allows to use SuiNS names (this is like DNS for Sui) to assign a human-readable name to a Walrus Site. To do so, you simply have to get a SuiNS name you like, and point it to the object ID of the Walrus Site (as provided by the publish or update commands).

Step 1: Buy a Domain

Go to https://testnet.suins.io to purchase a domain name. SuiNS allows you to map a human-readable domain to your Walrus Site.

Step 2: Link to Your Site

Once you’ve purchased a domain, use the “Link To Walrus Site” feature to associate the domain with your site’s object ID.

After mapping, the domain your purchased becomes your site’s new, user-friendly URL. For example, you can check this game https://walrusgame.walrus.site, that has been adapted from this Gist.

Useful Site Builder commands

The site-builder tool provides several commands to help you publish, update, and manage your Walrus Site. Below is a breakdown of the most important commands.

Quick Tip

Use the --help flag to get more details about the CLI and its commands:

• View general help: site-builder --help
  
• Get help for a specific command: site-builder update --help
  

publish – Deploy a New Site

The publish command creates a new Walrus Site on Sui by uploading the specified directory. It generates Walrus blobs for each file and stores them on the network.

Key Flags

• --epochs <number>: Specifies how long the site will remain active before expiring.
  • Each epoch on Walrus Testnet lasts two days.
  • The maximum duration is 183 epochs (approximately one year).
  • If you plan to keep your site online for several months, choose a higher epoch count.
• --list-directory: If your directory doesn't include an index.html, this flag generates a simple file browser so users can view and download files.

Example:

site-builder publish ./mywebsite --epochs 120

For advanced publishing options, refer to the Specifying Headers and Routing section.

update – Modify an Existing Site

The update command works like publish, but instead of creating a new site, it updates an existing one. It requires the Sui object ID of the Walrus Site you want to modify.

Important Notes

• The wallet you use to call update must be the owner of the Walrus Site object.
• Use this command to replace files, modify content, or extend the site's expiration period.

Example:

site-builder update --epochs 100 ./my-website 0x407a3081...

convert – Get the Site’s Subdomain

The convert command translates a hex-format object ID into its Base36 equivalent. This is useful for finding the subdomain where your Walrus Site is hosted.

Example:

site-builder convert 0x407a3081...

sitemap – View Site Resources

The sitemap command displays a list of all resources that make up a Walrus Site. This is helpful for inspecting which files are currently stored.

Example:

site-builder sitemap 0x407a3081...

list-directory – Browse Uploaded Files

If you’re not using an index.html, the list-directory command allows you to view all files available in a published directory. This is especially useful when hosting raw assets like images, documents, or static files.

For an example of a file-browsing site, check https://bin.blob.store.

With this guide, you now have everything needed to create, publish, and manage your own Walrus Site. We would also encourage you to take a look at the more technical overview of Walrus Sites, to better understand the mechanisms behind the scene - https://docs.walrus.site/walrus-sites/overview.html

Start building today and unleash the potential of decentralized web hosting!