feat: Kavita library on HDD-backed storage at novel.marcospaulo.dev.br

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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

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