Docker

This guide covers how to run the transcription process on your local machine using Docker Compose.

Table of Contents

1. Prerequisites
2. Initial Setup
3. Running Transcription
4. Configuration Options
5. Managing Containers
6. Viewing Logs and Progress
7. Troubleshooting

---

Prerequisites

Required Software

• Docker (version 20.10+)
• Docker Compose (version 2.0+ or Docker Desktop)
• NVIDIA Container Toolkit (for GPU support)

Install Docker

Ubuntu/Debian:

# Install Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker --version

macOS/Windows: Download and install Docker Desktop.

Install NVIDIA Container Toolkit (GPU Support)

For NVIDIA GPU support on Linux:

# Add NVIDIA repository
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
    sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# Install
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Restart Docker
sudo systemctl restart docker

# Verify GPU access
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

Google OAuth Credentials

Ensure you have valid credentials:

# Verify credentials exist
ls -la credentials.json token.json

# Refresh token if needed
arandu info

---

Initial Setup

1. Clone/Navigate to Project

cd /path/to/arandu

2. Create Environment File

cp .env.example .env

3. Configure Settings

Edit .env to customize your setup:

# Whisper model (adjust based on your GPU VRAM)
ARANDU_MODEL_ID=openai/whisper-large-v3

# Number of workers (adjust based on GPU VRAM)
# 24GB VRAM: 4 workers
# 16GB VRAM: 2-3 workers
# 8GB VRAM: 1-2 workers
WORKERS=4

# Enable quantization (reduces VRAM usage by ~50%)
ARANDU_QUANTIZE=true

# Input catalog file
CATALOG_FILE=catalog.csv

4. Verify Input Catalog

ls -la input/catalog.csv

5. Build Docker Image

docker compose --profile gpu build arandu

---

Running Transcription

GPU Mode (Recommended)

Run with NVIDIA GPU acceleration:

docker compose --profile gpu up arandu

CPU Mode

Run on CPU only (slower but works without GPU):

docker compose --profile cpu up arandu-cpu

Run in Background (Detached)

# GPU mode
docker compose --profile gpu up -d arandu

# CPU mode
docker compose --profile cpu up -d arandu-cpu

Run with Custom Settings

Override settings without editing .env:

# Use more workers
WORKERS=6 docker compose --profile gpu up arandu

# Use a different model
ARANDU_MODEL_ID=openai/whisper-large-v3 docker compose --profile gpu up arandu

# Use a different catalog
CATALOG_FILE=my_subset.csv docker compose --profile gpu up arandu

# Combine multiple overrides
WORKERS=2 ARANDU_MODEL_ID=distil-whisper/distil-large-v3 docker compose --profile gpu up arandu

---

Configuration Options

Environment Variables

Variable	Default	Description
ARANDU_MODEL_ID	openai/whisper-large-v3	Whisper model from Hugging Face
WORKERS	4	Number of parallel transcription workers
ARANDU_QUANTIZE	true	Enable 8-bit quantization (reduces VRAM)
ARANDU_FORCE_CPU	false	Force CPU execution
CATALOG_FILE	catalog.csv	Input catalog filename
INPUT_DIR	./input	Directory containing catalog
RESULTS_DIR	./results	Output directory for results
CREDENTIALS_DIR	./	Directory containing credentials
HF_CACHE_DIR	./cache/huggingface	Hugging Face model cache

Model Selection Guide

Model	VRAM Required	Speed	Accuracy	Best For
openai/whisper-large-v3	~10GB	Slow	Highest	Final production runs
openai/whisper-large-v3	~6GB	Medium	High	Good balance
distil-whisper/distil-large-v3	~3GB	Fast	Good	Quick processing, limited VRAM

Worker Configuration Guide

GPU VRAM	Recommended Workers	With Quantization
24GB (RTX 4090)	3-4	5-6
16GB (RTX 4080)	2-3	3-4
12GB (RTX 4070)	1-2	2-3
8GB (RTX 3070)	1	1-2

---

Managing Containers

View Running Containers

docker compose ps

Stop Transcription

# Graceful stop (allows current file to complete)
docker compose stop

# Force stop
docker compose kill

Remove Containers

docker compose down

Rebuild After Code Changes

docker compose build --no-cache

Clean Up Docker Resources

# Remove stopped containers and unused images
docker system prune

# Remove everything including volumes (careful!)
docker system prune -a --volumes

---

Viewing Logs and Progress

View Live Logs

# Follow logs in real-time
docker compose logs -f arandu

# View last 100 lines
docker compose logs --tail 100 arandu

Check Progress

# Count completed transcriptions
ls -1 results/*_transcription.json 2>/dev/null | wc -l

# View checkpoint status
cat results/checkpoint.json | python -m json.tool

Detailed Progress Script

python -c "
import json
from pathlib import Path

checkpoint = Path('results/checkpoint.json')
if checkpoint.exists():
    with open(checkpoint) as f:
        cp = json.load(f)
    completed = len(cp.get('completed_files', []))
    failed = len(cp.get('failed_files', {}))
    total = cp.get('total_files', 'unknown')
    print(f'Progress: {completed}/{total} completed')
    print(f'Failed: {failed}')
    if cp.get('failed_files'):
        print('Failed files:')
        for fid, err in cp['failed_files'].items():
            print(f'  - {fid}: {err[:50]}...')
else:
    print('No checkpoint found - transcription not started')
"

---

Troubleshooting

Docker Build Fails

Python package installation errors:

# Clean build cache and retry
docker compose build --no-cache

Disk space issues:

# Check available space
df -h

# Clean Docker resources
docker system prune -a

GPU Not Detected

Verify NVIDIA runtime:

# Check if GPU is accessible
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

Check Docker Compose GPU config:

# Verify GPU reservation in docker-compose.yml
docker compose config | grep -A 10 "deploy:"

Fall back to CPU mode:

docker compose --profile cpu up arandu-cpu

Out of Memory (OOM) Errors

Reduce workers:

WORKERS=1 docker compose --profile gpu up arandu

Enable quantization:

ARANDU_QUANTIZE=true docker compose --profile gpu up arandu

Use smaller model:

ARANDU_MODEL_ID=distil-whisper/distil-large-v3 docker compose --profile gpu up arandu

OAuth Token Expired

Error message: RefreshError or authentication failure

Solution:

# Stop the container
docker compose stop

# Refresh token locally (outside Docker)
arandu info

# Restart transcription
docker compose --profile gpu up arandu

Shared Memory Issues

Error: RuntimeError: unable to open shared memory object

Solution: Increase shared memory size in docker-compose.yml:

shm_size: '32gb'  # Increase from default 16gb

Network/Download Timeout

Pre-download models:

# Download model before running transcription
docker compose --profile gpu run --rm arandu python -c "
from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor
model_id = 'openai/whisper-large-v3'
AutoProcessor.from_pretrained(model_id)
AutoModelForSpeechSeq2Seq.from_pretrained(model_id)
print('Model downloaded successfully')
"

Resume After Interruption

The checkpoint system automatically handles resume. Simply restart:

docker compose --profile gpu up arandu

To start fresh:

rm results/checkpoint.json
docker compose --profile gpu up arandu

---

Quick Reference

Common Commands

# Build image
docker compose --profile gpu build arandu

# Run with GPU
docker compose --profile gpu up arandu

# Run with CPU
docker compose --profile cpu up arandu-cpu

# Run in background
docker compose --profile gpu up -d arandu

# View logs
docker compose logs -f arandu

# Stop
docker compose stop

# Clean up
docker compose down

Example: Full Local Workflow

# 1. Setup
cp .env.example .env
# Edit .env as needed

# 2. Build
docker compose --profile gpu build arandu

# 3. Run transcription
docker compose --profile gpu up arandu

# 4. Check results
ls results/*_transcription.json | wc -l

# 5. Clean up
docker compose down

Example: Quick Test Run

Test with a small subset of files:

# Create a test catalog with 5 files
head -6 input/catalog.csv > input/test_catalog.csv

# Run test
CATALOG_FILE=test_catalog.csv WORKERS=1 docker compose --profile gpu up arandu

# Check results
ls results/