BookLore Helm Chart
A Helm chart for deploying BookLore on Kubernetes. BookLore is a self-hosted, multi-user digital library with smart shelves, automatic metadata fetching, Kobo and KOReader sync, BookDrop imports, OPDS support, and a built-in reader for EPUB, PDF, and comics.
Features
- Official pinned BookLore image with a configurable runtime listener.
- Bundled HelmForge MariaDB or an operator-managed external database.
- Independent persistence for application data, books, and BookDrop imports.
- Ingress, Gateway API, External Secrets, NetworkPolicy, HPA, PDB, and optional ServiceMonitor resources.
- Fail-fast validation for unsafe multi-replica storage and incomplete external database or routing contracts.
Prerequisites
- Kubernetes 1.26+
- Helm 3.x
Quick start
helm install booklore oci://ghcr.io/helmforgedev/helm/booklore
Parameters
See values.yaml for the full list of configurable parameters.
Architecture
BookLore runs as one Spring Boot Deployment that serves the API and bundled
web interface on app.port. A ClusterIP Service targets the named http
container port. MariaDB is bundled by default and can be replaced with an
external service. Separate storage domains preserve application data, the book
library, and the optional BookDrop import directory.
Configuration reference
Values & Configuration Reference
All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.
Database
By default the chart deploys a MariaDB instance via the HelmForge MariaDB
subchart. To use an external database set mariadb.enabled=false and configure
database.external.*.
Exposure
The chart supports both traditional Ingress and Gateway API for external access. See examples/ for ready-to-use configurations.
Persistence
| Volume | Mount | Default | Description |
|---|---|---|---|
| data | /app/data | 10Gi | Library data, configuration, metadata |
| books | /books | 50Gi | Library book files |
| bookdrop | /bookdrop | disabled | BookDrop import folder |
Local filesystems use app.diskType=LOCAL. For network-attached book storage,
set app.diskType=NETWORK; upstream then disables file writes and
reorganization to avoid unsafe filesystem behavior.
Production
Production deployments should pin the public browser origin, source database credentials from a Secret, protect all three persistent data domains, and keep the application at one replica unless shared-storage concurrency has been validated independently. See docs/production.md and examples/production.yaml.
Examples
Security
- The pod does not mount a Kubernetes API token by default.
- The main container drops all capabilities except the four required by the upstream entrypoint to create and switch to its runtime user.
- Use existing Secrets or External Secrets for production database credentials; inline values remain visible in Helm release state.
- Restrict
app.allowedOriginsto the public HTTPS origin and review outbound NetworkPolicy rules for MariaDB and metadata providers.
Troubleshooting
- Slow startup: wait for Flyway migrations and inspect the BookLore and MariaDB logs before restarting the pod.
- Probe failures: verify
BOOKLORE_PORTandapp.portmatch, then request/api/v1/healthcheckinside the application container. - Database failures: confirm the JDBC host, port, database, username, and Secret key all refer to the same MariaDB instance.
- Missing books: verify the
/booksPVC is mounted and thatapp.diskTypematches the underlying filesystem type. - Multi-replica validation errors: every enabled persistence volume requires
ReadWriteMany; otherwise keep one replica.
Documentation
Security Scan: booklore
| Framework | Score |
|---|---|
| MITRE + NSA + SOC2 | 89.90% |
Security posture acceptable.
Links
System Architecture
DESIGN.md SyncedVerified architecture contract rendered dynamically from GitHub DESIGN.md
flowchart LR user[Users and reading clients] --> route[Ingress or HTTPRoute] route --> service[BookLore Service] service --> app[BookLore Deployment] app --> database[(Bundled or external MariaDB)] app --> data[(Application data PVC)] app --> books[(Books PVC)] app --> bookdrop[(Optional BookDrop PVC)] secret[Secret or ExternalSecret] --> app monitor[Optional ServiceMonitor] --> service
Booklore Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared with dependencies. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | - | Chart configuration parameter |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | - | Chart configuration parameter |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Chart configuration parameter |
Common Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonAnnotations | object | - | Chart configuration parameter |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | - | Chart configuration parameter |
| image.tag | string | - | Chart configuration parameter |
| image.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Chart configuration parameter |
Replica Count(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| replicaCount | integer | - | Chart configuration parameter |
App(9)
| Parameter | Type | Default | Description |
|---|---|---|---|
| app.port | integer | - | Chart configuration parameter |
| app.rootLogLevel | string | - | Chart configuration parameter |
| app.logLevel | string | - | Chart configuration parameter |
| app.allowedOrigins | string | - | Chart configuration parameter |
| app.diskType | string | - | Chart configuration parameter Allowed: LOCALNETWORK |
| app.command | array | - | Chart configuration parameter |
| app.args | array | - | Chart configuration parameter |
| app.env | array | - | Chart configuration parameter |
| app.envFrom | array | - | Chart configuration parameter |
Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| secrets.existingSecret | string | - | Chart configuration parameter |
Database(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| database.external.host | string | - | Chart configuration parameter |
| database.external.port | stringinteger | - | Chart configuration parameter |
| database.external.name | string | - | Chart configuration parameter |
| database.external.username | string | - | Chart configuration parameter |
| database.external.password | string | - | Chart configuration parameter |
| database.external.existingSecret | string | - | Chart configuration parameter |
| database.external.existingSecretPasswordKey | string | - | Chart configuration parameter |
Oidc(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| oidc.enabled | boolean | - | Chart configuration parameter |
| oidc.forceDisable | boolean | - | Chart configuration parameter |
Remote Auth(8)
| Parameter | Type | Default | Description |
|---|---|---|---|
| remoteAuth.enabled | boolean | - | Chart configuration parameter |
| remoteAuth.createNewUsers | boolean | - | Chart configuration parameter |
| remoteAuth.headerName | string | - | Chart configuration parameter |
| remoteAuth.headerUser | string | - | Chart configuration parameter |
| remoteAuth.headerEmail | string | - | Chart configuration parameter |
| remoteAuth.headerGroups | string | - | Chart configuration parameter |
| remoteAuth.adminGroup | string | - | Chart configuration parameter |
| remoteAuth.groupsDelimiter | string | - | Chart configuration parameter |
Persistence(15)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.data.enabled | boolean | - | Chart configuration parameter |
| persistence.data.size | string | - | Chart configuration parameter |
| persistence.data.storageClass | string | - | Chart configuration parameter |
| persistence.data.accessModes | array | - | Chart configuration parameter |
| persistence.data.existingClaim | string | - | Chart configuration parameter |
| persistence.books.enabled | boolean | - | Chart configuration parameter |
| persistence.books.size | string | - | Chart configuration parameter |
| persistence.books.storageClass | string | - | Chart configuration parameter |
| persistence.books.accessModes | array | - | Chart configuration parameter |
| persistence.books.existingClaim | string | - | Chart configuration parameter |
| persistence.bookdrop.enabled | boolean | - | Chart configuration parameter |
| persistence.bookdrop.size | string | - | Chart configuration parameter |
| persistence.bookdrop.storageClass | string | - | Chart configuration parameter |
| persistence.bookdrop.accessModes | array | - | Chart configuration parameter |
| persistence.bookdrop.existingClaim | string | - | Chart configuration parameter |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | - | Chart configuration parameter |
| serviceAccount.name | string | - | Chart configuration parameter |
| serviceAccount.annotations | object | - | Chart configuration parameter |
| serviceAccount.automountServiceAccountToken | boolean | - | Chart configuration parameter |
Service & Networking(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | - | Chart configuration parameter Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | - | Chart configuration parameter |
| service.annotations | object | - | Chart configuration parameter |
| service.ipFamilyPolicy | string | - | Chart configuration parameter Allowed: SingleStackPreferDualStackRequireDualStack |
| service.ipFamilies | array | - | Chart configuration parameter |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | - | Chart configuration parameter |
| ingress.ingressClassName | string | - | Chart configuration parameter |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Chart configuration parameter |
| ingress.tls | array | - | Chart configuration parameter |
Gateway API(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gatewayAPI.enabled | boolean | - | Chart configuration parameter |
| gatewayAPI.httpRoutes | array | - | Chart configuration parameter |
External Secrets(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | - | Chart configuration parameter |
| externalSecrets.apiVersion | string | - | Chart configuration parameter |
| externalSecrets.refreshInterval | string | - | Chart configuration parameter |
| externalSecrets.items | array | - | Chart configuration parameter |
Health Probes(15)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | - | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | - | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | - | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources.requests.cpu | stringnumber | - | Chart configuration parameter |
| resources.requests.memory | string | - | Chart configuration parameter |
| resources.limits.cpu | stringnumber | - | Chart configuration parameter |
| resources.limits.memory | string | - | Chart configuration parameter |
Wait For Database(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| waitForDatabase.image.repository | string | - | Chart configuration parameter |
| waitForDatabase.image.tag | string | - | Chart configuration parameter |
| waitForDatabase.image.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| waitForDatabase.resources.requests.cpu | stringnumber | - | Chart configuration parameter |
| waitForDatabase.resources.requests.memory | string | - | Chart configuration parameter |
| waitForDatabase.resources.limits.cpu | stringnumber | - | Chart configuration parameter |
| waitForDatabase.resources.limits.memory | string | - | Chart configuration parameter |
Pod Security(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.fsGroup | integer | - | Chart configuration parameter |
| podSecurityContext.fsGroupChangePolicy | string | - | Chart configuration parameter Allowed: AlwaysOnRootMismatch |
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter |
Container Security(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
| securityContext.capabilities.add | array | - | Chart configuration parameter |
| securityContext.readOnlyRootFilesystem | boolean | - | Chart configuration parameter |
| securityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| securityContext.runAsUser | integer | - | Chart configuration parameter |
| securityContext.seccompProfile.type | string | - | Chart configuration parameter |
Pdb(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| pdb.enabled | boolean | - | Chart configuration parameter |
| pdb.minAvailable | integerstring | - | Chart configuration parameter |
Network Policy(8)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | - | Chart configuration parameter |
| networkPolicy.ingressFrom | array | - | Chart configuration parameter |
| networkPolicy.egress.enabled | boolean | - | Chart configuration parameter |
| networkPolicy.egress.allowDNS | boolean | - | Chart configuration parameter |
| networkPolicy.egress.dnsPeers | array | - | Chart configuration parameter |
| networkPolicy.egress.databaseTo | array | - | Chart configuration parameter |
| networkPolicy.egress.extraTo | array | - | Chart configuration parameter |
| networkPolicy.egress.extraEgress | array | - | Chart configuration parameter |
Autoscaling(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| autoscaling.enabled | boolean | - | Chart configuration parameter |
| autoscaling.minReplicas | integer | - | Chart configuration parameter |
| autoscaling.maxReplicas | integer | - | Chart configuration parameter |
| autoscaling.targetCPUUtilizationPercentage | integer | - | Chart configuration parameter |
| autoscaling.targetMemoryUtilizationPercentage | any | - | Chart configuration parameter |
Monitoring(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| monitoring.serviceMonitor.enabled | boolean | - | Chart configuration parameter |
| monitoring.serviceMonitor.labels | object | - | Chart configuration parameter |
| monitoring.serviceMonitor.interval | string | - | Chart configuration parameter |
| monitoring.serviceMonitor.path | string | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Chart configuration parameter |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Chart configuration parameter |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Chart configuration parameter |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Chart configuration parameter |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | - | Chart configuration parameter |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | - | Chart configuration parameter |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Chart configuration parameter |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Chart configuration parameter |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Chart configuration parameter |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Chart configuration parameter |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Chart configuration parameter |
Mariadb(15)
| Parameter | Type | Default | Description |
|---|---|---|---|
| mariadb.enabled | boolean | - | Chart configuration parameter |
| mariadb.nameOverride | string | - | Chart configuration parameter |
| mariadb.fullnameOverride | string | - | Chart configuration parameter |
| mariadb.auth.database | string | - | Chart configuration parameter |
| mariadb.auth.username | string | - | Chart configuration parameter |
| mariadb.auth.password | string | - | Chart configuration parameter |
| mariadb.auth.rootPassword | string | - | Chart configuration parameter |
| mariadb.auth.existingSecret | string | - | Chart configuration parameter |
| mariadb.auth.existingSecretUserPasswordKey | string | - | Chart configuration parameter |
| mariadb.standalone.persistence.enabled | boolean | - | Chart configuration parameter |
| mariadb.standalone.persistence.size | string | - | Chart configuration parameter |
| mariadb.standalone.resources.requests.cpu | stringnumber | - | Chart configuration parameter |
| mariadb.standalone.resources.requests.memory | string | - | Chart configuration parameter |
| mariadb.standalone.resources.limits.cpu | stringnumber | - | Chart configuration parameter |
| mariadb.standalone.resources.limits.memory | string | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.