Enabling HTTPS

HTTPS is handled entirely by the nginx container (weiss). No changes are needed to the API or epicsWS services - they communicate on the internal Docker network over plain HTTP.

Prerequisites

You need a valid TLS certificate and private key in PEM format. Obtain them from your certificate authority, or generate self-signed certificates for testing:

openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out fullchain.pem \
  -days 365 -nodes -subj "/CN=your-server-hostname"

Place the files anywhere on the host that the weiss container can read (they are mounted read-only).

Configuration

In your .env file:

ENABLE_HTTPS=true
SSL_CERT_FILE=/path/to/fullchain.pem
SSL_KEY_FILE=/path/to/privkey.pem
APP_HOSTNAME=your-server-hostname

The scheme for CORS and OAuth redirect URIs is derived automatically from ENABLE_HTTPS, so no separate URL variable is needed.

  • nginx uses the HTTPS template (nginx/default.https.template) which listens on port 443 and redirects HTTP (port 80) to HTTPS.

  • The API sets the Secure flag on session cookies so they are only sent over HTTPS.

Restart the stack after changing these values:

docker compose up -d

Optional: NGINX setup

The nginx configuration templates are located in nginx/. Two templates are provided:

File

Used when

default.http.template

ENABLE_HTTPS=false (default)

default.https.template

ENABLE_HTTPS=true

The Docker entrypoint (nginx/docker-entrypoint.sh) selects the correct template at container start based on the ENABLE_HTTPS environment variable and substitutes APP_HOSTNAME, DOCS_HOSTNAME, and the certificate paths into the template.

An optional third template (default.docs.template) is appended to the HTTPS config when DOCS_HOSTNAME is set, adding a reverse-proxy server block for the documentation service.

If you need custom nginx directives (e.g., additional proxy headers, rate limiting, or custom locations), edit the relevant template file before building the image. The templates follow standard nginx envsubst syntax.

See more details on the nginx configuration in the nginx docs.