Skip to main content

Deploy a Local Portal

To view a website deployed using Walrus Sites, you must use a Sites Portal. A portal retrieves site resources from Walrus and their corresponding Sui objects before serving the site in your browser. You can browse any Walrus Site deployed on Mainnet or Testnet using a Sites Portal.

Use Docker to deploy a Sites Portal locally. There are no Testnet portals hosted for public good, and Mainnet sites must use a SuiNS domain name to be resolved via the Walrus Foundation's public Mainnet portal.

Programmatic installation​

The local-docker-portal.sh script automates portal configuration and startup. It reads the version of your locally installed site-builder, generates a portal-config.yaml file, and runs the corresponding Docker image.

Download the script:

$ curl -O https://raw.githubusercontent.com/MystenLabs/walrus-sites/main/scripts/local-docker-portal.sh
$ chmod +x local-docker-portal.sh

To run the script, it requires the target network (mainnet or testnet) as its only argument, with an optional second argument to override the default landing page.

$ ./local-docker-portal.sh <network>
$ ./local-docker-portal.sh mainnet

Run with a custom landing page​

Pass a Base36-encoded Sui object ID as the second argument to override the default landing page served at the portal root.

$ ./local-docker-portal.sh mainnet 46f3881sp4r55fc6pcao9t93bieeejl4vr4k2uv8u4wwyx1a93
tip

To obtain the Base36 ID of a site you have published, use the convert command:

$ site-builder convert <hex-object-id>

Once the portal is running, open your browser and navigate to:

http://<site-object-id-b36>.localhost:3000

Replace <site-object-id-b36> with the Base36-encoded object ID of the Walrus Site you want to view.

info

The portal runs on port 3000 by default. The --rm flag in the local-docker-portal.sh script ensures the Docker container is removed automatically when stopped.

Manual configuration​

Use this method if you need to customize the portal configuration beyond what the script supports, such as enabling allowlists, blocklists, or custom RPC endpoints.

Docker​

The portal Docker image version must match your site-builder version. Run the following command to get the version tag:

$ site-builder -V | awk '{ print $2 }' | awk -F - '{ printf("v%s\n", $1) }'

This outputs a version string like v0.7.3.

Create a file named portal-config.yaml with the following content. Adjust the values for the network you are deploying on.

network: mainnet
site_package: "0x26eb7ee8688da02c5f671679524e379f0b837a12f1d1d799f255b7eea260ad27"
landing_page_oid_b36: "46f3881sp4r55fc6pcao9t93bieeejl4vr4k2uv8u4wwyx1a93"
enable_allowlist: false
enable_blocklist: false
b36_domain_resolution: true
rpc_urls:
  - url: https://fullnode.mainnet.sui.io:443
    retries: 2
    metric: 100
aggregator_urls:
  - url: https://aggregator.walrus-mainnet.walrus.space
    retries: 3
    metric: 100

Then run the Docker container:

docker run \
  -it \
  --rm \
  -v /path/to/portal-config.yaml:/etc/walrus-sites/portal-config.yaml:ro \
  -p 3000:3000 \
  mysten/walrus-sites-server-portal:mainnet-

Replace /path/to/portal-config.yaml with the absolute path to your config file, and <version> with the version string.

Open your browser and navigate to:

http://<site-object-id-b36>.localhost:3000

Local development​

This requires having the bun tool installed:

$ bun --version

If not installed, run the following command:

$ curl -fsSL https://bun.sh/install | bash

Install the dependencies:

$ cd portal
$ bun install

To run a server-side portal, copy the example portal-config.yaml for your target network and start the server. The server portal is served at localhost:3000.

# Mainnet
$ cp server/portal-config.mainnet.example.yaml server/portal-config.yaml

# Testnet
$ cp server/portal-config.testnet.example.yaml server/portal-config.yaml

$ bun run server

To run a service-worker portal, copy the example .env.local for your target network and start the worker. The service-worker portal is served at localhost:8080.

# Mainnet
$ cp worker/.env.mainnet.example worker/.env.local

# Testnet
$ cp worker/.env.testnet.example worker/.env.local

$ bun run build:worker
$ bun run worker