Skip to main content

NGINX & HTTPS Setup

Set up NGINX reverse proxy with SSL/TLS for secure HTTPS access. This enables browser microphone recording from devices other than localhost.

Why HTTPS?​

Modern browsers enforce strict security policies. The getUserMedia() API (used for microphone access) only works in:

  1. localhost connections (development exception)
  2. HTTPS connections (production requirement)

If you access OpenTranscribe over HTTP from another device or IP address, browsers will block microphone recording.

Homelab and small-office setup (self-signed)​

Self-signed certificates, name resolution, trusting the certificate on each device (Windows, macOS, Linux, iOS, Android) and the troubleshooting for it live in one place: Install for a small business. In short: ./opentranscribe.sh setup-ssl, then ./opentranscribe.sh restart.

NGINX is loaded in production only: ./opentr.sh start dev skips it (the Vite dev server serves the frontend directly), so HTTPS needs ./opentranscribe.sh start or ./opentr.sh start prod.

PKI / mutual TLS​

NGINX is required for PKI certificate-based authentication. --with-pki loads docker-compose.pki.yml, which makes NGINX verify client certificates before forwarding requests to the backend.

# Production only: the dev Vite server cannot perform an mTLS handshake
./opentr.sh start prod --build --with-pki

# https://localhost:5182, requires a valid client certificate (.p12)

Client certificates are generated by scripts/pki/ into scripts/pki/test-certs/clients/. For a real deployment replace the test certificates with your organisation's CA-signed ones.

Production Setup (Let's Encrypt)​

For production with a public domain, use Let's Encrypt for trusted certificates.

Prerequisites​

  • Domain name pointing to your server
  • Ports 80 and 443 accessible from internet

Generate Certificates​

# Install certbot
sudo apt install certbot # Ubuntu/Debian

# Stop services
./opentranscribe.sh stop

# Generate certificates
sudo certbot certonly --standalone -d transcribe.example.com

# Link certificates
mkdir -p nginx/ssl
sudo ln -sf /etc/letsencrypt/live/transcribe.example.com/fullchain.pem nginx/ssl/server.crt
sudo ln -sf /etc/letsencrypt/live/transcribe.example.com/privkey.pem nginx/ssl/server.key

Configure Environment​

Edit .env:

NGINX_SERVER_NAME=transcribe.example.com
NGINX_CERT_FILE=/etc/letsencrypt/live/transcribe.example.com/fullchain.pem
NGINX_CERT_KEY=/etc/letsencrypt/live/transcribe.example.com/privkey.pem

Auto-Renewal​

# Test renewal
sudo certbot renew --dry-run

# Add cron job
echo "0 0 1 * * certbot renew --quiet && docker restart opentranscribe-nginx" | sudo tee -a /etc/crontab

Environment Variables​

VariableDefaultDescription
NGINX_SERVER_NAME(none)Hostname for NGINX. Setting this enables HTTPS.
NGINX_HTTP_PORT80HTTP port (redirects to HTTPS)
NGINX_HTTPS_PORT443HTTPS port. When it is not 443 the HTTP redirect includes it (https://host:8443/)
NGINX_CERT_FILE./nginx/ssl/server.crtPath to SSL certificate
NGINX_CERT_KEY./nginx/ssl/server.keyPath to SSL private key

Routes​

With NGINX active everything is served from one HTTPS port.

PathDestinationDescription
/FrontendSvelte SPA
/docs/DocsEmbedded documentation site
/api/wsBackend WebSocketReal-time notifications
/api/Backend REST APIAll API endpoints
/flower/FlowerCelery task monitoring
/minio/MinIO consoleS3 storage management
/s3/MinIO APIPresigned upload and playback URLs

Troubleshooting​

SSL Certificates Not Found​

# Generate certificates
./scripts/generate-ssl-cert.sh opentranscribe.local --auto-ip

Browser Shows Security Warning​

Expected with self-signed certificates. Options:

  1. Trust the certificate on each device (recommended for homelab)
  2. Use Let's Encrypt for publicly trusted certificates

Connection Refused on Port 443​

# Check NGINX container
./opentranscribe.sh status
./opentranscribe.sh logs nginx

Certificate Expired or No Longer Matches​

For a self-signed certificate (the server's address changed, or it expired):

./opentranscribe.sh setup-ssl # answer y to overwrite
./opentranscribe.sh restart

then import the new server.crt on each device. For Let's Encrypt run sudo certbot renew and docker restart opentranscribe-nginx.

Microphone Still Not Working​

  1. Verify using HTTPS (not HTTP)
  2. Check browser console for errors
  3. Ensure certificate is trusted
  4. Try incognito/private window

Advanced: Custom NGINX Configuration​

Edit nginx/site.conf.template for customizations. It is rendered with envsubst at container start from NGINX_SERVER_NAME, the Flower credentials and the redirect port suffix only; another ${VAR} needs adding to the whitelist in docker-compose.nginx.yml.

  • HTTP Basic Auth for Flower/MinIO
  • Custom headers
  • Rate limiting
  • Larger file upload limits

Restart after changes:

docker restart opentranscribe-nginx

Security notes​

  • Self-signed certificates suit homelabs and internal networks; for a public-facing deployment use Let's Encrypt. Browsers show a warning until the certificate is trusted.
  • Never commit nginx/ssl/server.key; it is git-ignored.
  • Renew certificates before they expire and monitor the expiry date.