Knowledge base / Setup

HTTPS and reverse proxy

Run Kontris behind a reverse proxy or let it serve HTTPS itself.

Behind a reverse proxy

The usual setup: nginx, Traefik, Caddy or HAProxy accept HTTPS and forward to http://127.0.0.1:3000.

  • The proxy sets the headers X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host.
  • contracthub.env contains TRUST_PROXY=1 when exactly one proxy is in front.
  • APP_BASE_URL is the address users see in the browser, with https://.
  • The proxy’s upload limit is at least MAX_UPLOAD_MB (default 50 MB).
  • The proxy sets HSTS, for example Strict-Transport-Security: max-age=31536000.

Example for nginx:

server {
  listen 443 ssl;
  http2 on;
  server_name contracthub.example.com;

  ssl_certificate     /etc/ssl/contracthub/fullchain.crt;
  ssl_certificate_key /etc/ssl/contracthub/server.key;

  client_max_body_size 50m;
  add_header Strict-Transport-Security "max-age=31536000" always;

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

If you are signed out again right after signing in, APP_BASE_URL does not match the address in the browser or TRUST_PROXY is missing.

Without a reverse proxy

Kontris can serve HTTPS itself:

APP_BASE_URL=https://contracthub.example.com
TRUST_PROXY=false
TLS_CERT_FILE=/tls/server.crt
TLS_KEY_FILE=/tls/server.key
# optional: HTTP port that redirects to HTTPS
HTTP_REDIRECT_PORT=8080

In compose.yaml:

    ports:
      - '443:3000'
      - '80:8080'
    volumes:
      - ./tls:/tls:ro
  • server.crt contains the server certificate first, then the intermediate certificates (PEM).
  • server.key is the unencrypted key (PEM) and must be readable for UID 1000.
  • Kontris checks at startup that the two match and sets HSTS itself. The remaining validity of the certificate is in the log, as a warning from 30 days before expiry.
  • To renew, replace the files and restart the container.

Certificate from a PFX file

openssl pkcs12 -in contracthub.pfx -clcerts -nokeys -out server-only.crt
openssl pkcs12 -in contracthub.pfx -cacerts -nokeys -out chain.crt
openssl pkcs12 -in contracthub.pfx -nocerts -nodes -out server.key
cat server-only.crt chain.crt > server.crt
sudo chown 1000:1000 server.key && sudo chmod 600 server.key

If openssl reports unsupported, repeat the commands with -legacy at the end.

As of 2026-11-15 · Stuck? Write to us