Skip to main content

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​

ComponentMinimumRecommended
CPU4 cores8+ cores
RAM8 GB16-32 GB
Storage50 GB SSD200+ GB NVMe SSD
GPUNVIDIA with 6 GB VRAMNVIDIA with 12+ GB VRAM
NVIDIA Driver525+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.

  1. Create an account at huggingface.co
  2. 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.0 pair this replaced.
  3. Generate an access token at huggingface.co/settings/tokens
  4. Add to your .env file: 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​

FilePurpose
docker-compose.ymlBase configuration shared by all environments
docker-compose.prod.ymlProduction overrides (Docker Hub images, pull policies)
docker-compose.nginx.ymlNGINX reverse proxy service
docker-compose.local.ymlPrevents pulling from Docker Hub (use with local builds)
docker-compose.pki.ymlPKI/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​

VariableDefaultDescription
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_PORT80HTTP port (redirects to HTTPS)
NGINX_HTTPS_PORT443HTTPS port
NGINX_CERT_FILE./nginx/ssl/server.crtPath to SSL certificate
NGINX_CERT_KEY./nginx/ssl/server.keyPath 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​

PathUpstreamPurpose
/frontend:8080Svelte SPA
/api/wsbackend:8080WebSocket notifications
/api/backend:8080REST API
/docs/docs:8080Embedded documentation site
/flower/flower:5555Celery monitoring dashboard (admin and super admin only: nginx checks the session with auth_request before proxying)
/minio/minio:9001MinIO console
/s3/minio:9000S3 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:

ParameterDefault.env VariablePurpose
shared_buffers256MBPG_SHARED_BUFFERSMemory for caching data pages (set to ~25% of available RAM)
effective_cache_size1GBPG_EFFECTIVE_CACHE_SIZEPlanner estimate of OS cache (set to ~50-75% of RAM)
work_mem16MBPG_WORK_MEMPer-operation sort/hash memory
maintenance_work_mem128MBPG_MAINTENANCE_WORK_MEMMemory for VACUUM, CREATE INDEX
random_page_cost1.1PG_RANDOM_PAGE_COSTSSD-optimized (use 4.0 for spinning disks)
effective_io_concurrency200PG_EFFECTIVE_IO_CONCURRENCYSSD-optimized (use 2 for spinning disks)
max_connections200PG_MAX_CONNECTIONSMaximum concurrent connections
wal_buffers16MB(hardcoded)Write-ahead log buffer
checkpoint_completion_target0.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.1 only (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.

note

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:

  1. Update MINIO_ROOT_USER and MINIO_ROOT_PASSWORD in .env
  2. 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.

Quarantine and already-issued media URLs on S3

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 by PRESIGNED_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:

ActionResourceUsed for
s3:GetObjectTaggingarn: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:PutObjectTaggingarn:aws:s3:::<your-media-bucket>/*Setting ot-quarantine=true on quarantine and clearing it on release, on the original, thumbnail and playback copy
s3:GetBucketPolicyarn:aws:s3:::<your-media-bucket>Confirming the Deny above is attached, at startup and on every quarantine
s3:PutObjectLegalHoldarn:aws:s3:::<your-media-bucket>/*Optional. The storage legal hold placed with a takedown, only on a bucket created with Object Lock
s3:ListBucketarn:aws:s3:::<your-cache-bucket>Finding a file's download renders and exports in the cache bucket
s3:DeleteObjectarn: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 bucketsThe 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:GetBucketPolicy when 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. Set STORAGE_TAG_PROBE_ENABLED=false to 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}/quarantine and the release route) carries presign_revoked (or presign_tag_cleared on release) and a media_revocation object: complete, a reason (tag_write_failed, enforcement_missing, enforcement_unverified, tag_clear_failed, copy_removal_failed), enforcement (bucket_policy, none, unknown), missing_permissions, exposure_seconds and one entry per object, including each download render or export deleted from the cache bucket.
  • The organization-admin routes return only action, complete, exposure_seconds and a generic reason (revocation_incomplete or restore_incomplete), still with status 200.
  • The audit event has outcome partial instead of success. 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 only complete and 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.

AWS S3's 5 GiB single-PUT ceiling

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_at is 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 CRITICAL and increments the Prometheus counter security_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.

Run Redis highly available in production

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.

BindingServices (variable, default port)Reachable from the network?
127.0.0.1 onlyPostgreSQL (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 interfacesBackend 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:

HeaderValuePurpose
Strict-Transport-Securitymax-age=31536000; includeSubDomainsForce HTTPS for one year
X-Frame-OptionsSAMEORIGINPrevent clickjacking
X-Content-Type-OptionsnosniffPrevent MIME-type sniffing
X-XSS-Protection0Disabled (CSP is the modern replacement)
Referrer-Policystrict-origin-when-cross-originLimit referrer information
Permissions-Policycamera=(), microphone=(self), ...Restrict browser features
Cross-Origin-Opener-Policysame-originSever opener handles to cross-origin windows (frontend nginx)
Cross-Origin-Resource-Policysame-originStop 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 VariableGeneration Command
JWT SecretJWT_SECRET_KEYopenssl rand -hex 32
PostgreSQL PasswordPOSTGRES_PASSWORDopenssl rand -base64 24
MinIO Root PasswordMINIO_ROOT_PASSWORDopenssl rand -base64 24
Redis PasswordREDIS_PASSWORDopenssl rand -base64 24
Flower PasswordFLOWER_PASSWORDopenssl rand -base64 16
Encryption master keyENCRYPTION_KEYopenssl 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 KeyMINIO_KMS_SECRET_KEYecho "key:$(openssl rand -base64 32)"
HuggingFace TokenHUGGINGFACE_TOKEN(from huggingface.co)

Credential Rotation​

  1. Update the credential in .env
  2. Stop the stack: ./opentr.sh stop
  3. Start the stack: ./opentr.sh start prod
  4. 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.

ServiceHealth CheckIntervalPurpose
PostgreSQLpg_isready -U $POSTGRES_USER5sVerifies database accepts connections
MinIOcurl -f http://localhost:9000/minio/health/live5sVerifies S3 API is responsive
Redisredis-cli ping (with auth if configured)5sVerifies Redis responds to PING
OpenSearchcurl -sS http://localhost:92005sVerifies cluster status endpoint
Backendcurl -f http://localhost:8080/health10sVerifies API is serving requests
Frontend (prod)wget --spider -q http://127.0.0.1:808010sVerifies static assets are served
Celery Workerspython3 scripts/celery_pool_healthcheck.py <hostname>30sVerifies the worker answers control commands and its child pool is alive
Celery BeatNewest /app/celerybeat-schedule* file modified < 300s ago30sVerifies scheduler is writing heartbeats
Flowercurl -fs http://127.0.0.1:5555/${FLOWER_URL_PREFIX:-flower}/healthcheck30sVerifies 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​

  1. Sign in as the bootstrap admin -- On first start the backend creates a super_admin from INITIAL_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.
  2. Configure authentication -- Navigate to Settings and configure your preferred authentication method(s).
  3. Test a transcription -- Upload a short audio file and verify the full pipeline (upload, transcription, diarization, search indexing).
  4. Set up monitoring -- Configure alerting on container health checks and disk usage.
  5. Schedule backups -- Add ./opentranscribe.sh backup to 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=