Skip to content
Booklore icon
v2.0.7App: v2.3.1Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

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

Official Schema

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.

View Values Schema

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.allowedOrigins to 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_PORT and app.port match, then request /api/v1/healthcheck inside 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 /books PVC is mounted and that app.diskType matches 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 Synced

Verified 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
Official Contractvalues.schema.json

Booklore Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

153 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared with dependencies.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Chart configuration parameter

Common Annotations(1)

ParameterTypeDefaultDescription
commonAnnotationsobject-Chart configuration parameter

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring-Chart configuration parameter
image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Replica Count(1)

ParameterTypeDefaultDescription
replicaCountinteger-Chart configuration parameter

App(9)

ParameterTypeDefaultDescription
app.portinteger-Chart configuration parameter
app.rootLogLevelstring-Chart configuration parameter
app.logLevelstring-Chart configuration parameter
app.allowedOriginsstring-Chart configuration parameter
app.diskTypestring-Chart configuration parameter
Allowed:LOCALNETWORK
app.commandarray-Chart configuration parameter
app.argsarray-Chart configuration parameter
app.envarray-Chart configuration parameter
app.envFromarray-Chart configuration parameter

Secrets(1)

ParameterTypeDefaultDescription
secrets.existingSecretstring-Chart configuration parameter

Database(7)

ParameterTypeDefaultDescription
database.external.hoststring-Chart configuration parameter
database.external.portstringinteger-Chart configuration parameter
database.external.namestring-Chart configuration parameter
database.external.usernamestring-Chart configuration parameter
database.external.passwordstring-Chart configuration parameter
database.external.existingSecretstring-Chart configuration parameter
database.external.existingSecretPasswordKeystring-Chart configuration parameter

Oidc(2)

ParameterTypeDefaultDescription
oidc.enabledboolean-Chart configuration parameter
oidc.forceDisableboolean-Chart configuration parameter

Remote Auth(8)

ParameterTypeDefaultDescription
remoteAuth.enabledboolean-Chart configuration parameter
remoteAuth.createNewUsersboolean-Chart configuration parameter
remoteAuth.headerNamestring-Chart configuration parameter
remoteAuth.headerUserstring-Chart configuration parameter
remoteAuth.headerEmailstring-Chart configuration parameter
remoteAuth.headerGroupsstring-Chart configuration parameter
remoteAuth.adminGroupstring-Chart configuration parameter
remoteAuth.groupsDelimiterstring-Chart configuration parameter

Persistence(15)

ParameterTypeDefaultDescription
persistence.data.enabledboolean-Chart configuration parameter
persistence.data.sizestring-Chart configuration parameter
persistence.data.storageClassstring-Chart configuration parameter
persistence.data.accessModesarray-Chart configuration parameter
persistence.data.existingClaimstring-Chart configuration parameter
persistence.books.enabledboolean-Chart configuration parameter
persistence.books.sizestring-Chart configuration parameter
persistence.books.storageClassstring-Chart configuration parameter
persistence.books.accessModesarray-Chart configuration parameter
persistence.books.existingClaimstring-Chart configuration parameter
persistence.bookdrop.enabledboolean-Chart configuration parameter
persistence.bookdrop.sizestring-Chart configuration parameter
persistence.bookdrop.storageClassstring-Chart configuration parameter
persistence.bookdrop.accessModesarray-Chart configuration parameter
persistence.bookdrop.existingClaimstring-Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter
serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Chart configuration parameter
service.annotationsobject-Chart configuration parameter
service.ipFamilyPolicystring-Chart configuration parameter
Allowed:SingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Chart configuration parameter

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Chart configuration parameter
ingress.ingressClassNamestring-Chart configuration parameter
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Gateway API(2)

ParameterTypeDefaultDescription
gatewayAPI.enabledboolean-Chart configuration parameter
gatewayAPI.httpRoutesarray-Chart configuration parameter

External Secrets(4)

ParameterTypeDefaultDescription
externalSecrets.enabledboolean-Chart configuration parameter
externalSecrets.apiVersionstring-Chart configuration parameter
externalSecrets.refreshIntervalstring-Chart configuration parameter
externalSecrets.itemsarray-Chart configuration parameter

Health Probes(15)

ParameterTypeDefaultDescription
probes.startup.enabledboolean-Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledboolean-Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledboolean-Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(4)

ParameterTypeDefaultDescription
resources.requests.cpustringnumber-Chart configuration parameter
resources.requests.memorystring-Chart configuration parameter
resources.limits.cpustringnumber-Chart configuration parameter
resources.limits.memorystring-Chart configuration parameter

Wait For Database(7)

ParameterTypeDefaultDescription
waitForDatabase.image.repositorystring-Chart configuration parameter
waitForDatabase.image.tagstring-Chart configuration parameter
waitForDatabase.image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
waitForDatabase.resources.requests.cpustringnumber-Chart configuration parameter
waitForDatabase.resources.requests.memorystring-Chart configuration parameter
waitForDatabase.resources.limits.cpustringnumber-Chart configuration parameter
waitForDatabase.resources.limits.memorystring-Chart configuration parameter

Pod Security(3)

ParameterTypeDefaultDescription
podSecurityContext.fsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupChangePolicystring-Chart configuration parameter
Allowed:AlwaysOnRootMismatch
podSecurityContext.seccompProfile.typestring-Chart configuration parameter

Container Security(7)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter
securityContext.capabilities.addarray-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
securityContext.runAsNonRootboolean-Chart configuration parameter
securityContext.runAsUserinteger-Chart configuration parameter
securityContext.seccompProfile.typestring-Chart configuration parameter

Pdb(2)

ParameterTypeDefaultDescription
pdb.enabledboolean-Chart configuration parameter
pdb.minAvailableintegerstring-Chart configuration parameter

Network Policy(8)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.ingressFromarray-Chart configuration parameter
networkPolicy.egress.enabledboolean-Chart configuration parameter
networkPolicy.egress.allowDNSboolean-Chart configuration parameter
networkPolicy.egress.dnsPeersarray-Chart configuration parameter
networkPolicy.egress.databaseToarray-Chart configuration parameter
networkPolicy.egress.extraToarray-Chart configuration parameter
networkPolicy.egress.extraEgressarray-Chart configuration parameter

Autoscaling(5)

ParameterTypeDefaultDescription
autoscaling.enabledboolean-Chart configuration parameter
autoscaling.minReplicasinteger-Chart configuration parameter
autoscaling.maxReplicasinteger-Chart configuration parameter
autoscaling.targetCPUUtilizationPercentageinteger-Chart configuration parameter
autoscaling.targetMemoryUtilizationPercentageany-Chart configuration parameter

Monitoring(4)

ParameterTypeDefaultDescription
monitoring.serviceMonitor.enabledboolean-Chart configuration parameter
monitoring.serviceMonitor.labelsobject-Chart configuration parameter
monitoring.serviceMonitor.intervalstring-Chart configuration parameter
monitoring.serviceMonitor.pathstring-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter

Mariadb(15)

ParameterTypeDefaultDescription
mariadb.enabledboolean-Chart configuration parameter
mariadb.nameOverridestring-Chart configuration parameter
mariadb.fullnameOverridestring-Chart configuration parameter
mariadb.auth.databasestring-Chart configuration parameter
mariadb.auth.usernamestring-Chart configuration parameter
mariadb.auth.passwordstring-Chart configuration parameter
mariadb.auth.rootPasswordstring-Chart configuration parameter
mariadb.auth.existingSecretstring-Chart configuration parameter
mariadb.auth.existingSecretUserPasswordKeystring-Chart configuration parameter
mariadb.standalone.persistence.enabledboolean-Chart configuration parameter
mariadb.standalone.persistence.sizestring-Chart configuration parameter
mariadb.standalone.resources.requests.cpustringnumber-Chart configuration parameter
mariadb.standalone.resources.requests.memorystring-Chart configuration parameter
mariadb.standalone.resources.limits.cpustringnumber-Chart configuration parameter
mariadb.standalone.resources.limits.memorystring-Chart configuration parameter