# ipodderx-rs A headless podcatcher: scans RSS/Atom feeds, downloads enclosures (HTTP and BitTorrent), files them into per-feed folders, and reaps old files to stay under a disk quota. Runs as a one-shot CLI or as a daemon with a web UI, serving any number of people from one copy of the data. ## Lineage A modern Rust rewrite of [ipodderx-core](https://git.sdf1.net/rays/ipodderx-core), the Python 2 engine behind **iPodderX** (2004-2008, Ray Slakinski & August Trometer), open-sourced under the MIT License in 2010. What carries over: the feed scan and TTL handling, GUID/URL dedupe, per-feed and per-date download folders, keyword filters, the explicit-content filter, torrent enclosures, and "SmartSpace" -- the oldest-first disk quota reaper. What does not: iTunes and iPhoto export via AppleScript, text-to-speech enclosures, the Windows WMP/COM paths, XML plists and Python pickles for state, the `directory.iPodderX.com` survey ping, 3DES-encrypted preferences, and the `printMSG` stdout protocol -- replaced by a JSON-lines socket. ## Quick start ```sh cargo build --release install -m755 target/release/ipx ~/.cargo/bin/ ipx add https://atp.fm/rss # subscribe ipx fetch # scan and download ipx daemon # scheduler, control socket and web UI ``` On first start with `[web] enabled = true` the daemon mints a token, writes it to config.toml and prints the URL to open. A database with no accounts starts with **admin / ipodderx** at `/login` -- change it with `echo -n '' | ipx user passwd admin`. ## Documentation | | | |---|---| | [docs/configuration.md](docs/configuration.md) | Every config key, paths, environment variables | | [docs/cli.md](docs/cli.md) | Every command, including `ipx user` | | [docs/users.md](docs/users.md) | Accounts, and what several people share | | [docs/sso.md](docs/sso.md) | Cloudflare Zero Trust or Authentik in front | | [docs/architecture.md](docs/architecture.md) | How it works: modules, schema, socket, HTTP API | | [CHANGELOG.md](CHANGELOG.md) | What landed, and why | | [CLAUDE.md](CLAUDE.md) | Notes for anyone (or anything) working on the code | ## The web UI `ipx daemon` serves it in the same process, so it reads SQLite and the event bus directly. Feeds down the side; the selected feed's items across the top; the selected item's text and its enclosures below, which is where you play, download or delete them. The divider drags and its position is remembered. Playback serves Range requests, so seeking works. An OPML subscription is a collapsible folder whose page lists the feeds inside it. An item may carry several enclosures; all of them appear below, and anything that is not audio or video gets a View link rather than a player -- the publisher's copy until it is downloaded, the local one after. Opening an item marks it read. Show notes are untrusted feed HTML, sanitized with `ammonia` server-side before they reach the page. The **Log** button shows the running daemon live in four tabs: *Daemon I/O* is the control protocol itself, every command in and event out; *Scans* is feed and download activity; *HTTP* is web requests; *All* is everything, with level and text filters and a copy button. It reads a ring buffer held in the process, not a file, so it works the same under Docker. It is plain HTTP. On a LAN bind the token and everything else cross the network in the clear, and a feed URL can itself carry a credential. Put TLS in front of it if that matters. ## OPML **Importing and exporting** a file copies subscriptions in or out once: `ipx import subs.opml`, `ipx export subs.opml`, or Settings → Subscriptions in the UI. **Subscribing to an OPML URL** is a live subscription, as iPodderX had. Add the OPML's URL like any other feed; every scan re-reads it and keeps your list in step. The feeds inside are not written to config.toml -- the OPML is the source of truth, so they are re-derived each scan and held in the database. They show as a folder, download into one nested folder, and inherit the subscription's settings until you change one, which gives it its own entry. When a feed drops out of the OPML upstream, it is unsubscribed and removed -- unless it has downloads, in which case it is kept and flagged in the UI as no longer listed. A downloaded file is never left behind with nothing explaining where it came from. ## Docker ```sh docker compose up -d # builds the image and starts it docker compose logs -f ipx # the token is printed on first start ``` `docker-compose.yml` mounts `./config`, `./data` and a downloads directory, publishes 8099 for the UI and 6881 (TCP **and** UDP -- DHT needs the UDP side), and sets `PUID`/`PGID` to `99:100` so files land owned the way Unraid shares expect. The healthcheck runs `ipx status` through the control socket, so it catches a daemon that is alive but wedged rather than merely one that has died. ## Running it as a service `contrib/` has a systemd user unit for the daemon, and a timer plus one-shot service if you would rather run periodic scans with no daemon -- in which case there is no socket for a UI to attach to. ## Tests ```sh cargo test # the engine: parsing, filters, retention, schedules, SQL, per-user state node tests/page-smoke.js # the page script loads without throwing npx playwright test # a real browser against a real daemon ``` `npm install` gets the test runner; the browser comes from `npx playwright install --with-deps chromium` (in `install.sh`). ## License MIT. See [LICENSE](LICENSE).