Nia documentation · Latest
HTTPS and reverse proxy
Publish Nia safely with a stable HTTPS URL, correct forwarded headers and trusted proxy settings.Run Nia behind HTTPS for normal production use. Passkeys, secure browser APIs, email links, OIDC and native-client handoff depend on a stable public origin.
Required application settings
After the proxy works, open /admin and configure:
- Public base URL: the exact external origin, for example
https://todo.example.com - Allowed origins: the exact origins allowed to make credentialed cross-origin API requests
- Trusted proxies: the IP address or CIDR of the proxy that is allowed to supply client-IP and forwarded-host headers
Do not include a path or trailing slash in the public base URL. Do not trust a broad network unless every host in it is controlled.
Caddy example
todo.example.com {
reverse_proxy 127.0.0.1:8753
}
Caddy obtains and renews TLS certificates automatically when DNS and inbound ports are configured correctly.
Nginx example
server {
listen 443 ssl http2;
server_name todo.example.com;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:8753;
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 Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
The WebSocket headers keep realtime updates working across all modules. Do not cache authenticated API responses or private media at the proxy. Recipe images require current cookbook access, and Tasks attachments require current task access.
Adjust client_max_body_size to the attachment limit you intend to allow. BrainDump recordings and recipe editor requests also pass through the proxy. If a request works directly but times out through the proxy, check its read timeout against the configured STT/LLM deadline; increasing an upload limit alone does not extend model-processing time.
Verify the result
curl -I https://todo.example.com/
curl https://todo.example.com/api/instance
Then check:
- Sign-in and normal page reloads work.
- The public instance response shows the HTTPS base URL.
- Realtime updates connect without WebSocket errors.
- A passkey can be registered after the public URL is saved.
- Native apps use the same server URL, including
https://.
Changing the public hostname changes the WebAuthn relying-party context. Plan the change before users rely on passkeys as their only convenient factor.