Publishing a Walrus Site

The site-builder works by uploading a directory of files produced by any web framework to Walrus and adding the relevant metadata to Sui. This directory should have a file called index.html in its root, which is the entry point to the Walrus Site. The example Walrus sites repository contains multiple kinds of sites that you can use for reference.

Start by publishing the site for the walrus-snake game.

First, clone the repository of the examples:

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

Since the walrus and site-builder binaries and configuration are placed in their default locations, deploying the ./walrus-snake site is as simple as calling again the deploy command:

$ site-builder --context=testnet deploy ./walrus-snake --epochs 1

Depending on the network, the duration of an epoch might vary. Currently on Walrus Testnet, the duration of an epoch is 1 day. On Mainnet, the duration of an epoch is 2 weeks.

After deploying, how you access your site depends on which network you used:

Mainnet sites: Can be accessed through any mainnet portal. https://wal.app serves Walrus Sites on mainnet by resolving SuiNS names that point to them.
Testnet sites: Can be accessed through any testnet portal. Walrus Foundation does not operate a testnet portal. You can self-host or run one locally.

The end of the output should look like the following:

Execution completed
Resource operations performed:
  - created resource /Oi-Regular.ttf with quilt patch ID Jqz2KSMu18pygjkC-WVEQqtUZRo18-cuf_566VZSxVoBHgAjAg
  - created resource /file.svg with quilt patch ID Jqz2KSMu18pygjkC-WVEQqtUZRo18-cuf_566VZSxVoBAQAMAA
  - created resource /index.html with quilt patch ID Jqz2KSMu18pygjkC-WVEQqtUZRo18-cuf_566VZSxVoBDAAZAA
  - created resource /walrus.svg with quilt patch ID Jqz2KSMu18pygjkC-WVEQqtUZRo18-cuf_566VZSxVoBGQAeAA
The site routes were modified.
Metadata updated.
The site name has been updated.

Created new site!
New site object ID: 0x617221edd060dafb4070b73160ebf535e1516bf7f246890ed35190eba786d7ac
⚠ wal.app only supports sites deployed on mainnet.
    To browse your testnet site, you need to self-host a portal:
    1. For local development: http://2ffmxm7jmglccr79htmpdbaeqezp2krgftue5pfq9f83tdqjsc.localhost:3000
    2. For public sharing: http://2ffmxm7jmglccr79htmpdbaeqezp2krgftue5pfq9f83tdqjsc.yourdomain.com:3000

    📖 Setup instructions: https://docs.wal.app/walrus-sites/portal.html#running-the-portal-locally

    💡 Tip: You may also bring your own domain (https://docs.wal.app/walrus-sites/bring-your-own-domain.html)
            or find third-party hosted testnet portals.

Keep in mind that option 2 is only available on mainnet. For testnet sites, use option 1; see the portal setup guide for instructions.

This output tells you that, for each file in the folder, a new Walrus quilt was created with a respective quilt ID. Further, it prints the object ID of the Walrus Site object on Sui so you can look in an explorer and use it to set the SuiNS name. Finally, the URL at which you can browse the site is displayed. The deploy command also saves this new site object ID to the ws-resources.json.

Here the default sites-config.yaml is implicitly used as the config for the site-builder that was set up previously in the installation section. The configuration file is necessary to ensure that the site-builder knows the correct Sui package for the Walrus Sites logic.

More details on the configuration of the site-builder can be found under the advanced configuration section.

Update the site

If you want to update the content of the site, for example by changing the title from "eat all the blobs!" to "Glob all the Blobs!", first, make this text edit in the ./walrus-snake/index.html file.

Then, you can update the existing site by running the deploy command again. The deploy command uses the site object ID stored in ws-resources.json from the initial deployment to identify which site to update. You do not need to specify the object ID manually:

site-builder --context=testnet deploy --epochs 1 ./walrus-snake

The wallet you are using must be the owner of the Walrus Site object to be able to update it.

The output this time should be:

Execution completed
Resource operations performed:
  - deleted resource /Oi-Regular.ttf with quilt patch ID Jqz2KSMu18pygjkC-WVEQqtUZRo18-cuf_566VZSxVoBHgAjAg
  - deleted resource /file.svg with quilt patch ID Jqz2KSMu18pygjkC-WVEQqtUZRo18-cuf_566VZSxVoBAQAMAA
  - deleted resource /index.html with quilt patch ID Jqz2KSMu18pygjkC-WVEQqtUZRo18-cuf_566VZSxVoBDAAZAA
  - deleted resource /walrus.svg with quilt patch ID Jqz2KSMu18pygjkC-WVEQqtUZRo18-cuf_566VZSxVoBGQAeAA
  - created resource /Oi-Regular.ttf with quilt patch ID BjJAfHLJKMDZ0tFZaLKVw0R74re5RG65-xNhaZ5uwowBHgAjAg
  - created resource /file.svg with quilt patch ID BjJAfHLJKMDZ0tFZaLKVw0R74re5RG65-xNhaZ5uwowBAQAMAA
  - created resource /index.html with quilt patch ID BjJAfHLJKMDZ0tFZaLKVw0R74re5RG65-xNhaZ5uwowBDAAZAA
  - created resource /walrus.svg with quilt patch ID BjJAfHLJKMDZ0tFZaLKVw0R74re5RG65-xNhaZ5uwowBGQAeAA
The site routes were left unchanged.
No Metadata updated.
Site name has not been updated.

Site object ID: 0x4a1be0fb330215c532d74c70d34bc35f185cc7ce025e04b9ad42bc4ac8eda5ce
⚠ wal.app only supports sites deployed on mainnet.
    To browse your testnet site, you need to self-host a portal:
    1. For local development: http://1uhtkoi4t8swxbn2y0mec0l94368nhq2wa1xlh1kc1e43fbzym.localhost:3000
    2. For public sharing: http://1uhtkoi4t8swxbn2y0mec0l94368nhq2wa1xlh1kc1e43fbzym.yourdomain.com:3000

    📖 Setup instructions: https://docs.wal.app/walrus-sites/portal.html#running-the-portal-locally

    💡 Tip: You may also bring your own domain (https://docs.wal.app/walrus-sites/bring-your-own-domain.html)
            or find third-party hosted testnet portals.

Browsing to the provided URL should reflect the change. You've updated the site.

All site resources are deleted (because they all belong to the same quilt), even those that haven't been modified. They then get re-uploaded together as a single quilt, where each resource corresponds to a quilt patch. This happens because the site-builder stores files on Walrus using quilts. This approach offers significant benefits, including faster upload speeds and lower storage costs, especially when uploading many small files. The only disadvantage is that you cannot update a single file within a quilt. If even a tiny file changes, the entire quilt must be re-uploaded. Upcoming versions of the site-builder will introduce optimizations in the storage usage between updates. View a detailed overview of Quilts.

Update the site​

Update the site