Skip to content

komga

Self-hosted Komga comic / graphic-novel server, running as its own Docker stack on the arrstack VM. Stores a CBZ/CBR/PDF library and serves a web reader plus OPDS v1 & v2, so it reads on the iPad (Safari web reader, or Panels / Chunky over OPDS v2) and a broad range of devices. Comics only — ebooks stay on the korrosync KOReader flow.

Standalone app on its own komga network + komga_config named volume, mirroring the korrosync and Mealie stacks. Deliberately not on the shared arr external network — that network is the acquisition pipeline (Sonarr↔qBittorrent↔Prowlarr), which Komga never talks to.

LAN URL: http://192.168.1.252:25600. Public URL: https://comics.rampancy.cloud via Caddy on the edge LXC, TLS terminated at the edge with the Let's Encrypt wildcard cert.

Service details

Property Value
Host arrstack VM (192.168.1.252) — see arrstack service page
Image gotson/komga:latest (upstream, first-party)
Config storage named volume komga_config (/config in-container) — DB + thumbnails
Library /stash/rodneystash/Comics (ZFS stash, NFS-mounted on the VM) → /data read-write (was :ro; flipped 2026-07-09 for in-UI library management)
Compose stacks/komga/docker-compose.yml
Management Dockhand (Git-backed Docker Compose) — controller is local on arrstack
Host port 25600 → container 25600
Reverse proxy Caddy on edge LXC — comics.rampancy.cloud → 192.168.1.252:25600
Backup Captured by pbs-daily (komga_config sits under /var/lib/docker/volumes/komga_config/_data, part of the VM's vzdump snapshot). The library itself is on the stash pool, backed up separately from the VM.

Library mount (read-write since 2026-07-09)

The library is a read-write bind of the stash comics folder. Komga reads the books and writes its database + generated thumbnails to /config (the named volume). It was originally :ro as a safety guard (a pure reader can't touch the library), but that also blocked deleting books/series from disk in the UI — the trigger for the flip. :rw also enables optional ComicInfo write-back and CBR→CBZ auto-convert if wanted. The NFS export is no_root_squash, so root-in-container can unlink the root:root library files.

Trade-off

:rw removes the guard that stopped Komga from ever modifying/deleting the library. Deletes from the Komga UI now remove the real files on the stash. Deleting from disk is the point here, but mis-clicks are now destructive — the library is backed up separately from the VM (it lives on the stash pool), not in the komga_config vzdump snapshot.

No user:/PUID override is set: with a named volume, Docker seeds /config ownership from the image's mountpoint, so the image's default user can write without a chown footgun; the library dir is 0755 root:root and the container runs as root, so it can read and now also write/unlink. (Ref: komga.org docker docs.)

Clearing stale entries

Deleting library files outside Komga (via SMB / shell) does not immediately drop them from the UI — Komga soft-deletes books whose files vanished and keeps them until the library's trash is emptied. To clear ghosts: Scan library → Empty trash (works regardless of mount mode; it's a DB cleanup). With :rw, you can instead delete the book/series directly in the UI, which removes the files and the entry together.

Reading on devices

Device How
iPad (primary) Safari web reader at https://comics.rampancy.cloud, or a native OPDS app (Panels/Chunky) pointed at the OPDS feed with Komga credentials
Any browser Web reader — auto LTR/RTL/webtoon detection, double-page spread handling
Android / desktop OPDS-capable readers (Mihon, Paperback, YACReader, …)

Komga has its own user accounts; the admin account is created in-UI on first login. Because the edge is internet-facing, set a strong admin password before relying on the public route.

Deployment flow

  1. Compose lives in homelab-ansible/stacks/komga/ — not edited on the host.
  2. comics.rampancy.cloud route added to host_vars/edge.yml; caddy role applied to the edge LXC (ansible-playbook playbooks/edge.yml).
  3. Cloudflare DNS: comics CNAME → rampancy.cloud, gray cloud / DNS-only. There is no wildcard A record — each vhost needs its own CNAME (see forgejo-setup CNAME-per-subdomain note). The wildcard cert covers TLS but not resolution.
  4. The stack is registered once in the Dockhand UI (http://192.168.1.252:3000) pointing at stacks/komga/, same as korrosync/mealie/n8n — a new stack dir is not auto-discovered.
  5. Dockhand reads the compose from git and dispatches docker compose up against the local Docker daemon (no Hawser hop — same host).
  6. In the Komga UI: create the admin account, add a library pointing at /data, and it scans the CBZ/CBR/PDF files.

Reverse-proxy & TLS

Reverse proxy lives on the edge LXC (Caddy, Phase 5D). Caddy terminates TLS with the LE wildcard *.rampancy.cloud issued via Cloudflare DNS-01 and proxies to the upstream over plain HTTP. The wildcard cert and the CrowdSec bouncer already cover any new *.rampancy.cloud host — no cert or bouncer change was needed to add comics.

client → CF DNS → UDM forward → Caddy on edge (CrowdSec) → http://192.168.1.252:25600

Validate the edge/bouncer path from cellular, not LAN — hairpin NAT rewrites the source IP on LAN loops and masks bouncer behaviour.

The wider pipeline (Phase 6H)

Komga is the library + reader only — it neither acquires files nor scrapes metadata. Two companions in the same stack cover those:

Concern Handled by Notes
Acquisition Kapowarr Sonarr-for-comics: ComicVine + GetComics DDL, writes CBZs into the folder Komga watches. Routed through its own ProtonVPN gluetun.
Metadata komf Komga has no online scraper (it reads only embedded ComicInfo.xml or the filename), and Kapowarr doesn't write ComicInfo.xml — komf fetches from ComicVine / MangaUpdates / AniList and writes into Komga via its API.

Still out of scope: manga acquisition (Kapowarr is Western/ComicVine-oriented — Suwayomi would be the manga-specific downloader), and torrent-backed GetComics posts.