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 through Walrus Foundation's public Mainnet portal.

Clone the walrus-sites repository and check out the stable branch:

$ git clone https://github.com/MystenLabs/walrus-sites.git
$ cd walrus-sites
$ git checkout mainnet

Copy the template configuration file for your target network and rename it to portal-config.yaml:

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

Run the Docker container:

docker run \
  -it \
  --rm \
  -v $(pwd)/portal/server/portal-config.yaml:/portal-config.yaml:ro \
  -e PORTAL_CONFIG=/portal-config.yaml \
  -p 3000:3000 \
  mysten/walrus-sites-server-portal:mainnet-v2.8.0

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

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

Be sure that version tag matches the tag of the image you run: the mysten/walrus-sites-server-portal:mainnet-v2.8.0 tag shown above is only an example, so replace v2.8.0 with the version that the preceding command reports for your site-builder.

The command maps the container port with -p 3000:3000, so port 3000 must be free on your host. Once the Docker container is running, open your browser and navigate to the following URL:

http://localhost:3000

To view a specific Walrus Site, navigate to the following URL instead:

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. To obtain the Base36 ID of a site you published, use the convert command:

$ site-builder convert HEX_OBJECT_ID

Local development (server portal on port 3000, service-worker portal on port 8080)​

This method requires bun. Check whether bun is installed:

$ bun --version

If bun is not installed, run the following command:

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

Install the dependencies:

$ git clone https://github.com/MystenLabs/walrus-sites.git
$ cd walrus-sites/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 runs 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 view a specific Walrus Site on the server portal, use the same http://SITE_OBJECT_ID_B36.localhost:3000 URL pattern as the Docker portal.

To run a service-worker portal, copy the example .env.local for your target network and start the worker. The service-worker portal runs 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