Docker Installation¶

The recommended way to run cast2md in production.

Prerequisites¶

Docker
Docker Compose (included with Docker Desktop)

Setup¶

1. Clone the Repository¶

git clone https://github.com/meltforce/cast2md.git
cd cast2md

2. Configure Environment¶

cp .env.example .env

Edit .env and set at minimum:

POSTGRES_PASSWORD=your_secure_password

Optional settings:

PORT=8000
DATA_PATH=./data
WHISPER_MODEL=large-v3-turbo
WHISPER_DEVICE=cpu

See Environment Variables for the full reference.

3. Start the Stack¶

docker compose up -d

This starts two containers:

cast2md -- the application on port 8000
postgres -- PostgreSQL with pgvector extension

4. Access the Web UI¶

Open http://localhost:8000 in your browser.

Docker Compose Configuration¶

The compose.example.yml provides a reference configuration. Key settings:

services:
  cast2md:
    image: meltforce/cast2md:latest
    ports:
      - "${PORT:-8000}:8000"
    volumes:
      - ${DATA_PATH:-./data}:/data
    environment:
      - DATABASE_URL=postgresql://cast2md:${POSTGRES_PASSWORD}@postgres:5432/cast2md
    depends_on:
      - postgres

  postgres:
    image: pgvector/pgvector:pg16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=cast2md
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=cast2md

Management¶

View Logs¶

docker compose logs -f cast2md

Restart¶

docker compose restart cast2md

Stop¶

docker compose down

Update¶

docker compose pull
docker compose up -d

Backup¶

# Database backup
docker compose exec cast2md cast2md backup -o /data/backup.sql

# Or via pg_dump
docker compose exec postgres pg_dump -U cast2md cast2md > backup.sql

Restore¶

docker compose exec cast2md cast2md restore /data/backup.sql --force

Data Persistence¶

Path	Content	Persisted Via
`/data`	Audio files, transcripts, temp files	Docker volume mount
PostgreSQL data	Database	Named volume `pgdata`

Warning

Don't delete the pgdata volume unless you have a backup. It contains all your podcast data.

Optional: Tailscale Sidecar¶

To expose cast2md via Tailscale:

services:
  tailscale:
    image: tailscale/tailscale
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_HOSTNAME=${TAILSCALE_HOSTNAME:-cast2md}
      - TS_STATE_DIR=/var/lib/tailscale
    volumes:
      - tsstate:/var/lib/tailscale
    cap_add:
      - NET_ADMIN
      - SYS_MODULE

Set in .env:

TS_AUTHKEY=tskey-auth-xxx
TAILSCALE_HOSTNAME=cast2md