mangablitz

Self-hosted manga + books library with the *arr automation stack, running in Docker. Phase 1 targets a MacBook Pro; the same compose file is multi-arch and lifts onto a Raspberry Pi 5 (arm64) for Phase 2.

Architecture

            ┌─────────────┐   indexers    ┌──────────────┐
            │  Prowlarr   │──────────────▶│ FlareSolverr │
            │  (MAM etc.) │               └──────────────┘
            └──────┬──────┘
                   │ Torznab
                   ▼
            ┌───────────────┐     GetComics/DDL      ┌─────────────┐
            │ LazyLibrarian │                        │  Kapowarr   │
            │    (books)    │                        │  (comics)   │
            └───────┬───────┘                        └──────┬──────┘
                    │                                       │
        ┌───────────┴───────────┐              ┌────────────┴────────────┐
        ▼                       ▼              ▼                         ▼
 ┌─────────────┐         ┌───────────┐  ┌─────────────┐          ┌───────────┐
 │ qBittorrent │         │  Suwayomi │  │ qBittorrent │          │FlareSolverr│
 │(MAM books)  │         │  (manga)  │  │(GC torrents)│          │ (Kapowarr) │
 └──────┬──────┘         └─────┬─────┘  └──────┬──────┘          └───────────┘
        └──────────┬───────────┴───────────────┘
                   ▼
         /data/media/{manga,books,comics}  →  Kavita (scan libraries)

Everything shares a single ./data root so imports are instant hardlinks (same filesystem) instead of slow copies.

Service URLs

Service	URL	Role
Kavita	http://localhost:5000	Reader / front-end (iPad, web)
Prowlarr	http://localhost:9696	Indexer/tracker manager (the brain)
qBittorrent	http://localhost:8080	Download client (torrents)
Kapowarr	http://localhost:5656	Western comics (GetComics; not Prowlarr)
LazyLibrarian	http://localhost:5299	Books manager (Readarr replacement)
FlareSolverr	http://localhost:8191	Cloudflare solver (API, no UI)

Run make urls to print these any time.

Quick Start (Phase 1 — MacBook Pro)

Prerequisites

• Docker Desktop (Compose v2)
• Python 3 + pip for the optional official mloader path (brew install python)

1. Configure + start

cp .env.example .env        # adjust PUID/PGID/TZ if needed (defaults are fine on Mac)
make up                     # creates config/ + data/ trees, then docker compose up -d
make ps

Port 5000 busy? macOS Control Center / AirPlay Receiver often binds 5000.

• Preferred: System Settings → General → AirDrop & Handoff → turn off AirPlay Receiver.
• Or set KAVITA_PORT=5500 in .env (the container still listens on 5000; only the host port changes) and read Kavita at http://localhost:5500.
• make verify auto-falls back to 5500 when 5000 is held.

2. First-run wiring (one time)

Do these in order — each app needs the previous one configured.

1. qBittorrent (:8080): grab the temporary admin password from the logs (make logs S=qbittorrent), log in, set a permanent password, and set the default save path to /data/torrents.
2. FlareSolverr (:8191): no UI — just confirm it returns JSON in a browser.
3. Prowlarr (:9696):
   • Add your indexers (Settings → Indexers) — e.g. MyAnonamouse via make bootstrap-mam.
   • Add FlareSolverr (Settings → Indexers → add a FlareSolverr proxy, tag it).
   • Add qBittorrent as a download client (Settings → Download Clients, host qbittorrent, port 8080).
   • LazyLibrarian only — Prowlarr does not sync indexers to Kapowarr.
4. Kapowarr (:5656): root /data/media/comics, download /data/torrents/comics, FlareSolverr http://flaresolverr:8191, qBittorrent client — see docs/KAPOWARR.md or make bootstrap-kapowarr.
5. LazyLibrarian (:5299): eBook destination /data/media/books, download dir /data/torrents/books, qBittorrent + Torznab to Prowlarr MAM (make wire-mam if Torznab points at the wrong indexer).
6. Kavita (:5000): libraries at /manga, /books, /comics. After downloads, scan libraries — Kavita does not auto-import (make scan-kavita KAVITA_PASS=...).

Containers reach each other by name on the compose network — use qbittorrent, flaresolverr, kapowarr, etc. as hostnames (not localhost) when wiring apps.

3. Official source (optional): Manga Plus via mloader

make download URL=https://mangaplus.shueisha.co.jp/titles/100017 LAST=1
# CBZ lands directly in data/media/manga → scan the Kavita manga library

4. Add books manually (optional)

Drop EPUB/PDF into data/media/books/ and rescan the Kavita books library.

Make targets

make up        Start the full stack (creates dirs + .env first)
make down      Stop and remove containers
make ps        Container status
make logs [S=name]   Tail logs (all, or one service)
make urls      Print every service web UI
make download URL=<mplus-url> [LAST=1]   Official Manga Plus download
make scan      Prove media mounts inside the containers
make clean     Remove app configs (keeps data/media) for a fresh wiring
make verify    Full end-to-end Phase-1 verification

Folder Layout

.
├── docker-compose.yml      # 6 services (multi-arch: Mac now, Pi later)
├── .env.example            # PUID / PGID / TZ — copy to .env
├── Makefile
├── scripts/
│   ├── download-chapter.sh # mloader → data/media/manga
│   ├── scan-library.sh     # prove mounts
│   ├── wait-for-http.sh    # generic UI readiness poll
│   ├── wait-for-kavita.sh  # Kavita-specific poll
│   ├── free-port-5000.sh   # free macOS AirPlay port
│   └── verify-phase1.sh    # full-stack verifier
├── config/                 # per-app config + DBs (gitignored)
│   ├── prowlarr/ qbittorrent/ kapowarr/ lazylibrarian/ flaresolverr/
├── data/                   # single shared root (gitignored)
│   ├── torrents/{comics,books}/   # qBittorrent save dir
│   └── media/{manga,books}/       # imported library → Kavita /manga, /books
└── kavita-config/          # Kavita app config & DB

Verification

make verify
# or manually:
docker compose config
docker compose up -d
docker compose ps
for p in 5000 9696 8080 5656 5299 8191; do curl -sI localhost:$p | head -1; done
# prove the shared /data mount is identical across containers:
docker compose exec qbittorrent sh -c 'echo hi > /data/torrents/comics/_probe'
docker compose exec kapowarr   sh -c 'cat /data/torrents/comics/_probe'   # -> hi
docker compose down

Notes

• Images: linuxserver.io (Prowlarr/qBittorrent/LazyLibrarian), mrcas/kapowarr, ghcr.io/flaresolverr/flaresolverr, ghcr.io/kareadita/kavita — all arm64-ready.
• Readarr is retired; LazyLibrarian is the active book-automation replacement.
• Use indexers only for content you're entitled to.

Optional / Phase-2 capabilities

These are opt-in and don't affect the base make up / make verify:

Command	What it does
make vpn-up	Run qBittorrent behind a gluetun VPN killswitch (set VPN_* in .env; then point download clients at host gluetun). See docker-compose.vpn.yml.
make remote-up	Join Tailscale + serve Kavita over HTTPS (set TS_AUTHKEY).
make maintenance-up	Run Diun → notify when container images have updates.
make backup	Tarball config/ (the brains) to ./backups, excluding media.
make bootstrap-prowlarr	Inventory Prowlarr + ensure the qBittorrent client exists.
make bootstrap-mam	Add MyAnonamouse to Prowlarr (make bootstrap-mam MAM_ID=...).
make wire-mam	Point LazyLibrarian Torznab at Prowlarr MAM indexer.
make bootstrap-kapowarr	Apply Kapowarr defaults (FlareSolverr, concurrent DDL).
make scan	Compare on-disk media vs Kavita index + mount check.
make scan-kavita	Trigger Kavita scan-all (make scan-kavita KAVITA_PASS=...).

Phase 2 — Raspberry Pi + 1TB SSD

The stack is lift-and-shift portable (container-internal paths + hostnames), so the whole config/ moves to the Pi with near-zero re-wiring, and all images are arm64-ready. Full step-by-step — copy, Tailscale HTTPS, and the best iOS reading apps — is in MIGRATION.md.

Fresh Pi from SD (2026 Pi 5 bootstrap): docs/PI-BOOTSTRAP.md — power, SSD guard, MAM, Suwayomi/Manga Plus, Tailscale, and scripts/bootstrap-pi.sh. Suwayomi extension picks: docs/SUWAYOMI-EXTENSIONS.md. Kapowarr (Western comics): docs/KAPOWARR.md. Day-to-day ops: AGENTS.md.