Skip to main content

Behind a reverse proxy

The container serves plain HTTP on port 8080. For real use, put it behind a reverse proxy or load balancer that handles HTTPS. This page uses nginx on the same host; the same settings apply to any proxy.

Delegaris needs nothing special from the proxy. The web interface polls over ordinary HTTPS requests, so there are no WebSockets to pass through, and the container itself stays on HTTP behind the proxy.

Set PUBLIC_URL and TRUST_PROXY_HEADERS​

In .env:

PUBLIC_URL=https://delegaris.corp.example
TRUST_PROXY_HEADERS=true

PUBLIC_URL is the address people type, not the container's. With it set to an https:// address:

  • the session cookie is marked Secure, and browsers are told to keep using HTTPS (Strict-Transport-Security);
  • the Microsoft Entra ID redirect address is https://delegaris.corp.example/auth/oidc/callback;
  • links in Slack and Teams messages point at https://delegaris.corp.example.

TRUST_PROXY_HEADERS=true makes Delegaris take the visitor's address from X-Forwarded-For instead of the proxy's, for the activity log, sign-in throttling and the address an API token was last used from. Delegaris takes the right-most entry in that header, which is the one your proxy adds. Leave it false when nothing sits in front of the container, or anyone could put any address in the log.

Restart the container after changing .env:

docker compose up -d

With the Linux package, set the same two lines in /etc/delegaris/delegaris.env and run sudo systemctl restart delegaris.

Publish the port on localhost only​

With nginx on the same host, change the ports: line in docker-compose.yml so the container can only be reached through the proxy:

ports:
- "127.0.0.1:8080:8080"

This is more than tidiness. With an https:// PUBLIC_URL, the session cookie is marked Secure. A browser that opens http://<host>:8080 directly signs in successfully, then throws the cookie away and lands back on the sign-in page, with no obvious reason why. Binding to 127.0.0.1 stops anyone getting there.

Signed in, then straight back to the sign-in page

This is almost always the Secure-cookie problem: the page was opened over http:// while PUBLIC_URL is https://. The sign-in page shows a warning when it is opened that way, with a link to the right address. Use the https:// address, and bind the port to 127.0.0.1 as above.

When the page is opened at an address other than PUBLIC_URL (and PUBLIC_URL is plain http://), the sign-in page also says which address the service expects, because links in messages and Microsoft sign-in go there.

nginx configuration​

A minimal server block, terminating TLS for delegaris.corp.example and passing requests to the container on the same host:

server {
listen 443 ssl;
server_name delegaris.corp.example;
ssl_certificate /etc/nginx/certs/delegaris.crt;
ssl_certificate_key /etc/nginx/certs/delegaris.key;

location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 60s;
}
}

# Send plain HTTP to HTTPS.
server {
listen 80;
server_name delegaris.corp.example;
return 301 https://$host$request_uri;
}

Reload nginx and open https://delegaris.corp.example.

A load balancer instead of nginx​

The same two settings apply behind an AWS Application Load Balancer or any other HTTPS load balancer: PUBLIC_URL is the address on the load balancer and TRUST_PROXY_HEADERS=true. Use GET /healthz as the health check. No stickiness is needed. See High availability for a complete AWS layout.

Serving HTTPS from the container​

If there is no proxy, the container can serve HTTPS itself. Mount a certificate and key into the container and set both:

TLS_CERT_FILE=/certs/tls.crt
TLS_KEY_FILE=/certs/tls.key

The two must be set together, or the service refuses to start. The container still listens on port 8080, now for HTTPS. Set PUBLIC_URL to the https:// address people use.

Next steps​