Reverse proxy and HTTPS

A production Netstamp instance should have one stable HTTPS origin. Terminate TLS at a reverse proxy and forward the complete origin to the controller.

Set the public origin

Configure these values before exposing the service:

APP_ENV=production
PUBLIC_BASE_URL=https://netstamp.example.com
NETSTAMP_VERSION=<tested tag or digest>

PUBLIC_BASE_URL is the single origin used for OAuth and OIDC callbacks, email and browser links, OpenAPI, notifications, and controller-served probe installers. It must contain only the HTTPS scheme and host, with no path, query, fragment, or credentials.

With APP_ENV=production, session cookies use the __Host- prefix together with Secure, HttpOnly, SameSite=Strict, and Path=/. Users must access the application over HTTPS.

Forward required headers

Preserve these headers through the reverse proxy:

• Host
• X-Forwarded-Proto
• X-Forwarded-For
• X-Real-IP when the proxy provides it
• Authorization

An Nginx server block can look like this:

server {
    listen 443 ssl http2;
    server_name netstamp.example.com;

    ssl_certificate /etc/letsencrypt/live/netstamp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/netstamp.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Authorization $http_authorization;
    }
}

Redirect plain HTTP to the same HTTPS origin.

Limit direct controller access

When the reverse proxy runs on the same host, bind the Compose port to loopback:

services:
  netstamp:
    ports:
      - "127.0.0.1:3000:8080"

If Netstamp must trust client addresses supplied by the proxy, set HTTP_TRUSTED_PROXIES to the proxy’s exact address or CIDR prefixes, separated by commas. Do not trust all addresses unless the controller port is unreachable from untrusted networks.

Network direction

The controller needs:

• Inbound HTTPS from browsers, API clients, and probes.
• Outbound access to configured OAuth/OIDC providers and notification endpoints.
• Outbound SMTP access when email is enabled.
• Database access to PostgreSQL.

Probes initiate outbound HTTPS connections to the controller. The controller does not need inbound access to probe hosts.

Verify the public deployment

curl --fail https://netstamp.example.com/healthz
curl --fail https://netstamp.example.com/api/v1/healthz
curl --fail https://netstamp.example.com/api/v1/openapi.json >/dev/null
curl --fail https://netstamp.example.com/api/v1/install/agent.sh >/dev/null

Also verify that HTTP redirects to HTTPS, the certificate chain is valid, sign-in sets secure cookies, and a disposable probe can reach the public origin.

Production checklist

• APP_ENV=production is set.
• PUBLIC_BASE_URL exactly matches the public HTTPS origin.
• Every development secret has been replaced independently.
• Netstamp and TimescaleDB image versions are pinned.
• The database and controller ports are not publicly exposed.
• Trusted proxy ranges are no broader than necessary.
• Both health endpoints are monitored.
• A database backup has been restored successfully in a test environment.

Continue with Authentication and email before opening account creation broadly.