docs
On this page

Deployment: payment domain behind HTTPS

polysiad run serves two things on two loopback ports:

Listenerdefaultwhatwho may reach it
API_ADDR127.0.0.1:8081/v1/* (API), /pay/* (payment pages), /l/* (payment links)the internet, only through your HTTPS reverse proxy
DASHBOARD_ADDR127.0.0.1:8080the admin dashboard (keys, withdrawals, settings)you only — SSH tunnel or VPN

Never make the dashboard (port 8080) public — not through the proxy, not with a firewall rule, not with DASHBOARD_ADDR=0.0.0.0:…. It controls withdrawals and API keys. Reach it with ssh -L 8080:127.0.0.1:8080 you@server and open http://127.0.0.1:8080. The proxy forwards only /v1/*, /pay/* and /l/* of port 8081 and answers 404 for everything else. polysiad refuses a non-loopback DASHBOARD_ADDR unless DASHBOARD_ALLOW_REMOTE=1, and then logs a warning at every start.

1. DNS, firewall, .env

  • DNS: pay.example.com → your server. Firewall: allow 80 and 443 (and SSH); 8080 and 8081 stay closed.
  • backend/.env:
    API_ADDR=127.0.0.1:8081
    API_PUBLIC_URL=https://pay.example.com
    API_TRUST_PROXY=1
    # TRUSTED_PROXIES=127.0.0.1,::1      (default; set the proxy's IP/CIDR if it runs on another host)
    DASHBOARD_ADDR=127.0.0.1:8080

    API_PUBLIC_URL makes pay_url / payment-link URLs absolute and turns on HSTS.

2a. Caddy (automatic Let's Encrypt)

/etc/caddy/Caddyfile:

pay.example.com {
    encode gzip
    @polysia path /v1/* /pay/* /l/*
    reverse_proxy @polysia 127.0.0.1:8081
    respond 404
}

sudo systemctl reload caddy. Caddy sets X-Forwarded-For / X-Forwarded-Proto correctly by default.

2b. Nginx (+ certbot)

/etc/nginx/sites-available/polysia:

server {
    listen 443 ssl http2;
    server_name pay.example.com;
    ssl_certificate     /etc/letsencrypt/live/pay.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pay.example.com/privkey.pem;
    client_max_body_size 32k;

    location ~ ^/(v1|pay|l)/ {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;   # overwrite — never append a client-supplied value
        proxy_set_header X-Forwarded-Proto https;
    }
    location / { return 404; }                            # dashboard and anything else: not here
}
server { listen 80; server_name pay.example.com; return 301 https://$host$request_uri; }

sudo certbot --nginx -d pay.example.com, then sudo nginx -t && sudo systemctl reload nginx.

3. Check

curl -sS https://pay.example.com/v1/health                  # {"ok":true}
curl -s -o /dev/null -w '%{http_code}\n' https://pay.example.com/            # 404
curl -s -o /dev/null -w '%{http_code}\n' https://pay.example.com/login       # 404 (dashboard is not reachable)
curl -s -o /dev/null -w '%{http_code}\n' http://pay.example.com:8080/        # 000 (connection refused / filtered)

and in the polysiad log: no API_TRUST_PROXY / X-Forwarded-Proto / DASHBOARD_ADDR warnings.

Why the proxy settings matter

The API rate-limits per client IP and blocks an IP after repeated invalid API keys. It reads the client IP from X-Forwarded-For only with API_TRUST_PROXY=1 and when the TCP peer is in TRUSTED_PROXIES (read right to left, skipping trusted proxies — a forged value at the left is never used). If the proxy is in front but this is not set, every request seems to come from the proxy: one attacker would block all your customers. polysiad warns when API_PUBLIC_URL is set without API_TRUST_PROXY=1, when an untrusted peer sends X-Forwarded-For, when almost all requests come from one IP, and when API_PUBLIC_URL is https but requests lack X-Forwarded-Proto: https.