Skip to main content

TLS / HTTPS

Starting from v1.8.0, the bundled nginx can terminate TLS directly. HTTP-only mode (TLS_ENABLED=0) remains the default. Enabling HTTPS is opt-in.

For the full technical reference see TLS.md in the RAG-DocBot source repository.

Quick Overview​

ModeDefault?Ports
HTTP only (TLS_ENABLED=0)✅8088:80
HTTPS (TLS_ENABLED=1)❌8088:80 (redirects to HTTPS), 8443:443

When TLS is enabled, the HTTP :80 listener:

  • Permanently redirects all requests to HTTPS.
  • Serves Let's Encrypt HTTP-01 challenge files from /var/www/acme (no redirect applied to /.well-known/acme-challenge/).

Enabling TLS​

  1. Add the following to your .env:

    TLS_ENABLED=1
    SERVER_NAME=docbot.example.com

  2. Place your certificate files in ./nginx/certs/:

    FileContainer path
    ./nginx/certs/fullchain.pem/etc/nginx/certs/fullchain.pem
    ./nginx/certs/privkey.pem/etc/nginx/certs/privkey.pem

    Override the paths with TLS_CERT_PATH / TLS_KEY_PATH if needed.

  3. Restart nginx:

    docker compose up -d nginx
Docker Compose env-file gotcha

Docker Compose only auto-loads a file literally named .env. If your TLS variables live in .env.local or another file, pass --env-file .env.local explicitly:

docker compose --env-file .env.local up -d

Otherwise TLS_ENABLED will fall back to 0 and HTTPS will not be enabled.

Deployment Walkthroughs​

Three walkthroughs are covered in TLS.md:

LAN / Self-Signed Certificate​

Use the provided helper script to generate a self-signed certificate for local or lab deployments:

./nginx/scripts/gen-selfsigned.sh

The script creates ./nginx/certs/fullchain.pem and ./nginx/certs/privkey.pem. Clients will see a browser warning unless the certificate is imported into the system trust store.

Air-Gapped / Internal CA​

Issue a certificate from your internal CA and place it at ./nginx/certs/fullchain.pem (full chain, intermediate first) and ./nginx/certs/privkey.pem. Set OCSP_STAPLING=off in .env if your CA's OCSP responder is not reachable from the server:

TLS_ENABLED=1
SERVER_NAME=docbot.internal
OCSP_STAPLING=off

Internet-Exposed (Let's Encrypt)​

The deployment includes a certbot service (under the letsencrypt Docker Compose profile) that handles certificate issuance and shares the ./nginx/acme webroot with nginx for HTTP-01 challenges.

Use the provided helper scripts:

# Initial certificate issuance (run before starting nginx with TLS)
./letsencrypt-init.sh

# Certificate renewal (run periodically, e.g. via cron)
./letsencrypt-renew.sh

Detailed steps are in TLS.md.

TLS Configuration Reference​

VariableDefaultDescription
TLS_ENABLED0Set to 1 to enable HTTPS termination
SERVER_NAME(must be set when TLS enabled)FQDN of the server (used in server_name and HSTS)
TLS_CERT_PATH/etc/nginx/certs/fullchain.pemCertificate path inside the nginx container
TLS_KEY_PATH/etc/nginx/certs/privkey.pemPrivate key path inside the nginx container
HSTS_MAX_AGE31536000HSTS max-age in seconds. Set to 0 to disable HSTS.
OCSP_STAPLINGonSet to off for air-gapped deployments

TLS Settings​

  • Protocols: TLSv1.2 and TLSv1.3
  • Cipher suite: ECDHE + CHACHA20/AES-GCM (ECDHE preference)
  • HSTS: enabled by default with a 1-year max-age; configure or disable via HSTS_MAX_AGE
  • OCSP stapling: enabled by default; disable with OCSP_STAPLING=off for air-gapped environments