Portal DNS Configuration

After setting up your portal and configuring it for your domain, you need to configure your domain's DNS to route traffic to the server running your portal.

This guide covers adding DNS records, setting up HTTPS with a reverse proxy, verifying propagation, and troubleshooting common DNS issues.

Prerequisites

• A portal running on a server with a public IP address, configured per Use Your Own Domain for a Walrus Site
• Access to your domain's DNS settings through your domain registrar or DNS provider

Point your root domain to the portal

Log in to your domain registrar or DNS provider and add an A record for your domain:

Type	Name	Value
A	@	Your server's public IP address

The @ symbol represents the root domain (for example, example.com). Replace the value with the actual public IP address of the server running your portal.

DNS changes can take anywhere from a few minutes to 48 hours to propagate globally, depending on your DNS provider and the TTL (time to live) setting on your records. Most modern DNS providers propagate changes within a few minutes.

Point a subdomain to the portal (optional)

If you want to serve your site at a subdomain like www.example.com or app.example.com, add an A record for the subdomain instead:

Type	Name	Value
A	www	Your server's public IP address

You can add both a root domain record and a subdomain record, then configure your reverse proxy to handle both hostnames.

tip

Some domain registrars let you set up automatic redirects from www to your root domain (or the reverse). Check your registrar's documentation for redirect or forwarding options if you want both example.com and www.example.com to reach your site without running 2 separate server configurations.

Set up HTTPS with a reverse proxy

info

The Walrus Sites repo provides 2 first-party deployment options for the portal server: a Dockerfile for self-hosted deployments and a vercel.json for deploying on Vercel, which handles TLS automatically. If either of those fits your setup, you do not need a reverse proxy.

If you are running the portal directly on a Linux server, it listens on port 3000 with no built-in TLS. To serve HTTPS traffic you need a reverse proxy in front of it. A reverse proxy like Nginx or Caddy sits in front of your portal, handles TLS termination, and forwards requests to the portal process on its local port.

The following is a general-purpose Nginx configuration that proxies HTTPS traffic to a portal running on port 3000. This is not an officially supported Walrus Sites configuration — adapt it to your environment:

nginx.conf

server {
    listen 443 ssl;
    server_name example.com;
 
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
 
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Replace example.com with your domain and adjust the port if your portal is configured differently.

Any standard TLS certificate works here. Certbot with Let's Encrypt is a common free option that automates certificate issuance and renewal:

$ certbot --nginx -d example.com

Certbot edits your Nginx config to reference the certificate and configures automatic renewal. Caddy is an alternative that handles TLS automatically without a separate certificate step.

Verify DNS propagation

After adding your DNS records, confirm that your domain resolves to the correct IP address before testing the site.

Step 1: Check the A record

Use dig to confirm your domain resolves to your server's public IP address:

$ dig example.com A +short

The output should show your server's public IP address. If it returns nothing or a different address, the record has not yet propagated or was not saved correctly.

Step 2: Check that the portal is serving your site

Open a browser and navigate to your domain. Your Walrus Site should load. If the site does not load, check the following:

• The portal server is running on your server.
• The port the portal listens on is open in your server's firewall or security group.
• The reverse proxy (if used) is running and pointing to the correct port.
• The portal-config.yaml fields are set correctly, especially landing_page_oid_b36 and bring_your_own_domain: true.