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.comwith a glueArecord pointing at the relay public IP. See the Configuration Reference for the canonical embedded DNS details. - Inbound
443/tcp,53/tcp+53/udpfor 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:
| Port | Purpose |
|---|---|
443/tcp | Portal HTTPS, SPA, APIs, and SNI tunnel ingress |
53/tcp + 53/udp | Embedded authoritative DNS for the delegated relay zone |
| configured lease range | Optional 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.