Deployment: payment domain behind HTTPS
polysiad run serves two things on two loopback ports:
| Listener | default | what | who may reach it |
|---|---|---|---|
API_ADDR | 127.0.0.1:8081 | /v1/* (API), /pay/* (payment pages), /l/* (payment links) | the internet, only through your HTTPS reverse proxy |
DASHBOARD_ADDR | 127.0.0.1:8080 | the 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 withssh -L 8080:127.0.0.1:8080 you@serverand openhttp://127.0.0.1:8080. The proxy forwards only/v1/*,/pay/*and/l/*of port 8081 and answers 404 for everything else.polysiadrefuses a non-loopbackDASHBOARD_ADDRunlessDASHBOARD_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:8080API_PUBLIC_URLmakespay_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.