Skip to main content
Glama
README.md
# podcast-feed

Private podcast feeds from links to audio and video files. Add a direct link to a file (or
upload one in the admin UI), and podcast-feed downloads it, makes AAC audio of it (an MP3 file
stays as it is) and publishes it as an episode in an RSS feed that any podcast app can
subscribe to. An admin UI manages the feeds and episodes, and an
[MCP](https://modelcontextprotocol.io) server lets Claude add and remove episodes.

- **Direct links only:** a link to a file, not to a web page or a YouTube video. Every
  connection, redirects included, goes only to public addresses ("blocked address" otherwise),
  with limits on size, duration and free disk space.
- **Or an upload,** in the admin UI only, up to 100 MB (see [Uploading a file](#uploading-a-file)).
- **Several feeds**, created in the admin UI. One of them is the default for new episodes.
- **Retention:** an episode is deleted 30 days after it was added (per-feed override).
- **One process:** SQLite for the index, audio files on disk, ffmpeg for the conversion. A
  restart picks up the episodes it interrupted.

## Listeners and routes

| Port | Path | What |
|---|---|---|
| 8080 | `GET`/`HEAD` `/feeds/<slug>.xml` | A feed (RSS 2.0 with the iTunes tags) |
| 8080 | `GET`/`HEAD` `/media/<slug>/<file>` | An episode's audio or artwork, or the feed's cover, with ranges |
| 8080 | `/ui/` | The admin UI (`/` redirects there) |
| 8000 | `/mcp` | The MCP server (Streamable HTTP, stateless) |

The feed and media routes are the only public ones; everything else on 8080 is under `/ui/`.
Every request other than `GET`, `HEAD` or `OPTIONS` must come from the admin UI's own pages
(`Sec-Fetch-Site: same-origin`, or without that header an `Origin` whose host is the request's
`Host`), or it gets 403.

**MCP tools**, each with a title and all four hints: `list_feeds`, `add_episode` (returns at
once with status `queued`), `list_episodes`, `get_episode` (poll it until `ready` or `failed`)
and `remove_episode`. They never return a feed URL. Feeds are created, edited and deleted in
the admin UI only.

Neither listener has a login of its own. Put both behind something that authenticates every
request: the author runs the admin UI and the MCP server behind Cloudflare Access.

## Uploading a file

On a feed's page, "Upload a file" takes an audio or video file from your computer: the same
kinds a link can point to, converted the same way. The title is optional, as for a link: the
file's own title tag, else its name without the extension.

- **100 MB at most.** The upload is one request, and Cloudflare refuses a request body over
  100 MB on its free plan, so a bigger file could not get through the tunnel to the app anyway.
  The page says so before it sends anything, and the app refuses too, by the declared size and
  by counting what arrives. A bigger file has to be added by link. (`PODCAST_MAX_BYTES` still
  applies to links; the upload limit is separate, and lower.)
- **It needs JavaScript.** The page's script sends the file as the raw body of the request
  (with a progress bar), so that the app writes it to disk as it arrives; a plain form would be
  spooled by the web framework into `/tmp`, which in a read-only container is RAM-backed and
  counts against the memory limit. Without script, the section stays hidden, so there is no
  button that does nothing.
- **Failed uploads are not retried.** The file is deleted when its job ends, so a failed
  upload row has no Retry button, only Remove: upload the file again. The same goes for a
  restart that comes between the upload and the worker's turn: the app empties `media/.tmp/`
  when it starts, and the episode fails with "upload lost".
- **MCP cannot upload,** a remote tool call has no file on your disk to send; use a link.
- Only the admin UI's own pages can upload (the same-origin rule above); the file name and title
  travel in request headers, so the access log shows `POST /ui/feeds/<slug>/upload` and
  nothing about the file.

## Configuration

| Variable | Default | |
|---|---|---|
| `PODCAST_PUBLIC_BASE` | (required) | **A secret.** The public `https://` address of the feeds, including the secret path, e.g. `https://podcast-api.example.com/<secret>`; a trailing `/` is dropped. Feed and media links are built from it. |
| `PODCAST_DATA_DIR` | `/data` | The SQLite database (`podcast.sqlite`) |
| `PODCAST_MEDIA_DIR` | `/media` | Audio and artwork, one folder per feed; `.tmp/` for jobs in progress |
| `PODCAST_RETENTION_DAYS` | `30` | Days an episode is kept (1 to 3650), unless its feed says otherwise |
| `PODCAST_MAX_BYTES` | `1073741824` | Largest download (1 GiB) |
| `PODCAST_MAX_HOURS` | `6` | Longest episode |
| `PODCAST_MIN_FREE_GB` | `5` | Free space the media disk must keep; below it an episode fails with "disk nearly full" |
| `PODCAST_WEB_PORT` | `8080` | Feeds, media and the admin UI |
| `PODCAST_MCP_PORT` | `8000` | The MCP server |
| `PODCAST_HOST` | `0.0.0.0` | The address both listeners bind |

A missing or invalid setting stops the program at once with exit status 2; the message names
the variable and never quotes `PODCAST_PUBLIC_BASE`. podcast-feed never logs it or a feed URL:
the feed URLs appear only in the admin UI. `media/` gets a `CACHEDIR.TAG`, so backups that
skip caches (`restic --exclude-caches`) leave the audio out.

## The gateway and the secret

Podcast apps can't log in to Cloudflare Access, so the feeds and the audio reach them through
the device gateway of [vps-infra](https://github.com/jprintz/vps-infra): a Cloudflare Worker
on `podcast-api.<domain>` checks the podcast secret (the first path segment), strips it,
forwards only `/feeds/` and `/media/` and adds the service token Access expects, so Access
still stands in front of every request. The podcast gateway has its own secret, separate from
the device secret of the e-reader clients. `PODCAST_PUBLIC_BASE` is that gateway's address
plus the secret, which is why it is one. How the gateway works and how to rotate its secret:
[`docs/devices.md`](https://github.com/jprintz/vps-infra/blob/main/docs/devices.md) in
vps-infra.

## Deployment

The image is `ghcr.io/jprintz/podcast-feed:<version>` (linux/amd64). It runs as uid 65532 with
a read-only root: give it writable `/data` and `/media` volumes and a `/tmp` (Podman's
`ReadOnly=true` mounts one; with Docker use `--tmpfs /tmp`). It needs no capabilities.
SIGTERM stops it within seconds; an open download gets 3 s to finish. If a listener or the
worker stops on its own, the process exits with status 1, so that the service manager
restarts it.

```ini
[Container]
ContainerName=podcast
Image=ghcr.io/jprintz/podcast-feed:0.1.0
Secret=podcast_public_base,type=env,target=PODCAST_PUBLIC_BASE
Volume=/srv/apps/podcast/data:/data:U
Volume=/srv/apps/podcast/media:/media:U
UserNS=auto
ReadOnly=true
NoNewPrivileges=true
DropCapability=ALL
```

## Development

```bash
uv sync --all-extras
make test     # unit tests; the conversion tests need ffmpeg and ffprobe on PATH (skipped otherwise)
make lint     # ruff check and format check
make smoke    # builds the image and smoke-tests it with Docker, as CI does
```

`make smoke` runs `scripts/smoke.sh`: the container read-only with no capabilities, the
image's healthcheck, the MCP tools and their annotations (`scripts/smoke_mcp.py`), the admin UI,
a feed round trip, an uploaded file that becomes an episode, the public routes' answers,
ffmpeg, and `docker stop` under 8 s with exit status 0. CI runs the tests with `REQUIRE_FFMPEG=1`
(the static ffmpeg of the image) and the same smoke test, and pushes the image from `main` and
from `v*` tags.

## License

MIT