# 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).