Docker Compose Installation
This guide covers installing OpenTranscribe using Docker Compose - the recommended method for all deployment scenarios.
Quick Installation
The fastest way to install OpenTranscribe is using our one-line installer:
curl -fsSL https://raw.githubusercontent.com/attevon-llc/OpenTranscribe/master/setup-opentranscribe.sh | bash
Skip to Manual Installation if you prefer more control.
The installer sets up the full image by default (local transcription and speaker detection, using a GPU when it finds one). Pass --cpu to run the full image on CPU only, or --lite for the lite image, which has no local transcription or local speaker detection and uses cloud providers for both. Deployment Variants explains the differences and gives the exact commands.
Prerequisites
Required Software
Docker Engine (v20.10+)
# Check Docker version
docker --version
# Expected output
Docker version 20.10.x or higher
Docker Compose (v2.0+)
# Check Docker Compose version
docker compose version
# Expected output
Docker Compose version v2.x.x or higher
Use docker compose (with space), not docker-compose (with hyphen). OpenTranscribe requires Docker Compose V2.
Installing Docker:
- Linux: docs.docker.com/engine/install
- macOS: Docker Desktop for Mac
- Windows: Docker Desktop for Windows with WSL2
System Requirements
See Hardware Requirements for detailed specs.
Minimum:
- 8GB RAM
- 4 CPU cores
- 50GB disk space
- Internet connection (for initial setup)
Recommended:
- 16GB+ RAM
- 8+ CPU cores
- 100GB+ SSD storage
- NVIDIA GPU with 8GB+ VRAM
Optional: NVIDIA GPU
For GPU acceleration with the full image (recommended; the lite image never uses a GPU):
- NVIDIA GPU with CUDA support (GTX 1060 or better)
- NVIDIA Driver (525.60.13 or higher, because the image uses CUDA 12; Blackwell / RTX 50-series cards need 570+)
- NVIDIA Container Toolkit installed
See GPU Setup Guide for installation instructions.
Manual Installation
If you prefer manual installation or need more control:
Step 1: Clone Repository (Development)
For development from source:
# Clone the repository
git clone https://github.com/attevon-llc/OpenTranscribe.git
cd OpenTranscribe
# Make utility script executable
chmod +x opentr.sh
Step 2: Download Production Files (Deployment)
For production deployment with Docker Hub images, keep the base file and the production overlay under their own names. docker-compose.prod.yml only adds image names and volumes on top of the service definitions in docker-compose.yml, so it cannot be renamed over the base file:
# Create directory
mkdir opentranscribe && cd opentranscribe
# Download the base file, the production overlay, the management script and the env template
BASE=https://raw.githubusercontent.com/attevon-llc/OpenTranscribe/master
for f in docker-compose.yml docker-compose.prod.yml opentranscribe.sh .env.example; do
curl -fsSLO "$BASE/$f"
done
chmod +x opentranscribe.sh
opentranscribe.sh also layers optional overlays (GPU, Blackwell, lite, diar-native, NGINX, backup) when it finds them next to the base file, along with the helper scripts under scripts/. The full file list is release-manifest.txt in the repository; the one-line installer downloads all of it, which is why it is the recommended route.
Step 3: Configure Environment
# Copy environment template
cp .env.example .env
# Edit configuration
nano .env # or use your preferred editor
Key variables to configure:
# Security (REQUIRED - replace every CHANGE_ME in .env.example; the installer
# generates these for you). Production refuses to boot on a placeholder
# JWT_SECRET_KEY or an unset REDIS_PASSWORD.
JWT_SECRET_KEY=your-jwt-secret-key
ENCRYPTION_KEY=your-encryption-key # decrypts DB-stored secrets: never change after first use
REDIS_PASSWORD=strong-redis-password
OPENSEARCH_PASSWORD=strong-opensearch-password
FLOWER_PASSWORD=strong-flower-password
MINIO_KMS_SECRET_KEY=opentranscribe-key:<base64-32-bytes> # encryption at rest; generate with: echo "opentranscribe-key:$(openssl rand -base64 32)"
# Generate secrets with
openssl rand -hex 32
# HuggingFace Token (needed for speaker detection on this server; see Step 4)
HUGGINGFACE_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Database (use strong passwords in production)
POSTGRES_PASSWORD=strong-password-here
# Storage
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=strong-minio-password
# GPU Settings (auto-detected by installer)
USE_GPU=true # not in .env.example (default: auto); false for CPU-only
WHISPER_MODEL=large-v3-turbo # large-v3-turbo, large-v3, medium, base
COMPUTE_TYPE=auto # auto (default), float16, float32 or int8
BATCH_SIZE=auto # auto (default) or an integer
# Model Cache (where AI models are stored)
MODEL_CACHE_DIR=./models
See Environment Variables for all options.
Optional: Configure Authentication
OpenTranscribe supports multiple authentication methods. For enterprise deployments, you may want to configure:
- LDAP/Active Directory -
LDAP_ENABLED=true - OpenID Connect -
OIDC_ENABLED=true(any conforming provider;KEYCLOAK_*names still work) - PKI/X.509 -
PKI_ENABLED=true
See Authentication Overview for setup guides.
Step 4: Set Up HuggingFace
This step is required for speaker detection on this server (the full image's default). Speakers detected by a cloud provider (a transcription model that returns speakers, or the pyannote.ai cloud service) do not use this token. The diar-native sidecar's models (speaker detection and voiceprints) are exported on this server from the same gated repository, so a lite install that runs the sidecar for voiceprints needs the token too.
- Get a token at huggingface.co/settings/tokens
- Accept the model agreement for pyannote/speaker-diarization-community-1 — the only repo OpenTranscribe actually gates on
- Add to .env:
HUGGINGFACE_TOKEN=hf_xxxxxxxxxxxx
See HuggingFace Setup for detailed instructions.
Step 5: Download AI Models (Optional but Recommended)
Pre-download models to avoid first-use delays:
./opentranscribe.sh download-models # production install
bash scripts/download-models.sh # source checkout
Either fetches the whole set (transcription, speaker detection, gender classifier,
NLTK, embeddings, chat reranker, neural search, and content redaction) using the
image version your deployment is pinned to. This downloads several GB of AI
models. The exact total depends on which WHISPER_MODEL you selected and how
many neural-search models you enable — see
HuggingFace setup.
Step 6: Start OpenTranscribe
For Development (source code):
./opentr.sh start dev
For Production (Docker Hub images):
./opentranscribe.sh start
Use the script rather than a bare docker compose up -d: it assembles the right chain of compose files (base, production overlay, then GPU, lite, diar-native, NGINX and backup overlays as they apply). ./opentranscribe.sh compose-files prints the chain it chose.
Step 7: Verify Installation
Check that all services are running:
# Check service status
./opentranscribe.sh status
# Check service health
./opentranscribe.sh health
Every container should show Up, and those with a health check should report (healthy): opentranscribe-postgres, -redis, -minio, -opensearch, -backend, -celery-worker and the other -celery-* workers, -flower, -frontend and -docs. A deployment that runs the native diarization sidecar (the default for the full image) also runs a diar-native container.
Check logs for any errors:
# View all logs
./opentranscribe.sh logs
# View specific service logs
./opentranscribe.sh logs backend
./opentranscribe.sh logs celery-worker
Step 8: Access the Application
Open your browser and navigate to:
- Web Interface: http://localhost:5173 (
FRONTEND_PORT) - API Documentation: http://localhost:5174/api/docs (
BACKEND_PORT; off on hardened/production deployments unlessENABLE_API_DOCS=true) - Task Monitor (Flower): http://localhost:5175/flower (
FLOWER_PORT; loginFLOWER_USER/FLOWER_PASSWORD) - MinIO Console: http://localhost:5179 (
MINIO_CONSOLE_PORT, loopback only) - OpenSearch: http://localhost:5180 (
OPENSEARCH_PORT, loopback only)
PostgreSQL (5176), Redis (5177) and the MinIO API (5178) are also published on loopback only.
To sign in the first time, use the bootstrap administrator: admin@example.com (or INITIAL_ADMIN_EMAIL) with INITIAL_ADMIN_PASSWORD if you set one in .env, otherwise the random password the backend logs once at first start (./opentranscribe.sh logs backend). See Quick Start.
Docker Compose Structure
OpenTranscribe uses a base + override pattern:
File Structure
docker-compose.yml # Base configuration (all environments)
docker-compose.override.yml # Development overrides (auto-loaded; source checkout only)
docker-compose.prod.yml # Production overrides (Docker Hub images)
docker-compose.gpu.yml # NVIDIA GPU reservation (docker-compose.blackwell.yml for SM_12x cards)
docker-compose.lite.yml # Lite (CPU-only, cloud ASR) images
docker-compose.diar-native.yml # Native diarization sidecar (+ -gpu.yml for its GPU reservation)
docker-compose.nginx.yml # NGINX reverse proxy / HTTPS
docker-compose.offline.yml # Offline/airgapped overrides
docker-compose.gpu-scale.yml # Multi-GPU scaling overrides
docker-compose.gpu-split.yml # Transcription and diarization on separate GPUs
docker-compose.backup.yml # Scheduled in-app backups
In a production install ./opentranscribe.sh picks the overlays for you. ./opentr.sh does the same for a source checkout.
Usage
Development (with hot reload, from a source checkout):
./opentr.sh start dev
Production (with Docker Hub images):
./opentranscribe.sh start
Offline (airgapped environment): see Offline Installation.
Multi-GPU (parallel processing): see Multi-GPU Scaling. From a source checkout it is ./opentr.sh start dev --gpu-scale.
./opentr.sh and ./opentranscribe.sh build the compose file chain for you. Assembling it by hand with docker compose -f ... silently drops overlays (for example the GPU or diar-native ones), so only do that after checking ./opentranscribe.sh compose-files.
Service Architecture
OpenTranscribe runs as a set of Docker services. The names below are the compose service names; the containers are opentranscribe-<service>.
Core Services
backend (FastAPI)
- REST API server
- WebSocket support
- User authentication
- File management
- Host port: 5174 (
BACKEND_PORT; 8080 inside the container)
frontend (Svelte + Vite in dev, NGINX in production)
- Svelte/TypeScript SPA
- Progressive Web App
- Host port: 5173 (
FRONTEND_PORT)
docs
- The embedded documentation site, proxied at
/docs/in the app - Host port: 5183 (
DOCS_PORT)
postgres (PostgreSQL 17)
- Main database
- User data, transcriptions, speakers
- Host port: 5176 (
POSTGRES_PORT, loopback only)
redis (Redis 8)
- Celery message broker
- Task queue coordination
- Host port: 5177 (
REDIS_PORT, loopback only)
Storage Services
minio (MinIO)
- S3-compatible object storage
- Media files, audio, waveforms
- Host ports: 5178 (API,
MINIO_PORT), 5179 (Console,MINIO_CONSOLE_PORT), both loopback only
opensearch (OpenSearch 3.4.0)
- Full-text search
- Vector search for semantic search (neural search with ML Commons)
- Alias-based speaker indices for zero-downtime upgrades
- Host ports: 5180 (
OPENSEARCH_PORT), 5181 (OPENSEARCH_ADMIN_PORT), both loopback only
Worker Services
All workers run the backend image and differ by the queues they consume.
- celery-worker - GPU queue: transcription and local speaker detection (3-stage pipeline: preprocess, transcribe, postprocess)
- celery-cpu-worker - CPU, utility and CPU-transcribe queues
- celery-nlp-worker - NLP (summaries, topics) queue
- celery-embedding-worker - search indexing and embeddings
- celery-download-worker - media URL downloads
- celery-cloud-asr-worker - cloud ASR provider calls
- celery-redaction - content redaction
- celery-beat - scheduled tasks
- diar-native - the native diarization sidecar (the default speaker-detection engine of the full image), added by
docker-compose.diar-native.yml
The multi-GPU profiles add celery-worker-gpu-scaled (--gpu-scale) or celery-worker-gpu-transcribe / celery-worker-gpu-diarize (GPU split).
flower (Celery monitoring)
- Industry-standard task monitoring with persistent history
- Worker status, queue visibility, task inspection
- Basic auth protection (configured via
FLOWER_USER/FLOWER_PASSWORD) - Host port: 5175 (
FLOWER_PORT, loopback only; 5555 inside the container)
Management Commands
Starting and Stopping
# Start all services
./opentranscribe.sh start
# Stop all services
./opentranscribe.sh stop
# Restart all services
./opentranscribe.sh restart
# Stop and remove volumes (deletes data!)
./opentranscribe.sh clean
Viewing Logs
# View logs for all services, or one service
./opentranscribe.sh logs
./opentranscribe.sh logs backend
./opentranscribe.sh logs celery-worker
Accessing Containers
# Open a shell in a container (backend by default)
./opentranscribe.sh shell
./opentranscribe.sh shell postgres
# Access the database (inside the postgres shell)
psql -U postgres -d opentranscribe
# Check worker status (inside the celery-worker shell)
celery -A app.core.celery inspect active
Updating
# Back up the database first
./opentranscribe.sh backup
# Pull the latest images and restart (production deployment)
./opentranscribe.sh update
# Rebuild images from source (development)
./opentr.sh build
Advanced Configuration
Custom Ports
Set the host ports in .env; the compose files already read them:
FRONTEND_PORT=5173
BACKEND_PORT=5174
FLOWER_PORT=5175
POSTGRES_PORT=5176
REDIS_PORT=5177
MINIO_PORT=5178
MINIO_CONSOLE_PORT=5179
OPENSEARCH_PORT=5180
OPENSEARCH_ADMIN_PORT=5181
DOCS_PORT=5183
Everything except the frontend, backend and docs ports is published on 127.0.0.1 only. BACKEND_BIND_HOST (default 0.0.0.0) controls which interface the API port binds to.
Resource Limits
services:
celery-worker:
deploy:
resources:
limits:
cpus: '4'
memory: 16G
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
Persistent Data
Data is persisted in Docker volumes (postgres_data, minio_data, redis_data, opensearch_data, flower_data and others, prefixed with the compose project name, normally opentranscribe_):
# List volumes
docker volume ls | grep opentranscribe
# Back up the database (a logical dump, not a volume copy)
./opentranscribe.sh backup
./opentranscribe.sh backup --encrypt # GPG AES-256, no plaintext on disk
# Restore it (replaces the current database)
./opentranscribe.sh restore ./backups/<backup-file>
Copying a live PostgreSQL volume with tar can capture an inconsistent state, so use backup and restore for the database. Media lives in the minio_data volume and the search index in opensearch_data.
Troubleshooting
Services Won't Start
# Check Docker is running
systemctl status docker
# Check Docker Compose version
docker compose version
# Check for port conflicts
ss -tulpn | grep -E '5173|5174|5175|5176|5177|5178|5179|5180'
# Check logs
./opentranscribe.sh logs
Out of Memory
# Check Docker resources
docker stats
# Reduce model size in .env
WHISPER_MODEL=medium # or base
BATCH_SIZE=8 # or lower
# Increase Docker memory limit (Docker Desktop)
# Docker Desktop → Settings → Resources → Memory
GPU Not Working
# Check NVIDIA driver
nvidia-smi
# Check NVIDIA Container Toolkit
docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi
# Check GPU is visible to the worker container
./opentranscribe.sh shell celery-worker
nvidia-smi
Permission Errors
# Fix model cache permissions
./scripts/fix-model-permissions.sh
# Or manually
sudo chown -R 1000:999 ./models
HTTPS/SSL Setup
HTTPS is required for browser microphone recording when accessing from devices other than localhost (browser security requirement).
Quick Setup
# Run the SSL setup command
./opentranscribe.sh setup-ssl
This interactive command will:
- Prompt for your hostname (e.g.,
opentranscribe.local) - Generate self-signed SSL certificates
- Configure NGINX reverse proxy
- Update your
.envfile
DNS Configuration
After SSL setup, configure DNS:
Router DNS: Add a DNS entry pointing your hostname to your server's IP.
Local hosts file: Add to /etc/hosts (Linux/Mac) or C:\Windows\System32\drivers\etc\hosts (Windows):
192.168.1.100 opentranscribe.local
Trust the Certificate
Import nginx/ssl/server.crt on each client device:
- Windows: Double-click → Install Certificate → Trusted Root CAs
- macOS: Double-click → Keychain → Always Trust
- Linux Chrome:
chrome://settings/certificates→ Import - iOS: Install profile → Settings → Certificate Trust Settings
- Android: Settings → Security → Install certificate
Restart with HTTPS
./opentranscribe.sh restart
Access at https://your-hostname. All services are available through the reverse proxy:
- Frontend:
https://your-hostname - API:
https://your-hostname/api - Flower:
https://your-hostname/flower/ - MinIO Console:
https://your-hostname/minio/
See NGINX Setup Guide for advanced configuration including Let's Encrypt certificates.
Updating OpenTranscribe
Check for Updates
./opentranscribe.sh version
Shows current version and checks GitHub for newer releases.
Update Containers Only
./opentranscribe.sh update
Pulls latest Docker images and restarts services. Fast update when only containers changed.
Run ./opentranscribe.sh backup first. To move to a specific release, or return to the previous one, use ./opentranscribe.sh update --version vX.Y.Z or ./opentranscribe.sh update --rollback. The database migration chain is one-way: rolling the images back does not revert the database, so restore a pre-upgrade backup if the older release cannot read the newer schema.
Full Update (Recommended)
./opentranscribe.sh update-full
Updates everything:
- Docker container images
- Docker Compose configuration files
- NGINX configuration
- Management and helper scripts
Preserved during updates:
.envconfiguration- SSL certificates
- Database and transcriptions
- Model cache
Next Steps
- Hardware Requirements - Optimize for your hardware
- GPU Setup - Enable GPU acceleration
- Configuration - Customize settings
- Troubleshooting - Resolve common issues
Getting Help
- FAQ - Common questions
- GitHub Issues - Report bugs
- GitHub Discussions - Ask questions