Skip to main content

Walrus Sites Portal

The term portal is used to indicate any technology that is used to access and browse Walrus Sites. Currently, only a server-side portal is served at https://wal.app.

https://wal.app only serves sites deployed on mainnet, linked with SuiNS names. You can run a portal to access Mainnet sites as well. Walrus Foundation does not maintain a portal that serves Testnet Walrus Sites. To access sites deployed on Testnet you can either use a third party Testnet portal, self-host one, or run one locally.

Known portals​

A list of known portals is maintained. Portals can self-identify by opening a PR that adds an entry to docs/book/portals/list.json. The stable branch of Walrus Sites is mainnet.

Loading portals...

The service-worker portal is no longer hosted, but you can still run it locally. Its code is available in the walrus-sites repository. For more information, see running a local portal.

Running a local portal​

Running a portal locally can be useful, for example if you want to browse Walrus Sites without accessing external portals, or for development purposes.

Start by cloning the walrus-sites repository:

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

Make sure you are on the stable branch:

$ git checkout mainnet

Configuration​

Portal configuration is managed through 2 key elements:

  • Environment variables: Required for basic functionality.

  • Constants file: Optional for advanced customization.

Environment variables​

The environment variables are set in the .env.local file at the root of each portal directory. To just run a simple instance of a portal, you can use the environment variables specified in the .env.<network>.example file:

Mainnet server portal environment variables​
$ cp ./portal/server/.env.mainnet.example ./portal/server/.env.local
Testnet server portal environment variables​
$ cp ./portal/server/.env.testnet.example ./portal/server/.env.local

Likewise, if you want to run the service-worker portal, you can copy the .env.<network>.example file to .env.local in the portal/worker directory.

Mainnet service-worker portal environment variables​
$ cp ./portal/worker/.env.mainnet.example ./portal/worker/.env.local
Testnet service-worker portal environment variables​
$ cp ./portal/worker/.env.testnet.example ./portal/worker/.env.local

For a more detailed configuration, you can modify the .env.local files to suit your needs. As a reference, here are the definitions of the environment variables:

The server portal code contains additional functionality that can be enabled or disabled using environment variables. For example, you can enable or disable the blocklist feature by setting the ENABLE_BLOCKLIST variable to true or false. This can be helpful to manage the behavior of the portal. For example, if you host a publicly-accessible portal, you might want to avoid serving sites that are not published by you.

  • AGGREGATOR_URL: The URL to a Walrus aggregator that fetches the site resources from Walrus.

  • AMPLITUDE_API_KEY: Provide it if you want to enable Amplitude for your server analytics.

  • EDGE_CONFIG: If you host your portal on Vercel, you can use the Edge Config to blocklist certain SuiNS subdomains or Base36 object IDs.

  • EDGE_CONFIG_ALLOWLIST: Similar to blocklist, but allows certain subdomains to use the premium rpc url list.

  • ENABLE_ALLOWLIST: Enable the allowlist feature.

  • ENABLE_BLOCKLIST: Enable the blocklist feature.

  • ENABLE_SENTRY: Enable Sentry error tracking.

  • ENABLE_VERCEL_WEB_ANALYTICS: Enable Vercel web analytics.

  • LANDING_PAGE_OID_B36: The Base36 object ID of the landing page Walrus Site. That is, the page you get when you visit localhost:3000.

  • PORTAL_DOMAIN_NAME_LENGTH: If you connect your portal with a domain name, specify the length of the domain name. For example, example.com has a length of 11.

  • PREMIUM_RPC_URL_LIST: A list of RPC URLs that are used when a site belongs to the allowlist.

  • RPC_URL_LIST: A list of RPC URLs that are used when a site does not belong to the allowlist.

  • SENTRY_AUTH_TOKEN: If you enable Sentry error tracking, provide your Sentry authentication token.

  • SENTRY_DSN: If you enable Sentry error tracking, provide your Sentry DSN.

  • SENTRY_TRACES_SAMPLE_RATE: If you enable Sentry error tracking, provide the sample rate for traces.

  • SITE_PACKAGE: The Walrus Site package ID. Depending on the network you are using, you have to specify the correct package ID.

  • SUINS_CLIENT_NETWORK: The network of the SuiNS client.

  • B36_DOMAIN_RESOLUTION_SUPPORT: Define if Base36 domain resolution is supported. Otherwise, the site is not served.

Constants​

You can find the constants.ts file in the portal/common/lib directory. It holds key configuration parameters for the portal. Typically, you won't need to modify these, but if you do, these are the available parameters:

  • MAX_REDIRECT_DEPTH: The number of redirects the portal follows before stopping.

  • SITE_NAMES: Hard coded name: objectID mappings, to override the SuiNS names. For development only. Use this at your own risk as it might render some sites with legitimate SuiNS names unusable.

  • FALLBACK_PORTAL: This is related only to the service-worker portal. The fallback portal should be a server-side portal that is used in cases where some browsers do not support service-workers.

Deploying the portal​

To run the portal locally you can either use a Docker container or a local development environment.

Docker​

First, make sure you have Docker installed on your system. If it is not installed, follow the instructions on the Docker website.

$ docker --version

Then, build the Docker image with:

$ docker build -f portal/docker/server/Dockerfile -t server-portal . --build-arg ENABLE_SENTRY=false --no-cache

Finally, run the Docker container:

$ docker run --env-file ./portal/server/.env.local -p 3000:3000 server-portal

Browse the sites at localhost:3000.

Local development​

This requires having the bun tool installed:

Check if bun is installed with:

$ 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:

$ bun run server

To run a service-worker portal:

$ bun build:worker
$ bun run worker

Find the server side portal served at localhost:3000 the service worker portal at localhost:8080.