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:
localhostconnections (development exception)- 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
| Variable | Default | Description |
|---|---|---|
NGINX_SERVER_NAME | (none) | Hostname for NGINX. Setting this enables HTTPS. |
NGINX_HTTP_PORT | 80 | HTTP port (redirects to HTTPS) |
NGINX_HTTPS_PORT | 443 | HTTPS port. When it is not 443 the HTTP redirect includes it (https://host:8443/) |
NGINX_CERT_FILE | ./nginx/ssl/server.crt | Path to SSL certificate |
NGINX_CERT_KEY | ./nginx/ssl/server.key | Path to SSL private key |
Routes
With NGINX active everything is served from one HTTPS port.
| Path | Destination | Description |
|---|---|---|
/ | Frontend | Svelte SPA |
/docs/ | Docs | Embedded documentation site |
/api/ws | Backend WebSocket | Real-time notifications |
/api/ | Backend REST API | All API endpoints |
/flower/ | Flower | Celery task monitoring |
/minio/ | MinIO console | S3 storage management |
/s3/ | MinIO API | Presigned 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:
- Trust the certificate on each device (recommended for homelab)
- 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
- Verify using HTTPS (not HTTP)
- Check browser console for errors
- Ensure certificate is trusted
- 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.