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:

# 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.

First run

The wizard walks you through six short steps. You can change any of these later in Settings.

1. Login — pick a username and password, or skip this step to leave your instance open.
2. Theme — pick a colour scheme.
3. Timezone — used for date-prefixed filenames and year-based folders.
4. Downloads folder — where inside the container to save audio files. This maps to DOWNLOAD_PATH on the host.
5. File options — filename format and folder organisation.
6. External API — leave on if you plan to use the Android app or scripts; leave off if you'll only ever use the web interface.

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.

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.

Most people only need these three:

Advanced options

You can safely skip this section unless you're running CastCharm behind a reverse proxy in another container, or building your own image.

The login cookie's Secure flag is set automatically based on whether the current request came in over HTTPS, so no configuration is needed for either plain-HTTP or HTTPS deployments.

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

CastCharm works behind nginx, Caddy, Traefik, or any other reverse proxy. If your proxy runs on the same host as CastCharm (the usual setup), no configuration is needed — just point it at the container and go.

If your proxy runs in a separate container and you want the login rate-limit to see the real client IP instead of the proxy's, set CASTCHARM_TRUSTED_PROXIES to the proxy's container IP. See the Advanced options above.

Caddy example

podcasts.example.com {
    reverse_proxy localhost:8000
}

nginx example

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;
    }
}

External API access

Everything the web interface can do is also available as a REST API. This is what the Android app uses to talk to your server, and it's how scripts and home-automation tools can reach your library.

To let an outside app or script in:

1. Open Settings → External API in the web interface.
2. Make sure Enable external API access is on.
3. Click Generate new key and give it a name (e.g. "Phone" or "Backup script").
4. Copy the key that appears — it's only shown once.

The Android app handles all of this for you: log in once with your username and password, and the app generates and stores its own key automatically.

Managing keys

The keys list in Settings shows when each key was last used. You can:

• Rename a key so you can tell two identical devices apart.
• Revoke a single key — that device stops working immediately, others are unaffected.
• Revoke unused — a one-click cleanup for keys that have never been used or haven't been used in 30 days (common when an app was uninstalled without logging out).

CastCharm also runs a small daily cleanup that removes keys never used within a week of being created — usually the fingerprint of a failed enrolment.

Interactive API docs

Full API reference with an interactive "try it out" panel is at /api/docs on your instance (e.g. http://localhost:8000/api/docs). Use the Authorize button to paste an API key for testing.

Playlists

There are two kinds, chosen when you create one and fixed from then on. A manual playlist holds the episodes you add to it, in the order you drag them into. A smart playlist (the brain icon) holds whatever matches its rules right now, so it keeps itself current as episodes arrive and get played.

Smart playlist rules, all optional and combined with "and":

• Episodes that are unplayed (the default, including part-played), in progress, played, or any.
• Podcast is any of, or none of, the ones you tick.
• Published in the last N days, or after or before a date.
• Duration between a minimum and a maximum in minutes.
• Title contains some words.
• Order: oldest, newest, shortest or longest first, optionally keeping only the first N.

Only episodes downloaded on the server are ever included. While you edit the rules, the editor shows how many episodes they match and how long that is in total. Playing a smart playlist, from its Play button or any row, works through it in order and carries on to the next episode by itself; the Android app does the same, offline too.

Get Caught Up is a smart playlist that comes with CastCharm: unplayed episodes from the last two weeks, oldest first. It sits at the top of the Home page and first in Android Auto. Change its rules to taste; it cannot be deleted.

Notifications

CastCharm can send you a message when it finds new episodes: one message per sync, listing the podcasts and episodes. There's nothing to install on the server. Under Settings → Notifications, choose how to send it and paste one address.

• ntfy — the simplest option. Pick a topic name and use https://ntfy.sh/your-topic, or the same path on your own ntfy server. Install the ntfy app on your phone and subscribe to that topic. The topic name is the only thing protecting it, so choose something hard to guess, or add an access token in the form.
• Apprise API — for Discord, Telegram, email, Pushover, Matrix and a hundred other services. Run the Apprise API container next to CastCharm, configure your services there, and point CastCharm at http://apprise:8000/notify/your-key. CastCharm itself stays generic and never holds those services' tokens.
• Webhook — for anything else (Home Assistant, n8n, your own script). CastCharm sends a POST with this JSON:

{
  "event": "new_episodes",
  "title": "2 new episodes",
  "message": "Podcast — Episode title\nOther podcast — Another episode",
  "count": 2,
  "link": "https://podcasts.example.com",
  "feeds": [{ "id": 7, "title": "Podcast", "episodes": [{ "id": 912, "title": "Episode title", "published_at": "2026-10-09T06:00:00" }] }],
  "sent_at": "2026-10-09T06:05:12Z"
}

Fill in Public URL with the address you open CastCharm at and the message will link straight to the podcast. Use Send test message after saving to make sure it arrives.

Notifications are only available once login is turned on (Settings → Security). Sending a message means the server makes a request to an address of your choosing; on an open instance anyone on the network could change that address, so the setting is reserved for the signed-in owner, can't be changed with an API key, and the server never follows redirects or shows the reply it gets back.

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:

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

Updating

# 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.