Komga

Deploy Komga on Kubernetes using the official gotson/komga Docker image. A media server for comics, mangas, BDs, magazines, and eBooks with a modern web reader, OPDS support, and native apps for iOS and Android.

Komga 1.29.1 supersedes 1.29.0 with fixes for NextUI reader links and dialogs. The 1.29 line adds notable entities, OAuth2 login in NextUI, a selectable default UI, and persistent HTTP sessions in a dedicated SQLite database. The chart’s /config PVC persists both the main and session databases; back it up before upgrading.

Upgrade Compatibility

The chart preserves the root UID/GID behavior from previous releases so root-owned SQLite databases on existing /config PVCs remain writable. The new compatible security defaults prevent privilege escalation, use RuntimeDefault seccomp, and disable Kubernetes API token mounts without changing file ownership or filesystem access.

Back up /config, then use either a normal upgrade with your values file or reuse the values stored in the release:

helm upgrade komga helmforge/komga --namespace komga -f values.yaml
helm upgrade komga helmforge/komga --namespace komga --reset-then-reuse-values

--reset-then-reuse-values applies new chart defaults while retaining explicit values from the previous release; those explicit values still take precedence. Both paths retain the existing /config and /data claims. Custom non-root UID/GID settings remain supported, but operators must verify PVC ownership and access before enabling them.

Chart References

• Chart source
• Chart design
• Standards completion PR

Key Features

• No database server — SQLite stored in /config PVC, zero external dependencies
• Dual PVC architecture — /config (metadata) and /data (library files) are separate
• OPDS support — works with Kybook, Chunky, Moon+ Reader, and other OPDS clients
• JVM tuning — configurable JVM flags via javaToolOptions (-Xmx, GC options)
• S3 backup — consistent SQLite export via Alpine backup job (covers /config only)
• External Secrets — optional ExternalSecret items for S3 backup credentials
• Gateway API — optional HTTPRoute for clusters using Gateway API
• Session timeout — configurable for long-lived mobile client sessions

Installation

HTTPS repository:

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

OCI registry:

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

Deployment Examples

# values.yaml — Komga basic setup with dual PVC
komga:
  timezone: UTC
  sessionTimeout: '7d' # increase for mobile clients (default 30m is too short)
  javaToolOptions: '-Xmx1g' # limit JVM heap; use javaToolOptions (javaMemory is deprecated)

persistence:
  config:
    enabled: true
    size: 2Gi # SQLite database, thumbnails, app config

  data:
    enabled: true
    size: 100Gi # comic/manga file storage

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: komga.example.com
      paths:
        - path: /
          pathType: Prefix

# values.yaml — Production Komga with TLS and tuning
komga:
  timezone: America/Sao_Paulo
  sessionTimeout: '7d'
  javaToolOptions: '-Xms512m -Xmx2g -XX:+UseG1GC'

persistence:
  config:
    enabled: true
    size: 5Gi
    storageClass: longhorn

  data:
    enabled: true
    size: 500Gi
    storageClass: longhorn

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

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

# values.yaml — Komga with daily S3 backup of /config (SQLite + metadata)
# NOTE: The backup covers /config only (database and thumbnails).
# Comic/manga files in /data must be backed up separately.
komga:
  timezone: UTC
  javaToolOptions: '-Xmx2g'

persistence:
  config:
    enabled: true
    size: 5Gi
  data:
    enabled: true
    size: 500Gi

backup:
  enabled: true
  schedule: '0 2 * * *'
  archivePrefix: komga
  includeLogs: true # include /config/logs in the archive
  s3:
    endpoint: https://s3.amazonaws.com
    bucket: my-komga-backups
    existingSecret: komga-s3-credentials
    existingSecretAccessKeyKey: access-key
    existingSecretSecretKeyKey: secret-key

# values.yaml — Komga backup credentials projected by External Secrets Operator
backup:
  enabled: true
  schedule: '0 2 * * *'
  s3:
    endpoint: https://s3.amazonaws.com
    bucket: my-komga-backups
    existingSecret: komga-backup-s3

externalSecrets:
  enabled: true
  items:
    - name: backup-s3
      spec:
        secretStoreRef:
          name: platform-secrets
          kind: ClusterSecretStore
        target:
          name: komga-backup-s3
          creationPolicy: Owner
        data:
          - secretKey: access-key
            remoteRef:
              key: komga/backup
              property: access-key
          - secretKey: secret-key
            remoteRef:
              key: komga/backup
              property: secret-key

# values.yaml — Komga with NFS-mounted library (data from existing NFS PVC)
komga:
  timezone: UTC
  sessionTimeout: '7d'
  javaToolOptions: '-Xmx2g'

persistence:
  config:
    enabled: true
    size: 5Gi

  data:
    enabled: false # don't create a new PVC for data
    existingClaim: nfs-komga-library # bind to pre-existing NFS PVC

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: komga.example.com
      paths:
        - path: /
          pathType: Prefix

Configuration Reference

Core

Image

Komga Configuration

Persistence

Service

Ingress

Gateway API

Backup

External Secrets

Komga uses the HelmForge canonical externalSecrets.items[] contract. External Secrets Operator is installed out-of-band; this chart only renders ExternalSecret resources when enabled. See the External Secrets documentation for provider configuration.

Probes

Resources and Scheduling

Extra

Security

Komga and its optional backup containers use RuntimeDefault seccomp, block privilege escalation, and do not receive a Kubernetes API token. The official image currently starts as root; the chart intentionally preserves that UID and its discretionary filesystem access because earlier installations may contain root-owned files or restrictive files written by a custom UID. A read-only root filesystem is not enabled because the SQLite JDBC driver extracts a native library while starting.

Use TLS for external routes and an existing Secret or ExternalSecret for S3 credentials. NetworkPolicy, encrypted storage, image admission, log retention, and alerting remain responsibilities of the cluster platform.

Security Scan

Security posture: compatible hardening is enabled by default. The remaining root-user and writable-root-filesystem constraints are documented in the chart design with their upgrade and runtime rationale.

More Information

• Komga Official Documentation
• Komga GitHub Repository
• OPDS Client List
• HelmForge Komga Chart Source