Docker Deployment

Docker Deployment

Deploy Subtide backend using Docker.

---

Quick Start

cd backend
docker-compose up subtide-tier2

The backend will be available at http://localhost:5001.

---

Docker Compose Services

Tier 1: Standard

YouTube captions only, no transcription:

docker-compose up subtide-tier1

Use when:

• Videos have existing captions
• You want minimal resource usage
• Browser provides the API key

Tier 2: Enhanced

Full Whisper transcription support:

docker-compose up subtide-tier2

Use when:

• You need transcription for any video
• Browser provides the API key
• Most common choice

Tier 3: Managed

Server-side API key:

SERVER_API_KEY=sk-xxx \
SERVER_API_URL=https://api.openai.com/v1 \
SERVER_MODEL=gpt-4o \
docker-compose up subtide-tier3

Use when:

• Deploying for a team
• Centralizing API key management
• Hiding API key from clients

Tier 4: Streaming

Real-time progressive translation:

SERVER_API_KEY=sk-xxx \
SERVER_API_URL=https://api.openai.com/v1 \
SERVER_MODEL=gpt-4o \
docker-compose up subtide-tier4

Use when:

• You want subtitles as they’re generated
• Lowest perceived latency
• Server handles everything

---

Building Images

Build Locally

cd backend
docker build -t subtide-backend .

Using Pre-built Images

# Standard backend
docker pull ghcr.io/rennerdo30/subtide-backend:latest

# RunPod variant
docker pull ghcr.io/rennerdo30/subtide-runpod:latest

---

Environment Variables

Pass environment variables to configure the container:

docker run -d \
  -p 5001:5001 \
  -e WHISPER_MODEL=large-v3-turbo \
  -e WHISPER_BACKEND=faster \
  -e CORS_ORIGINS="*" \
  ghcr.io/rennerdo30/subtide-backend:latest

Available Variables

Variable	Description	Default
PORT	Internal port	5001
GUNICORN_WORKERS	Worker processes	2
GUNICORN_TIMEOUT	Request timeout (s)	300
CORS_ORIGINS	CORS allowed origins	*
WHISPER_MODEL	Whisper model size	base
WHISPER_BACKEND	mlx, faster, openai	Auto
SERVER_API_KEY	API key (Tier 3/4)	—
SERVER_API_URL	LLM endpoint (Tier 3/4)	—
SERVER_MODEL	LLM model (Tier 3/4)	—

---

Volume Mounts

Model Cache

Persist downloaded Whisper models:

docker run -d \
  -p 5001:5001 \
  -v ~/.cache/whisper:/root/.cache/whisper \
  ghcr.io/rennerdo30/subtide-backend:latest

Custom Configuration

Mount a custom .env file:

docker run -d \
  -p 5001:5001 \
  -v /path/to/.env:/app/.env \
  ghcr.io/rennerdo30/subtide-backend:latest

---

GPU Support

NVIDIA GPU

Use the NVIDIA Container Toolkit:

docker run -d \
  --gpus all \
  -p 5001:5001 \
  -e WHISPER_BACKEND=faster \
  ghcr.io/rennerdo30/subtide-backend:latest

Requires:

• NVIDIA GPU with CUDA support
• NVIDIA Container Toolkit installed

---

Docker Compose Reference

Full docker-compose.yml Example

version: '3.8'

services:
  subtide:
    image: ghcr.io/rennerdo30/subtide-backend:latest
    ports:
      - "5001:5001"
    environment:
      - WHISPER_MODEL=large-v3-turbo
      - WHISPER_BACKEND=faster
      - CORS_ORIGINS=*
      - GUNICORN_WORKERS=4
      - GUNICORN_TIMEOUT=600
    volumes:
      - whisper-cache:/root/.cache/whisper
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

volumes:
  whisper-cache:

---

Health Checks

Docker health check is built-in:

docker ps
# Check HEALTH column

docker inspect --format='{{.State.Health.Status}}' <container>

Manual check:

curl http://localhost:5001/health

---

Troubleshooting

Container exits immediately

Check logs:

docker logs <container_id>

Common causes:

• Port already in use
• Missing environment variables
• Insufficient memory

Out of memory

Increase Docker memory limit or use a smaller model:

-e WHISPER_MODEL=base

Permission denied

On Linux, add your user to the docker group:

sudo usermod -aG docker $USER

---

Production Considerations

1. Use specific tags instead of latest
2. Set resource limits for memory and CPU
3. Configure logging with log drivers
4. Use secrets for API keys instead of environment variables
5. Set up health checks for orchestration

---

Next Steps

• RunPod Deployment - Cloud GPU deployment
• API Reference - API documentation