PORTAL v2

Portal Relay Deployment Guide

Portal production deployment uses one image and one public HTTPS origin. The Go binary owns TLS, SNI routing, relay APIs, tunnel ingress, and the embedded React SPA. Operators can replace only the SPA files without adding a reverse proxy or changing ownership of the Portal API paths.

Run a relay. Stay in control.

A relay exposes a public endpoint on your IP and domain. Budget for egress and finite compute and ports, plan for outages, and be prepared to handle abuse complaints and IP, domain or CA reputation damage. Approved publishers and their visitors can still generate costs. A stream rate limit in bytes/second cannot guarantee a monthly traffic bill or remove legal liability.

Choose Public (auto) to accept registrations by default, or Approval Required (manual) to review authenticated service identities before allocating resources. For a first or capacity-constrained relay, start with manual approval. Check the effective mode in /admin or the relay’s public /sdk/domain report. A saved policy.json overrides the startup setting.

See Private relay for pending requests, pre-approval and mode changes.

Production Topology

Browser or tunnel client
  -> https://portal.example.com or https://*.portal.example.com
  -> Portal :443 SNI router
      -> root host: Admin/API handler (in-process handoff)
          -> /api/*, /sdk/*, /discovery*, /v1/sign
          -> embedded React SPA for /, /admin, and client routes
      -> registered wildcard host: tunnel ingress

The SNI router is the single ingress: it inspects each TLS handshake and hands root-host connections in-process to the Admin/API handler, so there is no separate API listener and nothing else to publish.

This topology assumes Portal owns public 443/tcp. If that port already belongs to something else on the host, see Running Behind an Existing Reverse Proxy. For a Kubernetes cluster, see Kubernetes.

Prerequisites

  • A public Linux server with Docker and Docker Compose.
  • A public hostname such as portal.example.com.
  • A one-time NS delegation at the parent zone: NS portal.example.com -> ns.portal.example.com with a glue A record pointing at the relay public IP. See the Configuration Reference for the canonical embedded DNS details.
  • Inbound 443/tcp, 53/tcp + 53/udp for the embedded authoritative DNS.
  • Certificates for the root and wildcard names are issued automatically via ACME DNS-01 against the embedded authoritative DNS.

Configuration

Create .env next to docker-compose.yml:

PORTAL_URL=https://portal.example.com
ADMIN_TOKEN=replace-with-a-long-random-value
APPROVAL_MODE=auto

DISCOVERY=false
BOOTSTRAPS=
IVNP_CONFIG=

# Embedded authoritative DNS is the default provider and needs no API
# credentials once the NS delegation above is in place. External providers
# (cloudflare, gcloud, hetzner, njalla, route53, vultr) are supported
# first-class backends when selected explicitly.
ACME_DNS_PROVIDER=
EMBEDDED_DNS_PORT=53

Embedded DNS logs its DS as soon as the local DNS listeners start; startup does not check delegation. After NS/glue delegation is reachable, publish the DS printed at startup at the parent zone. Persist IDENTITY_PATH/dnssec-csk.json with the identity volume across container replacement and backup/restore; replacing this key without coordinating the parent DS breaks DNSSEC validation. See Embedded DNS for the complete DNSSEC setup and key-storage requirements. Manual certificate overrides remain supported.

APPROVAL_MODE supplies the initial value. Changes made from the admin dashboard are stored in IDENTITY_PATH/policy.json and survive restarts. For a relay that serves only tunnels you approve, see Private relay.

To enable optional IVNP-backed overlay networking, set DISCOVERY=true, mount an IVNP RouterConfig JSON file, and set IVNP_CONFIG to its container path. A file containing {} uses in-memory router state and needs no writable state mount. Replace legacy ivnp.conf files with the new JSON format. For persistent router state, explicitly configure and mount a dedicated private directory as described in IVNP overlay configuration. Invalid overlay configuration fails startup. Destination warmup runs in the background; a runtime overlay failure leaves public ingress and direct reverse transport running. See the overlay networking concepts and the architecture.

Google Trust Services with External Account Binding

Let’s Encrypt remains the default CA. To select Google Trust Services (GTS) Public CA, create or select a Google Cloud project, enable the Public CA API, and obtain an external account binding (EAB) key. The identity requesting the key needs roles/publicca.externalAccountKeyCreator; enabling the API also requires the appropriate Service Usage permission.

gcloud services enable publicca.googleapis.com --project=YOUR_PROJECT_ID
gcloud publicca external-account-keys create --project=YOUR_PROJECT_ID

Copy the returned keyId and b64MacKey into the relay’s private .env:

ACME_CA_DIR_URL=https://dv.acme-v02.api.pki.goog/directory
ACME_EAB_KID=REPLACE_WITH_keyId
ACME_EAB_HMAC=REPLACE_WITH_b64MacKey

The HMAC is a base64url secret. Restrict .env access (chmod 600 .env on Unix), keep it out of version control, and use environment variables rather than putting secrets in command-line arguments. The repository Compose file forwards these settings to the relay. Treat access to the Docker daemon and container inspection output as access to the secrets. The relay’s config report redacts both EAB values.

EAB keys are single-use and must be used within seven days. After successful registration, preserve the entire identity volume, including the account key and CA-specific registration. Both EAB variables can then be removed; startup, renewal, and tenant issuance reuse the registered account. A different CA directory uses its own registration and certificate files. Switching back reuses that directory’s saved state. Registration failures stop issuance; Portal does not fall back to another CA. Operator-managed certificate files continue to override managed relay issuance.

GTS uses the existing DNS-01 provider. It does not require Google Cloud DNS. If your domain restricts issuance through CAA, authorize pki.goog for the names being issued, including wildcard policy where applicable. See Google’s Public CA setup guide for IAM, EAB, CAA, and staging details.

The selected CA serves both relay wildcard issuance and authorized tenant CSRs. TENANT_CERTIFICATES stays default-off. Public tenant issuance still requires explicit service approval and shared durable TENANT_ISSUANCE_STATE_DIR accounting. GTS quotas apply to the Google Cloud project; multiple ACME accounts in that project share them. EAB does not remove issuance limits. Check the project’s effective quotas and Google’s Public CA request quotas before enabling tenant issuance broadly. These instructions were checked against Google’s documentation on 2026-11-14.

Optional live verification

Use a dedicated test relay and delegated DNS zone. Follow Google’s staging instructions to obtain a staging EAB key, then select https://dv.acme-v02.test-api.pki.goog/directory and use a separate identity volume. Staging certificates are not publicly trusted. Confirm wildcard DNS-01 issuance, remove both EAB variables, and restart with the same volume to confirm account and certificate reuse. With tenant issuance explicitly enabled and an approved service identity, request an automatic tenant certificate and check its exact hostname and chain. Observe subsequent renewal with the same account; do not repeatedly delete account state to force registration. Live GTS issuance is an operator opt-in check and is not performed by regular CI.

Optional Observability

The observability Compose overlay adds Prometheus and Grafana without changing the base deployment. It scrapes the authenticated /api/admin/metrics route. The dashboard follows the current aggregate metrics contract; transport-specific and application traffic panels require additional relay statistics.

Custom Community Frontend

Portal serves the official embedded SPA when PORTAL_FRONTEND_DIR is empty. To use a React, Vue, Svelte, Astro, or other static SPA, build it with client routes falling back to index.html, then mount its output directory read-only:

services:
  portal:
    environment:
      PORTAL_FRONTEND_DIR: /srv/portal/frontend
    volumes:
      - ./community-frontend/dist:/srv/portal/frontend:ro

The mounted directory must contain a regular index.html; Portal fails at startup with a configuration error when it does not. Custom assets own / and client-side routes, while /api, /sdk, /discovery, and /v1 remain reserved Portal paths. Community frontends can therefore use the stable JSON APIs without owning TLS routing or running nginx.

Frameworks that require a live SSR server cannot be mounted as static files. Run those applications separately and call the Portal API over HTTPS; the API allows cross-origin requests. Static-export modes can use the mount directly.

To override ACME with a manually managed certificate, place these files in ./.portal-certs:

fullchain.pem
privatekey.pem

The certificate must cover the Portal root hostname and the tunnel hostnames, normally through a wildcard SAN. Even uncached tunnels use this certificate through the relay-backed keyless signer. Manual files override issuance only when neither acme-account.key nor acme-registration.json exists in the state directory; DNS management still runs.

Deploy

mkdir -p ./.portal-certs
# For a new bind-mount directory on Linux, allow the nonroot container to write.
# Preserve the ownership policy of existing deployments.
sudo chown 65532:65532 ./.portal-certs
docker compose pull portal
docker compose up -d --force-recreate portal

For a local source build:

docker compose up -d --build --force-recreate portal

Name the Portal service explicitly when the Compose project contains unrelated services. Do not use --remove-orphans on a shared project; remove obsolete containers individually after confirming their ownership.

The Compose stack publishes:

PortPurpose
443/tcpPortal HTTPS, SPA, APIs, and SNI tunnel ingress
53/tcp + 53/udpEmbedded authoritative DNS for the delegated relay zone
configured lease rangeOptional UDP and raw TCP leases

Port 80/tcp is optional. To enable the built-in redirect listener, set HTTP_REDIRECT_ENABLED=true and publish 80:80. It redirects to the canonical PORTAL_URL, discarding the request path and query; it does not redirect tenant hostnames. See HTTP redirect configuration. An external redirect service is also possible, but must not terminate wildcard tunnel TLS.

Verify

curl -fsS https://portal.example.com/api/healthz
curl -fsS https://portal.example.com/sdk/domain
curl -I https://portal.example.com/
curl -I https://portal.example.com/admin
docker compose ps

Expected runtime services:

portal

The /admin request must return the SPA entry rather than 404. Registered subdomains must continue to reach their tunnel targets through the same public 443 listener.

Upgrading

The current source retains tunnel protocol 10 and discovery version 9. New SDKs select their implemented protocol from supported_protocol_versions, falling back to exact equality with protocol_version when the list is absent or null. The current relay advertises default 10 and supported ["10"]. Feature capabilities are negotiated separately.

Keeping protocol 10 preserves main’s version negotiation behavior. SDK v2.7.3 and v2.7.4 pass that check but require the removed canonical response field, even when callers use only an alias. Those releases still need a relay that provides their original contract or an SDK upgrade. Check the pinned SDK’s registration and lifecycle behavior before deployment; the source release label alone does not establish compatibility.

Named HTTP services can use their granted friendly alias with the current SDK. Unnamed HTTP services require explicit Local TLS with usable certificate material. Move traffic after replacement clients are ready and drain existing connections before retiring a relay. See the compatibility matrix for the current limitations.

For replacement within a compatible protocol version, see Relay Replacement with External Infrastructure. It describes explicit dual registration, externally managed connection draining, policy responsibilities, and the current configuration limits.

Running Behind an Existing Reverse Proxy

Portal expects to own public 443/tcp. On a host that already serves other sites from that port, it cannot simply be pointed at: Portal’s SNI router closes any hostname it has no lease for, so a shared socket would drop every request meant for those other sites.

The proxy keeps the port and hands Portal the hostnames that belong to it. Example configurations: Compose override and nginx configuration.

One topology: nginx in a container beside Portal

nginx runs on the same Compose network as Portal and owns the public HTTPS port. It reaches Portal as portal:443 on that network. Portal still publishes 53/tcp and 53/udp for the default embedded DNS provider; retain any enabled UDP backhaul and lease-port mappings in the override.

host :443 -> nginx container
               :443  stream, ssl_preread, sends PROXY protocol
                 *.portal.example.com -> :8444 -> strips PROXY -> portal:443
                 portal.example.com   -> :8444 -> strips PROXY -> portal:443
                 anything else        -> :8443 -> nginx http, other sites

Mixing this with a host-loopback port mapping does not work: if Portal also published 127.0.0.1:8443, nginx’s own listener on that address could not bind. Pick this topology or a host nginx reaching Portal over published ports ?? not both.

SNI_PORT stays 443 inside the container. The SNI router is Portal’s single ingress: the Admin/API handler is served through it in-process, so there is no separate API port to wire around.

Lease hostnames must pass through, unmodified

Terminating TLS for *.portal.example.com breaks tunnels: clients started with --ban-mitm probe for termination and drop a relay that does it, and it disables keyless TLS, which needs the handshake itself to reach Portal.

Two things in an nginx stream block break this quietly.

The map needs hostnames;. Without it, map compares keys as literal strings and *.portal.example.com matches nothing, so every lease hostname falls through to default and is answered by the HTTP terminator instead of Portal:

map $ssl_preread_server_name $portal_backend {
    hostnames;                              # required for the wildcard to match
    *.portal.example.com  127.0.0.1:8444;
    portal.example.com    127.0.0.1:8444;
    default               127.0.0.1:8443;
}

The PROXY header must be stripped before Portal. proxy_protocol on is a server-level directive, so the :443 listener sends the header to every destination it selects. Portal does not parse the PROXY protocol: it would read PROXY TCP4 ... where it expects a TLS ClientHello and close the connection. Send the lease path through a stage that consumes the header first:

server {
    listen 127.0.0.1:8444 proxy_protocol;   # consumes it
    set $portal_sni portal:443;             # variable, so it resolves per request
    proxy_pass $portal_sni;                 # no proxy_protocol on: plain TLS onward
}

Client addresses, and the trust boundary

An SNI router forwarding to a local port opens a new connection, so the terminating listener sees the router rather than the visitor. proxy_protocol on carries the original address, and the http block recovers it:

set_real_ip_from 127.0.0.1;     # trust only the loopback hop
real_ip_header proxy_protocol;

This is what gives the other sites on the box their real client addresses. For Portal itself it only matters if you terminate the root host.

If you do, overwrite X-Forwarded-For rather than appending to it:

proxy_set_header X-Forwarded-For $remote_addr;    # not $proxy_add_x_forwarded_for
proxy_set_header X-Real-IP $remote_addr;

$proxy_add_x_forwarded_for keeps whatever the visitor sent and appends the peer. Portal trusts the first entry, so a request carrying X-Forwarded-For: 10.0.0.9 from the Internet arrives as 10.0.0.9, <real> and is read as 10.0.0.9. The client picks its own address: it escapes source rate limits, and with TUNNEL_SOURCE_CIDRS set it can register tunnels from outside the list. Set X-Real-IP the same way, because Portal reads it when X-Forwarded-For is absent. $remote_addr has already been restored from the PROXY header, so it is both correct and unspoofable.

Enable TRUST_PROXY_HEADERS and set TRUSTED_PROXY_CIDRS to the proxy’s own address as a /32 (/128 for IPv6). An empty allowlist trusts no proxies, including private and loopback peers, and Portal uses the socket address. Do not allowlist an entire private subnet: on a Docker host that would let other containers choose their client address and bypass source limits. TUNNEL_SOURCE_CIDRS matches this same resolved address, so a wrong proxy allowlist also lets the wrong tunnels in.

That address has to be fixed. Compose assigns container addresses dynamically, so a /32 matching whatever nginx got today stops matching the next time it is recreated ??and the failure is silent: everything still works, Portal just ignores the forwarded address and starts applying rate limits to nginx instead of to visitors. Give the network its own IPAM and pin nginx into it:

services:
  nginx:
    networks:
      edge:
        ipv4_address: 172.31.240.2      # TRUSTED_PROXY_CIDRS=172.31.240.2/32
  portal:
    networks: [edge]

networks:
  edge:
    ipam:
      config:
        - subnet: 172.31.240.0/24

Compose’s implicit default network does not accept ipv4_address, which is why the network is declared. Check the subnet does not overlap something already on the host with docker network inspect $(docker network ls -q) --format '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}'.

Sharing a Compose project with unrelated services

A host like this usually runs Portal alongside services that have nothing to do with it. Compose commands operate on the whole project by default, so name the service explicitly every time:

docker compose up -d portal        # not: docker compose up -d
docker compose stop portal         # not: docker compose down

Never pass --remove-orphans on a shared project. It deletes every container in the project that the current file does not define, which includes services that belong to other stacks.

Verifying without a regression hunt

Record how the host answers before changing anything, so that an error found afterwards can be attributed rather than investigated:

# One line per host, with a path its clients actually use.
cat > probe.txt <<'PROBE'
portal.example.com   /api/healthz
other-site.example   /
PROBE

probe() {
  while read -r host path; do
    [ -z "$host" ] && continue
    printf '%-32s %-16s %s\n' "$host" "$path" 
      "$(curl -sS -o /dev/null -w '%{http_code}' --max-time 10 "https://$host$path")"
  done < probe.txt
}

probe > baseline.txt

Compare with probe | diff baseline.txt - afterwards. Judge by the difference, not by whether a code looks healthy: / is not a valid request for every host, and a WebSocket-only endpoint answers a plain GET with nothing at all, which a proxy correctly reports as 502.

Automated Updates

Production deployments should follow the v2 release track:

ghcr.io/gosuda/portal:2

The bundled watcher tracks that image and recreates only the Portal service:

cp <repo>/docs/static/examples/auto-update/watch_and_deploy.sh ./watch_and_deploy.sh
chmod +x watch_and_deploy.sh
./watch_and_deploy.sh

Troubleshooting

Port 443 Is Already Allocated

Identify what holds the port first:

sudo ss -tlnp | grep ':443'

If the listener belongs to an obsolete deployment, stop only that deployment’s service after confirming ownership. If it serves other sites, keep it running and use the reverse-proxy topology.

SPA Routes Return 404

When PORTAL_FRONTEND_DIR is empty, Portal serves its embedded frontend. When it is set, confirm the mounted directory contains index.html and all asset paths expected by that file. /admin and other non-reserved client routes fall back to the selected SPA’s index.html.

Certificate Errors

Confirm PORTAL_URL matches the certificate root hostname and inspect the certificate files under IDENTITY_PATH. With the embedded DNS provider, confirm the delegation is visible (dig @<relay public IP> portal.example.com NS) and that 53/tcp + 53/udp are reachable. With an external provider, verify the DNS API token has permission to update the selected zone.