BookLore

Deploy BookLore on Kubernetes using the official ghcr.io/booklore-app/booklore container image. A self-hosted eBook library management application with metadata fetching, OPDS support, and a modern web-based reader for managing your personal digital book collection.

Chart References

• Chart source
• Chart design

Key Features

• MariaDB bundled – HelmForge MariaDB subchart handles the database automatically
• External database – connect to an existing MariaDB/MySQL instance instead
• Triple PVC architecture – /app/data (metadata), /books (library files), /bookdrop (imports)
• OIDC guardrail – force-disable upstream OIDC while it is configured through the BookLore interface
• Remote/proxy auth – header-based authentication for reverse proxy setups
• NetworkPolicy – egress constrained to kube-system (DNS) and MariaDB only
• Gateway API – optional HTTPRoute support for clusters using Gateway API
• External Secrets – optional ExternalSecret items for secrets management
• HPA guardrails – validation prevents multi-replica scaling with ReadWriteOnce storage

Architecture

The Service targets the Deployment’s named http port. app.port configures the actual BOOKLORE_PORT listener and all health probes; service.port remains an independent Kubernetes-facing port. BookLore connects to the bundled or external MariaDB service and mounts separate data, books, and optional BookDrop volumes.

The official health endpoint is /api/v1/healthcheck. The default Recreate strategy prevents overlapping mounts during upgrades that use ReadWriteOnce storage.

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install booklore helmforge/booklore -f values.yaml

OCI registry:

helm install booklore oci://ghcr.io/helmforgedev/helm/booklore -f values.yaml

Deployment Examples

# values.yaml -- BookLore basic setup with bundled MariaDB
# MariaDB subchart handles the database automatically.
persistence:
  data:
    enabled: true
    size: 5Gi

  books:
    enabled: true
    size: 50Gi

# values.yaml -- Production BookLore with TLS, tuning, and BookDrop
app:
  rootLogLevel: WARN
  logLevel: INFO

persistence:
  data:
    enabled: true
    size: 10Gi
    storageClass: longhorn

  books:
    enabled: true
    size: 200Gi
    storageClass: longhorn

  bookdrop:
    enabled: true
    size: 10Gi
    storageClass: longhorn

resources:
  requests:
    memory: 512Mi
    cpu: 250m
  limits:
    memory: 1Gi
    cpu: '1'

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: booklore.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: booklore-tls
      hosts:
        - booklore.example.com

mariadb:
  standalone:
    persistence:
      enabled: true
      size: 5Gi
      storageClass: longhorn
    resources:
      requests:
        memory: 256Mi
        cpu: 100m
      limits:
        memory: 512Mi
        cpu: 500m

# values.yaml -- BookLore with external MariaDB/MySQL
mariadb:
  enabled: false

database:
  external:
    host: mariadb.example.com
    port: '3306'
    name: booklore
    username: booklore
    existingSecret: booklore-db-credentials
    existingSecretPasswordKey: password

persistence:
  data:
    enabled: true
    size: 5Gi
  books:
    enabled: true
    size: 100Gi

# values.yaml -- BookLore with Ingress exposure
ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: booklore.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: booklore-tls
      hosts:
        - booklore.example.com

# values.yaml -- BookLore with Gateway API HTTPRoute
gatewayAPI:
  enabled: true
  httpRoutes:
    - name: booklore
      parentRefs:
        - name: main-gateway
          namespace: gateway-system
      hostnames:
        - booklore.example.com
      rules:
        - matches:
            - path:
                type: PathPrefix
                value: /
          backendRefs:
            - name: booklore
              port: 6060

Configuration Reference

Application Settings

Image Configuration

Persistence

Database

Authentication

Networking

Monitoring and Scaling

Security and production boundaries

• Service-account token mounting is disabled by default.
• Database credentials can come from an existing Secret or ExternalSecret; inline passwords remain visible in Helm release state.
• Restrict app.allowedOrigins to the public HTTPS origin and allow required metadata-provider egress when enabling NetworkPolicy restrictions.
• app.diskType=NETWORK disables file writes and reorganization for network-attached book storage; it does not make every network filesystem safe or supported.
• The stock pinned image has no Prometheus endpoint, so ServiceMonitor remains disabled unless an operator supplies a compatible image and path.

Troubleshooting

• For slow startup, inspect Flyway and MariaDB logs before restarting the pod.
• For probe failures, verify BOOKLORE_PORT matches app.port and request /api/v1/healthcheck inside the container.
• For missing books, verify the /books PVC and app.diskType contract.
• For database failures, verify the JDBC endpoint, username, and Secret key refer to the same MariaDB instance.