Production Deployment & Hardening Guide
This guide covers everything needed to deploy OpenTranscribe in a production environment -- from pre-deployment preparation through security hardening and ongoing monitoring.
Production Network Architecture
The following diagram shows which services are exposed externally versus isolated on the internal Docker network.
In production, only NGINX ports 80 and 443 should be exposed to the network. All other services communicate exclusively over the internal Docker bridge network.
1. Pre-Deployment Checklist
Complete these items before starting the production stack.
Hardware Verification
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores | 8+ cores |
| RAM | 8 GB | 16-32 GB |
| Storage | 50 GB SSD | 200+ GB NVMe SSD |
| GPU | NVIDIA with 6 GB VRAM | NVIDIA with 12+ GB VRAM |
| NVIDIA Driver | 525+ | 535+ |
Verify GPU availability:
nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
DNS and Domain
- Point your domain (e.g.,
transcribe.example.com) to your server's public IP via an A record. - Verify resolution:
dig +short transcribe.example.com - For internal/homelab deployments, configure local DNS or hosts files (see the NGINX Setup guide).
SSL/TLS Certificates
For publicly accessible deployments, use Let's Encrypt:
sudo apt install certbot
sudo certbot certonly --standalone -d transcribe.example.com
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
For internal deployments, generate self-signed certificates:
./scripts/generate-ssl-cert.sh opentranscribe.local --auto-ip
HuggingFace Token
A HuggingFace token is required for downloading the PyAnnote speaker diarization pipeline. You must accept its model license agreement — from the same account that issues the token — or the token will fail with HTTP 403 as if it were invalid. The gate is per-account, not just per-repo.
- Create an account at huggingface.co
- Accept the license for pyannote/speaker-diarization-community-1 — it's CC-BY-4.0 and auto-approved (no waiting list). This is the only gated model either diarization engine loads; see HuggingFace Token Setup for the older
speaker-diarization-3.1/segmentation-3.0pair this replaced. - Generate an access token at huggingface.co/settings/tokens
- Add to your
.envfile:HUGGINGFACE_TOKEN=hf_your_token_here
Pre-Download AI Models
Download all AI models before starting the stack, especially for air-gapped or bandwidth-constrained environments:
bash scripts/download-models.sh models
This downloads approximately 2.5 GB of models to ${MODEL_CACHE_DIR:-./models}/, including WhisperX, PyAnnote, sentence-transformers, and OpenSearch neural search models.
2. Production Docker Compose
OpenTranscribe uses a layered Docker Compose pattern. Production deployments combine the base configuration with production-specific overrides.
Compose File Stack
| File | Purpose |
|---|---|
docker-compose.yml | Base configuration shared by all environments |
docker-compose.prod.yml | Production overrides (Docker Hub images, pull policies) |
docker-compose.nginx.yml | NGINX reverse proxy service |
docker-compose.local.yml | Prevents pulling from Docker Hub (use with local builds) |
docker-compose.pki.yml | PKI/mTLS certificate authentication overlay |
Starting Production
The recommended way to start production is through the management script:
./opentr.sh start prod
This automatically selects the correct compose files, detects GPU availability, checks model permissions, and starts all services in the correct order.
For manual control:
docker compose \
-f docker-compose.yml \
-f docker-compose.prod.yml \
-f docker-compose.nginx.yml \
up -d
Restart Policies
All services in the base configuration use restart: always, which means containers restart automatically after crashes or host reboots. Docker's restart policy also applies after a system reboot if the Docker daemon is enabled as a systemd service:
sudo systemctl enable docker
Security Options
Every service in the base configuration includes security_opt: [no-new-privileges:true], which prevents privilege escalation inside containers.
3. Reverse Proxy and SSL/TLS
NGINX acts as the single entry point for all external traffic, terminating TLS and proxying requests to internal services.
NGINX Configuration
The NGINX configuration template lives at nginx/site.conf.template. Environment variables are substituted at container startup via envsubst.
Key settings in the production NGINX config:
# TLS protocols -- only modern, secure versions
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
# Session caching for performance
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;
# HSTS -- force HTTPS for one year
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
# Large file uploads (audio/video up to 15 GB, matching MAX_UPLOAD_BYTES's default)
client_max_body_size 15G;
client_body_timeout 600s;
Environment Variables
| Variable | Default | Description |
|---|---|---|
NGINX_SERVER_NAME | (unset) | Hostname for the NGINX server block. Setting it is what adds docker-compose.nginx.yml to the stack (./opentr.sh start prod and ./opentranscribe.sh start both do this, and refuse to start if the certificate files are missing) |
NGINX_HTTP_PORT | 80 | HTTP port (redirects to HTTPS) |
NGINX_HTTPS_PORT | 443 | HTTPS port |
NGINX_CERT_FILE | ./nginx/ssl/server.crt | Path to SSL certificate |
NGINX_CERT_KEY | ./nginx/ssl/server.key | Path to SSL private key |
Let's Encrypt Auto-Renewal
Set up a cron job for automatic certificate renewal:
# Test renewal first
sudo certbot renew --dry-run
# Add monthly renewal to crontab
echo "0 0 1 * * certbot renew --quiet && docker compose restart nginx" | sudo tee -a /etc/crontab
Proxy Routes
| Path | Upstream | Purpose |
|---|---|---|
/ | frontend:8080 | Svelte SPA |
/api/ws | backend:8080 | WebSocket notifications |
/api/ | backend:8080 | REST API |
/docs/ | docs:8080 | Embedded documentation site |
/flower/ | flower:5555 | Celery monitoring dashboard (admin and super admin only: nginx checks the session with auth_request before proxying) |
/minio/ | minio:9001 | MinIO console |
/s3/ | minio:9000 | S3 API (presigned URLs) |
/metrics, /metrics/queues | (none) | Answered with 404 at the proxy; Prometheus scrapes the backend over the internal network |
4. Database Hardening
PostgreSQL Tuning
The base docker-compose.yml includes production-tuned PostgreSQL parameters passed via the command directive. All values are configurable through .env variables:
| Parameter | Default | .env Variable | Purpose |
|---|---|---|---|
shared_buffers | 256MB | PG_SHARED_BUFFERS | Memory for caching data pages (set to ~25% of available RAM) |
effective_cache_size | 1GB | PG_EFFECTIVE_CACHE_SIZE | Planner estimate of OS cache (set to ~50-75% of RAM) |
work_mem | 16MB | PG_WORK_MEM | Per-operation sort/hash memory |
maintenance_work_mem | 128MB | PG_MAINTENANCE_WORK_MEM | Memory for VACUUM, CREATE INDEX |
random_page_cost | 1.1 | PG_RANDOM_PAGE_COST | SSD-optimized (use 4.0 for spinning disks) |
effective_io_concurrency | 200 | PG_EFFECTIVE_IO_CONCURRENCY | SSD-optimized (use 2 for spinning disks) |
max_connections | 200 | PG_MAX_CONNECTIONS | Maximum concurrent connections |
wal_buffers | 16MB | (hardcoded) | Write-ahead log buffer |
checkpoint_completion_target | 0.9 | (hardcoded) | Spread checkpoint I/O |
Recommendations for larger deployments:
# .env -- for a server with 32 GB RAM and NVMe SSD
PG_SHARED_BUFFERS=8GB
PG_EFFECTIVE_CACHE_SIZE=24GB
PG_WORK_MEM=64MB
PG_MAINTENANCE_WORK_MEM=512MB
PG_MAX_CONNECTIONS=300
Connection Security
- PostgreSQL's host port is published on
127.0.0.1only (POSTGRES_PORT, default 5176), so it is not reachable from the network. - Set strong credentials in
.env:
POSTGRES_USER=opentranscribe
POSTGRES_PASSWORD=<generate-a-strong-random-password>
POSTGRES_DB=opentranscribe
- The loopback mapping cannot be removed by unsetting
POSTGRES_PORT(the compose file falls back to the default when the variable is unset or empty). Leave it, or drop it with your own compose override if you do not want even local host access.
Backups
Use the built-in backup command:
./opentranscribe.sh backup
This creates a timestamped SQL dump and a matching .voiceprints.ndjson file (speaker voiceprints, which are not in PostgreSQL) in the backups/ directory; keep the two together. See Backup & Restore, including the built-in scheduled backups. For OS-level automated backups, add a cron job:
0 2 * * * cd /opt/opentranscribe && ./opentranscribe.sh backup
5. MinIO Security
Credentials
Set strong MinIO credentials in .env:
MINIO_ROOT_USER=opentranscribe-admin
MINIO_ROOT_PASSWORD=<generate-a-strong-random-password>
Bucket Policy
OpenTranscribe creates a private bucket on startup. Verify the bucket is not publicly accessible:
# From inside the backend container
mc alias set local http://minio:9000 $MINIO_ROOT_USER $MINIO_ROOT_PASSWORD
mc policy get local/opentranscribe
# Should show: "none" (private)
Encryption at Rest
MinIO supports server-side encryption (AES-256-GCM). The installer enables it automatically on
fresh installs; to configure it manually in .env:
# Generate a key
echo "opentranscribe-key:$(openssl rand -base64 32)"
# Add to .env
MINIO_KMS_SECRET_KEY=opentranscribe-key:<base64-encoded-key>
MINIO_KMS_AUTO_ENCRYPTION=on
All new objects will be automatically encrypted. Existing unencrypted objects remain readable.
MinIO encryption covers media files only. Transcript text also lives in PostgreSQL and the
OpenSearch index, neither of which has built-in at-rest encryption — protect those with
full-disk encryption (LUKS/dm-crypt) or by placing the data volumes on an encrypted
filesystem. See Security Hardening for the full
data-protection picture, including encrypted backups (./opentranscribe.sh backup --encrypt).
Access Key Rotation
Periodically rotate MinIO credentials:
- Update
MINIO_ROOT_USERandMINIO_ROOT_PASSWORDin.env - Restart the stack:
./opentr.sh stop && ./opentr.sh start prod
Native AWS S3 Backend (alternative to MinIO)
Object storage is not hardwired to the bundled MinIO container. Setting STORAGE_BACKEND=s3
targets a real regional AWS S3 endpoint (or any S3-compatible provider via S3_ENDPOINT_URL)
instead:
STORAGE_BACKEND=s3
S3_REGION=us-east-1
S3_USE_IAM_ROLE=true # default: AWS credential chain (env / EKS-IRSA / ECS task role / EC2 instance metadata) -- no static keys, automatic rotation
Set S3_USE_IAM_ROLE=false and provide AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY only if the
deployment cannot use the AWS credential chain. STORAGE_BACKEND=minio remains the default, and
self-hosted behavior (endpoint, credentials, addressing, presigned-URL rewriting) is unchanged
when it's in effect. Amazon Transcribe, if you use it as an ASR provider, additionally requires AWS_TRANSCRIBE_BUCKET
(a private bucket you own, in AWS_REGION; there is no default). See
Environment Variables
for the full variable reference, including presigned-URL TTL clamping
(PRESIGNED_URL_MAX_SECONDS) and the multipart-upload threshold.
On the bundled MinIO backend, quarantining a file immediately revokes presigned media URLs that
were already handed out (a restricted signing identity denies reads of quarantined objects). That
identity is created through MinIO's admin API, which S3 does not have, so on STORAGE_BACKEND=s3
an already-issued URL for a quarantined file stays valid until it expires. New URLs are never
issued for a quarantined file either way.
Two mitigations, which can be combined:
-
Shorten the window.
MEDIA_URL_EXPIRE_SECONDS(default 21600 = 6 h, capped byPRESIGNED_URL_MAX_SECONDS) is the longest an issued URL can outlive a takedown. Lowering it narrows the exposure, at the cost of long recordings needing a fresh URL mid-playback. -
Enforce revocation with a bucket policy. Quarantine tags the object
ot-quarantine=true; attach this Deny to the media bucket and S3 rejects reads of tagged objects whoever signed the URL:{"Version": "2012-10-17","Statement": [{"Sid": "DenyQuarantinedReads","Effect": "Deny","Principal": "*","Action": "s3:GetObject","Resource": "arn:aws:s3:::<your-media-bucket>/*","Condition": { "StringEquals": { "s3:ExistingObjectTag/ot-quarantine": "true" } }}]}Because the Deny applies to every principal, the backend itself also cannot read a quarantined file's media (reprocessing, download, export) until it is released.
The bucket policy only enforces a tag that landed. The app's own identity must also be allowed to
read and write object tags, or every takedown leaves issued URLs working (see the permissions
below). See docs/abuse-and-takedown.md in the repository for the full takedown design.
Permissions quarantine needs on S3
Grant these to the identity OpenTranscribe signs with (the IAM role, or the static key when
S3_USE_IAM_ROLE=false), in addition to the read, write, delete and list permissions it already
needs for media:
| Action | Resource | Used for |
|---|---|---|
s3:GetObjectTagging | arn:aws:s3:::<your-media-bucket>/* | Reading an object's tags before adding or removing ot-quarantine (tags are replaced as a whole set, so the others are kept) |
s3:PutObjectTagging | arn:aws:s3:::<your-media-bucket>/* | Setting ot-quarantine=true on quarantine and clearing it on release, on the original, thumbnail and playback copy |
s3:GetBucketPolicy | arn:aws:s3:::<your-media-bucket> | Confirming the Deny above is attached, at startup and on every quarantine |
s3:PutObjectLegalHold | arn:aws:s3:::<your-media-bucket>/* | Optional. The storage legal hold placed with a takedown, only on a bucket created with Object Lock |
s3:ListBucket | arn:aws:s3:::<your-cache-bucket> | Finding a file's download renders and exports in the cache bucket |
s3:DeleteObject | arn:aws:s3:::<your-cache-bucket>/* | Deleting those copies on quarantine (they are rebuilt on demand after a release) |
s3:PutObject, s3:DeleteObject | _opentranscribe/probes/* in both buckets | The startup probe's throwaway object. A refused delete in the media bucket is logged as a leftover object, not as a missing takedown permission |
s3:DeleteObjectTagging is not needed: releasing a file writes the remaining tag set with
s3:PutObjectTagging.
The Deny counts as enforcing only when it is unconditional apart from the one tag condition:
Deny of s3:GetObject (or s3:Get*, s3:*), to "*" or {"AWS": "*"}, on <bucket>/*,
with exactly StringEquals s3:ExistingObjectTag/ot-quarantine = "true". Anything narrower (an
extra condition, a Not* element, a named principal, a prefix resource) is reported as
enforcement_unverified, never as enforced.
As statements to add to the identity's policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "OpenTranscribeQuarantineTags",
"Effect": "Allow",
"Action": ["s3:GetObjectTagging", "s3:PutObjectTagging"],
"Resource": "arn:aws:s3:::<your-media-bucket>/*"
},
{
"Sid": "OpenTranscribeQuarantinePolicyCheck",
"Effect": "Allow",
"Action": "s3:GetBucketPolicy",
"Resource": "arn:aws:s3:::<your-media-bucket>"
}
]
}
At startup on STORAGE_BACKEND=s3 the backend checks both halves and never refuses to start:
- It reads the bucket policy and logs one WARNING if the Deny is missing or the policy cannot be
read (naming
s3:GetBucketPolicywhen that is the reason), or INFO if revocation is enforced. - It writes a small probe object with a per-boot key (
_opentranscribe/probes/<uuid>), sets and clears the quarantine tag on it and deletes it, then lists and deletes a probe in the cache bucket. A refused call is an ERROR naming each missing action and its bucket; INFO says the identity can do all of it. The probe uses a short-timeout client with no retries. - Caveats: the probe proves permissions under
_opentranscribe/probes/only, so an IAM policy scoped to other prefixes can pass it and still refuse real objects. On a versioned bucket each boot leaves a delete marker there (expire it with a lifecycle rule), and an Object Lock default retention can make the probe delete fail. SetSTORAGE_TAG_PROBE_ENABLED=falseto skip it.
What a quarantine reports
A quarantine always takes the file down in the database, so every list, page, search and new URL hides it straight away, even when storage refuses the tag. Whether links that were already issued stop working is reported, never assumed:
- The API response (
POST /api/admin/files/{uuid}/quarantineand the release route) carriespresign_revoked(orpresign_tag_clearedon release) and amedia_revocationobject:complete, areason(tag_write_failed,enforcement_missing,enforcement_unverified,tag_clear_failed,copy_removal_failed),enforcement(bucket_policy,none,unknown),missing_permissions,exposure_secondsand one entry per object, including each download render or export deleted from the cache bucket. - The organization-admin routes return only
action,complete,exposure_secondsand a genericreason(revocation_incompleteorrestore_incomplete), still with status 200. - The audit event has outcome
partialinstead ofsuccess. On a personal file it records the same fields; on an organization's file, whose audit log that organization's admins can read and export, it records onlycompleteand the generic reason, and the storage detail is in the backend log. - The backend logs an ERROR naming the missing actions, and the admin UI shows a warning instead of a plain success.
Verify that an issued URL stops working
With a test file you are allowed to take down, signed in as an administrator ($COOKIES holds
the session cookie, $CSRF the CSRF token, $HOST your site):
# 1. Issue a media URL and fetch it the way the player does
URL=$(curl -s -b "$COOKIES" "https://$HOST/api/files/$FILE/stream-url?media_type=video" | jq -r .url)
curl -s -o /dev/null -w '%{http_code}\n' -H 'Range: bytes=0-1' "$URL" # 206
# 2. Quarantine the file; the response must say the URL was revoked
curl -s -b "$COOKIES" -H "X-CSRF-Token: $CSRF" -H 'Content-Type: application/json' \
-d '{"reason":"revocation check","operator_action_reason":"operator verification"}' \
"https://$HOST/api/admin/files/$FILE/quarantine" | jq '.presign_revoked, .media_revocation'
# true, complete: true
# 3. The SAME URL is now refused
curl -s -o /dev/null -w '%{http_code}\n' -H 'Range: bytes=0-1' "$URL" # 403
# 4. Release it; the same URL works again
curl -s -b "$COOKIES" -H "X-CSRF-Token: $CSRF" -H 'Content-Type: application/json' \
-d '{"clear_legal_hold":true}' "https://$HOST/api/admin/files/$FILE/release" \
| jq '.presign_tag_cleared' # true
curl -s -o /dev/null -w '%{http_code}\n' -H 'Range: bytes=0-1' "$URL" # 206
If step 2 prints false, media_revocation.reason and missing_permissions say what to fix,
and step 3 will still return 206 until you do. The quarantine creates a notice record and is
audited like any other, so use a file and a reason you are happy to keep in the history.
MinIO accepts a single-PUT object up to 5 TiB; AWS S3 rejects one above 5 GiB. On
STORAGE_BACKEND=s3, uploads above that size are always routed through the multipart path, so
this only affects very large source files, not typical media uploads.
6. Redis Security
Password Authentication
Set a Redis password in .env:
REDIS_PASSWORD=<generate-a-strong-random-password>
The base docker-compose.yml automatically starts Redis with --requirepass when REDIS_PASSWORD is set. All services (backend, Celery workers, Flower) read REDIS_PASSWORD from the environment and include it in their connection strings.
Persistence
Redis is configured with a named volume (redis_data) for persistence. The default persistence strategy (RDB snapshots) is sufficient for OpenTranscribe's use case -- Redis stores Celery task state, cached GPU stats, and the shared security state described below, not primary data.
Redis also carries security state -- plan for its loss
Beyond the Celery broker, Redis holds the shared state that several security controls depend on:
- the token revocation blacklist (JTIs invalidated by logout-all, password reset, or admin session termination)
- account lockout counters
- MFA single-use token (replay) protection
- authentication rate limiting
That state is shared through Redis, not held in the backend process. If Redis becomes unreachable, the backend falls back to its own process memory, which is empty on start and lost on every restart -- so a Redis outage on this deployment's single backend means a session revoked just before the outage would still be honoured until Redis (or the fallback below) recovers.
:::note Single backend replica only
OpenTranscribe does not support running more than one backend replica (no leader election;
a second replica races search_index_maintenance on startup — see
operations/performance-tuning.md). This section is about surviving a Redis outage on the
one backend, not about coordinating multiple backends.
:::
OpenTranscribe handles the Redis-loss case rather than degrading silently:
- Token revocation falls back to the database.
refresh_token.revoked_atis durable, so revocation keeps working and nobody is logged out during a Redis outage. - Where no durable record exists, the control fails closed or tightens rather than loosening.
- Degradation is logged at
CRITICALand increments the Prometheus countersecurity_state_degraded_total{control,fallback}.
Alert on security_state_degraded_total. A non-zero rate means a security control is running without its shared state store. There is deliberately no configuration flag to disable this behaviour -- an off-switch on a security control tends to get flipped during exactly the incident it guards against.
On AWS, use ElastiCache for Redis with Multi-AZ and automatic failover rather than a single Redis container. Failover then takes seconds instead of leaving the cluster in the degraded state above for the length of an outage.
Note that Redis is also the Celery broker, so a Redis outage stops transcription regardless -- highly available Redis protects throughput and security posture together.
Network Isolation
Redis's host port is published on 127.0.0.1 only (REDIS_PORT, default 5177), so it is not reachable from the network. Do not widen that binding.
When using a managed Redis (ElastiCache or equivalent), enable encryption in transit and point REDIS_URL at the rediss:// scheme -- the Celery configuration detects it and enables TLS for both the broker and the result backend.
7. OpenSearch Security
JVM Heap Sizing
The base configuration sets the OpenSearch JVM heap to 4 GB, and bootstrap.memory_lock=true pins it in RAM at startup:
OPENSEARCH_JAVA_OPTS=-Xms4g -Xmx4g
Heap is sized for the embedding model, not for your transcript count — the measured floors are 1 GB for the default model and 2 GB for every English model, including the 768-dimension ones. See Performance Tuning for the measurements.
Keep Xms equal to Xmx; a differing pair makes the JVM resize the heap at runtime and bootstrap.memory_lock expects a fixed heap. Never exceed 50% of available RAM, or ~30 GB (JVM compressed oops threshold).
Update in .env or directly in your compose override:
OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g
Security Plugin
By default, OpenSearch runs with the security plugin disabled (DISABLE_SECURITY_PLUGIN=true) for simplicity. This is acceptable when OpenSearch is isolated on the Docker network with no exposed ports.
To enable the security plugin in production (required if OpenSearch is exposed or you need audit logging):
# .env
OPENSEARCH_DISABLE_SECURITY=false
OPENSEARCH_ADMIN_PASSWORD=<strong-password>
OPENSEARCH_USE_TLS=true
You will also need TLS certificates for inter-node transport. See the docker-compose.prod.yml for the certificate path configuration.
Amazon OpenSearch Service (SigV4)
A managed Amazon OpenSearch Service domain uses an IAM access policy instead of the self-hosted security plugin, and requires SigV4-signed requests rather than basic auth:
OPENSEARCH_AUTH=sigv4 # default: basic (unchanged for self-hosted OpenSearch)
OPENSEARCH_AWS_REGION= # empty falls back to AWS_REGION
OPENSEARCH_AWS_SERVICE=es # es (managed domain) or aoss (OpenSearch Serverless)
OPENSEARCH_AUTH=sigv4 signs every OpenSearch client with the AWS credential chain and forces
TLS. Pair it with OPENSEARCH_EMBEDDING_MODE=managed (see
Environment Variables)
if the domain already hosts the neural-search embedding model -- a managed domain does not permit
registering a model by URL or mutating ML Commons cluster settings the way self-hosted
initialization does.
Memory Locking
The base configuration uses memlock ulimits to prevent OpenSearch from being swapped to disk:
ulimits:
memlock:
soft: -1
hard: -1
Ensure the host system allows memory locking:
# Add to /etc/security/limits.conf
opensearch soft memlock unlimited
opensearch hard memlock unlimited
8. Container Security
Non-Root Execution
All backend containers run as a non-root user (appuser, UID 1000, GID 999 — the Dockerfile uses groupadd -r). This follows the principle of least privilege and is enforced in the production Dockerfile.
The appuser is a member of the video group for GPU access.
Permission Management
The model cache directory must be owned by UID 1000 for the container user to read/write models:
# Automatic (run by opentr.sh on startup)
./scripts/fix-model-permissions.sh
# Manual
sudo chown -R 1000:999 ${MODEL_CACHE_DIR:-./models}
Security Options
Every service includes:
security_opt:
- no-new-privileges:true
This prevents processes inside containers from gaining additional privileges through setuid, setgid, or Linux capabilities.
Resource Limits
For production deployments, add resource limits to prevent any single service from consuming all host resources. Add to a custom override file:
# docker-compose.limits.yml
services:
backend:
deploy:
resources:
limits:
memory: 4G
cpus: "4"
postgres:
deploy:
resources:
limits:
memory: 4G
opensearch:
deploy:
resources:
limits:
memory: 4G
redis:
deploy:
resources:
limits:
memory: 1G
9. Network Isolation
Docker Network Architecture
All services communicate over a single Docker bridge network (default). In production, only NGINX should have ports mapped to the host.
Restricting Exposed Ports
The published host ports fall into two groups. Unsetting the variables does not remove a mapping, because every mapping is written ${VAR:-default} and an unset or empty variable falls back to the default.
| Binding | Services (variable, default port) | Reachable from the network? |
|---|---|---|
127.0.0.1 only | PostgreSQL (POSTGRES_PORT 5176), Redis (REDIS_PORT 5177), MinIO API and console (MINIO_PORT 5178, MINIO_CONSOLE_PORT 5179), OpenSearch (OPENSEARCH_PORT 5180, OPENSEARCH_ADMIN_PORT 5181), Flower (FLOWER_PORT 5175) | No |
| All interfaces | Backend API (BACKEND_PORT 5174), frontend (FRONTEND_PORT 5173), docs (DOCS_PORT 5183) | Yes, unless you firewall them |
With the NGINX overlay, close the second group from outside the host: set BACKEND_BIND_HOST=127.0.0.1 in .env to bind the backend port to loopback, and block 5173, 5174 and 5183 in the host firewall below. The frontend and docs ports have no bind-host variable. Docker publishes ports through its own iptables rules, which bypass ufw's default rules, so verify from another machine (nc -zv <host> 5174) rather than trusting the ufw status output.
Host Firewall
Configure the host firewall to allow only necessary inbound traffic:
# Allow SSH
sudo ufw allow 22/tcp
# Allow HTTPS
sudo ufw allow 443/tcp
# Allow HTTP (for HTTPS redirect)
sudo ufw allow 80/tcp
# Enable firewall
sudo ufw enable
10. CSP and Security Headers
The NGINX configuration includes a comprehensive set of security headers following OWASP recommendations:
| Header | Value | Purpose |
|---|---|---|
Strict-Transport-Security | max-age=31536000; includeSubDomains | Force HTTPS for one year |
X-Frame-Options | SAMEORIGIN | Prevent clickjacking |
X-Content-Type-Options | nosniff | Prevent MIME-type sniffing |
X-XSS-Protection | 0 | Disabled (CSP is the modern replacement) |
Referrer-Policy | strict-origin-when-cross-origin | Limit referrer information |
Permissions-Policy | camera=(), microphone=(self), ... | Restrict browser features |
Cross-Origin-Opener-Policy | same-origin | Sever opener handles to cross-origin windows (frontend nginx) |
Cross-Origin-Resource-Policy | same-origin | Stop other origins embedding the app's documents and assets (frontend nginx) |
Content-Security-Policy | (see below) | Control resource loading |
Content Security Policy
The default CSP is:
default-src 'self';
script-src 'self' 'unsafe-inline';
style-src 'self' 'unsafe-inline';
img-src 'self' data: blob:;
font-src 'self' data:;
connect-src 'self';
media-src 'self' blob:;
worker-src 'self' blob:;
frame-ancestors 'self';
object-src 'none';
base-uri 'self';
form-action 'self';
This policy allows the Svelte SPA and WebSocket connections to function while blocking external resource loading, iframes from other origins, and plugin-based content.
connect-src 'self' covers the notifications WebSocket: under CSP Level 3, 'self' matches ws:/wss: on the page's own host. Bare ws:/wss: sources were removed because they allowed a socket to any host (#1028). If you rewrite this directive with sub_filter, match connect-src 'self', and add an explicit scheme+host rather than a bare scheme.
Cross-Origin-Embedder-Policy is deliberately not sent: require-corp would block presigned object-storage media and thumbnails. The frontend nginx sends a single Cache-Control per response (no-store, ... for HTML, public, max-age=31536000, no-transform for hashed static assets).
11. Secrets Management
The .env File
The .env file contains all sensitive configuration. Protect it:
# Restrict permissions
chmod 600 .env
# Verify it is in .gitignore
grep -q "^\.env$" .gitignore && echo "OK" || echo "ADD .env TO .gitignore"
Never commit .env to version control. The repository includes .env.example as a template.
Critical Secrets
Generate strong, unique values for each of these:
| Secret | .env Variable | Generation Command |
|---|---|---|
| JWT Secret | JWT_SECRET_KEY | openssl rand -hex 32 |
| PostgreSQL Password | POSTGRES_PASSWORD | openssl rand -base64 24 |
| MinIO Root Password | MINIO_ROOT_PASSWORD | openssl rand -base64 24 |
| Redis Password | REDIS_PASSWORD | openssl rand -base64 24 |
| Flower Password | FLOWER_PASSWORD | openssl rand -base64 16 |
| Encryption master key | ENCRYPTION_KEY | openssl rand -hex 32 (never change after first use; it decrypts every secret stored in the database, and a backup is unreadable without it) |
| MinIO Encryption Key | MINIO_KMS_SECRET_KEY | echo "key:$(openssl rand -base64 32)" |
| HuggingFace Token | HUGGINGFACE_TOKEN | (from huggingface.co) |
Credential Rotation
- Update the credential in
.env - Stop the stack:
./opentr.sh stop - Start the stack:
./opentr.sh start prod - Verify services are healthy:
./opentr.sh status
For PostgreSQL password changes, you must also update the password in the database itself before restarting:
./opentr.sh shell postgres
psql -U $POSTGRES_USER -c "ALTER USER $POSTGRES_USER WITH PASSWORD 'new-password';"
12. Health Checks
Every service in the stack has a Docker health check. These are used for startup ordering (depends_on: condition: service_healthy) and ongoing monitoring.
| Service | Health Check | Interval | Purpose |
|---|---|---|---|
| PostgreSQL | pg_isready -U $POSTGRES_USER | 5s | Verifies database accepts connections |
| MinIO | curl -f http://localhost:9000/minio/health/live | 5s | Verifies S3 API is responsive |
| Redis | redis-cli ping (with auth if configured) | 5s | Verifies Redis responds to PING |
| OpenSearch | curl -sS http://localhost:9200 | 5s | Verifies cluster status endpoint |
| Backend | curl -f http://localhost:8080/health | 10s | Verifies API is serving requests |
| Frontend (prod) | wget --spider -q http://127.0.0.1:8080 | 10s | Verifies static assets are served |
| Celery Workers | python3 scripts/celery_pool_healthcheck.py <hostname> | 30s | Verifies the worker answers control commands and its child pool is alive |
| Celery Beat | Newest /app/celerybeat-schedule* file modified < 300s ago | 30s | Verifies scheduler is writing heartbeats |
| Flower | curl -fs http://127.0.0.1:5555/${FLOWER_URL_PREFIX:-flower}/healthcheck | 30s | Verifies Flower's own healthcheck endpoint (bypasses basic auth) |
Monitoring Health
Check all service health at once:
./opentr.sh status
# or
docker compose ps
For continuous monitoring, pipe health status to your monitoring system:
# Simple health check script
docker inspect --format='{{.Name}}: {{.State.Health.Status}}' \
$(docker ps -q --filter "label=com.docker.compose.project=opentranscribe")
13. Production Startup
Full Startup Procedure
# 1. Verify environment file
cat .env | grep -E "^(POSTGRES_PASSWORD|JWT_SECRET_KEY|MINIO_ROOT_PASSWORD|REDIS_PASSWORD|HUGGINGFACE_TOKEN)" \
| sed 's/=.*/=***/' # Confirm secrets are set without revealing them
# 2. Fix model cache permissions
./scripts/fix-model-permissions.sh
# 3. Pre-download models (if not already cached)
bash scripts/download-models.sh models
# 4. Start production stack
./opentr.sh start prod
# 5. Verify all services are healthy
./opentr.sh status
# 6. Check logs for errors
./opentr.sh logs backend
./opentr.sh logs celery-worker
Verifying the Deployment
After startup, verify each component:
# Backend API
curl -k https://transcribe.example.com/health
# Frontend
curl -k -o /dev/null -s -w "%{http_code}" https://transcribe.example.com/
# OpenSearch (from inside Docker network)
docker exec opentranscribe-backend curl -s http://opensearch:9200/_cluster/health | python3 -m json.tool
# GPU worker
docker exec opentranscribe-celery-worker nvidia-smi
Post-Deployment
- Sign in as the bootstrap admin -- On first start the backend creates a
super_adminfromINITIAL_ADMIN_EMAIL/INITIAL_ADMIN_PASSWORD. In production, leaving the password empty generates a random one that is logged once at startup (and forces a password change at first login); read it with./opentr.sh logs backend. - Configure authentication -- Navigate to Settings and configure your preferred authentication method(s).
- Test a transcription -- Upload a short audio file and verify the full pipeline (upload, transcription, diarization, search indexing).
- Set up monitoring -- Configure alerting on container health checks and disk usage.
- Schedule backups -- Add
./opentranscribe.sh backupto cron for automated database backups.
Quick Reference: Production .env Template
# === Core Secrets ===
JWT_SECRET_KEY=<openssl rand -hex 32>
POSTGRES_USER=opentranscribe
POSTGRES_PASSWORD=<openssl rand -base64 24>
POSTGRES_DB=opentranscribe
MINIO_ROOT_USER=opentranscribe-admin
MINIO_ROOT_PASSWORD=<openssl rand -base64 24>
REDIS_PASSWORD=<openssl rand -base64 24>
HUGGINGFACE_TOKEN=hf_your_token_here
# === NGINX ===
NGINX_SERVER_NAME=transcribe.example.com
# === Flower Monitoring ===
FLOWER_USER=admin
FLOWER_PASSWORD=<openssl rand -base64 16>
# === MinIO Encryption ===
MINIO_KMS_SECRET_KEY=opentranscribe-key:<openssl rand -base64 32>
MINIO_KMS_AUTO_ENCRYPTION=on
# === PostgreSQL Tuning (adjust for your hardware) ===
PG_SHARED_BUFFERS=256MB
PG_EFFECTIVE_CACHE_SIZE=1GB
PG_WORK_MEM=16MB
PG_MAX_CONNECTIONS=200
# === Model Cache ===
MODEL_CACHE_DIR=./models
# === Remove host port mappings in production ===
# (services are accessed through NGINX only)
# POSTGRES_PORT=
# REDIS_PORT=
# MINIO_PORT=
# OPENSEARCH_PORT=