kavita/README.md

Kavita (novel + manga library)

Self-hosted library for EPUB novels and CBZ manga. It replaced Komga on 2026-09-25 because Kavita has a richer reader and more customization.

• Manifest: k8s/kavita.yaml (namespace kavita, image jvmilazz0/kavita:0.9.1, runs as uid/gid 1000)
• URL: https://novel.marcospaulo.dev.br/ (Tailscale-only; ~/manifests/access-gateway/kavita.env, created with expose kavita/kavita novel)
• Libraries:
  • Novels: type LightNovel, folder /library/novels, EPUB
  • Manga: type Manga, folder /library/manga, archives and images
  • Folder watching is on for both.

Storage decision

Data	PV	Host path	Size	Mode
DB, covers, logs, settings	pv-hdd-kavita-config	/srv/hdd/kavita-config	5Gi	RWO
Book files	pv-hdd-kavita-library	/srv/hdd/filebrowser/data/library	200Gi	ROX, mounted read-only

• Both PVs use class hdd-storage, reclaim Retain, and node affinity kubernets.
• The library lives inside the Filebrowser tree. Add books with novel add <file> or by uploading through Filebrowser to library/novels/<Series>/ or library/manga/<Series>/.
• MinIO was rejected because Kavita needs filesystem semantics.

Accounts (secrets live only in the cluster)

• kavita-admin secret holds the admin login (user admin).
• kavita-reader secret holds the phone login (user reader; roles Login, Download, Bookmark; both libraries).
• Read a password with: kubectl -n kavita get secret kavita-reader -o jsonpath='{.data.password}' | base64 -d
• The API key used by the apps is shown in Kavita under Settings → Account (as reader).

Clients

• LNReader: install Kavita from masi/lnreader-plugins. In the plugin settings, set URL https://novel.marcospaulo.dev.br and the reader's API key.
• Mihon: use the Kavita extension (Keiyoushi) with the same URL, plus the OPDS URL/API key from the reader's account settings.

Backup / restore

• Config: scale to 0 (kubectl -n kavita scale deploy/kavita --replicas=0), then copy /srv/hdd/kavita-config. This covers users, reading progress and collections.
• Library: the files themselves are the source of truth, and Kavita rebuilds its metadata by scanning them.
• Restore: recreate /srv/hdd/kavita-config (owned by 1000:1000), copy the backup back, kubectl apply -f k8s/kavita.yaml, then expose kavita/kavita novel.
• Retain keeps the data if the namespace is deleted. Delete a released PV before applying again.

Notes

• The image keeps its default config in /tmp/config, so don't mount a volume over /tmp.
• Library create needs an explicit metadataProvider (the enum has no zero value).