Installation

Docker + Docker Compose · runs on any Linux, macOS, or Windows host

Requirements

Docker Engine 20.10 or later
Docker Compose v2 (the docker compose plugin, not the legacy docker-compose)

Quick start

The fastest path to a running instance:

bash

# Download the compose file
curl -O https://raw.githubusercontent.com/CastCharm/castcharm/main/docker-compose.yml

# Start in the background
docker compose up -d

Then open http://localhost:8000 in your browser. A setup wizard will run on the first visit.

Default paths: the database is saved to ./data/ and downloaded audio files go into ./downloads/, both relative to the directory containing your docker-compose.yml.

Full docker-compose.yml

Below is the complete file for reference. You can customise paths and the port via environment variables or a .env file placed in the same directory.

docker-compose.yml

services:
  castcharm:
    image: ghcr.io/castcharm/castcharm:latest
    container_name: castcharm
    ports:
      - "${PORT:-8000}:8000"
    volumes:
      # database and app state
      - ${DATA_PATH:-./data}:/data
      # downloaded audio files
      - ${DOWNLOAD_PATH:-./downloads}:/downloads
    environment:
      - DATABASE_URL=sqlite:////data/castcharm.db
      - DEFAULT_DOWNLOAD_PATH=/downloads
      - CLEAN_RSS_PATH=/downloads/clean-rss
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s

Environment variables

Set these in a .env file in the same folder as your docker-compose.yml, or pass them directly to the container.

Variable	Default	Description
PORT	8000	Host port the app is exposed on.
DATA_PATH	./data	Host path for the SQLite database and application state. Back this up to preserve all feeds, settings, and playback history.
DOWNLOAD_PATH	./downloads	Host path where audio files are saved. Point this at an existing media directory if you want CastCharm to manage files you already have.

The DATABASE_URL, DEFAULT_DOWNLOAD_PATH, and CLEAN_RSS_PATH variables inside the container are set automatically by the compose file and do not normally need to be changed.

Running behind a reverse proxy

The container is configured to trust X-Forwarded-* headers, so it works out of the box behind nginx, Caddy, Traefik, or any other reverse proxy.

Caddy example

Caddyfile

podcasts.example.com {
    reverse_proxy localhost:8000
}

nginx example

nginx.conf

server {
    listen 443 ssl;
    server_name podcasts.example.com;

    location / {
        proxy_pass         http://localhost:8000;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Data & backups

Database — DATA_PATH/castcharm.db. This single file contains all feeds, episode records, settings, and playback history. Copy it to back everything up.
Audio files — stored in DOWNLOAD_PATH/, organised as Podcast Name/YYYY/filename.mp3 by default.

To restore: stop the container, replace the files, start again.

Build from source

If you prefer to build the image locally rather than pulling from the registry:

bash

git clone https://github.com/CastCharm/castcharm
cd castcharm
docker compose up -d --build

Updating

bash

# Pull the latest image and restart
docker compose pull
docker compose up -d

Database migrations run automatically on startup. No manual steps are required when upgrading.