From 3209551cacc59b416346cd3bc1b3d4b5fbc479f5 Mon Sep 17 00:00:00 2001 From: masi Date: Fri, 25 Sep 2026 13:01:07 -0300 Subject: [PATCH] feat: Kavita library on HDD-backed storage at novel.marcospaulo.dev.br Co-Authored-By: Claude Opus 5.5 --- README.md | 42 +++++++++++++ k8s/kavita.yaml | 161 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 203 insertions(+) create mode 100644 README.md create mode 100644 k8s/kavita.yaml diff --git a/README.md b/README.md new file mode 100644 index 0000000..43425b3 --- /dev/null +++ b/README.md @@ -0,0 +1,42 @@ +# 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 ` or by uploading through Filebrowser to `library/novels//` or `library/manga//`. +- 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). diff --git a/k8s/kavita.yaml b/k8s/kavita.yaml new file mode 100644 index 0000000..622d716 --- /dev/null +++ b/k8s/kavita.yaml @@ -0,0 +1,161 @@ +# Kavita: self-hosted library for EPUB novels (LNReader "Kavita" plugin) and +# CBZ manga (Mihon Kavita extension). Storage decision: see README.md. +apiVersion: v1 +kind: Namespace +metadata: + name: kavita +--- +# Kavita database, covers, logs and settings. +apiVersion: v1 +kind: PersistentVolume +metadata: + name: pv-hdd-kavita-config + labels: + app.kubernetes.io/part-of: kavita +spec: + capacity: + storage: 5Gi + accessModes: [ReadWriteOnce] + persistentVolumeReclaimPolicy: Retain + storageClassName: hdd-storage + volumeMode: Filesystem + local: + path: /srv/hdd/kavita-config + nodeAffinity: + required: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/hostname + operator: In + values: [kubernets] +--- +# Book files. Lives inside the Filebrowser tree so uploads go through +# Filebrowser; Kavita mounts it read-only. +apiVersion: v1 +kind: PersistentVolume +metadata: + name: pv-hdd-kavita-library + labels: + app.kubernetes.io/part-of: kavita +spec: + capacity: + storage: 200Gi + accessModes: [ReadOnlyMany] + persistentVolumeReclaimPolicy: Retain + storageClassName: hdd-storage + volumeMode: Filesystem + local: + path: /srv/hdd/filebrowser/data/library + nodeAffinity: + required: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/hostname + operator: In + values: [kubernets] +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: kavita-config + namespace: kavita +spec: + storageClassName: hdd-storage + volumeName: pv-hdd-kavita-config + accessModes: [ReadWriteOnce] + resources: + requests: + storage: 5Gi +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: kavita-library + namespace: kavita +spec: + storageClassName: hdd-storage + volumeName: pv-hdd-kavita-library + accessModes: [ReadOnlyMany] + resources: + requests: + storage: 200Gi +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: kavita + namespace: kavita +spec: + replicas: 1 + strategy: + type: Recreate + selector: + matchLabels: + app: kavita + template: + metadata: + labels: + app: kavita + spec: + securityContext: + runAsUser: 1000 + runAsGroup: 1000 + fsGroup: 1000 + runAsNonRoot: true + containers: + - name: kavita + image: jvmilazz0/kavita:0.9.1 + ports: + - containerPort: 5000 + name: http + securityContext: + allowPrivilegeEscalation: false + capabilities: + drop: [ALL] + resources: + requests: + cpu: 250m + memory: 512Mi + limits: + cpu: "2" + memory: 1536Mi + volumeMounts: + - name: config + mountPath: /kavita/config + - name: library + mountPath: /library + readOnly: true + readinessProbe: + httpGet: + path: / + port: http + initialDelaySeconds: 20 + periodSeconds: 10 + failureThreshold: 6 + livenessProbe: + tcpSocket: + port: http + initialDelaySeconds: 60 + periodSeconds: 30 + volumes: + - name: config + persistentVolumeClaim: + claimName: kavita-config + - name: library + persistentVolumeClaim: + claimName: kavita-library + readOnly: true +--- +apiVersion: v1 +kind: Service +metadata: + name: kavita + namespace: kavita +spec: + type: ClusterIP + selector: + app: kavita + ports: + - name: http + port: 5000 + targetPort: http