Skip to content
Komga icon
v1.6.0App: v1.29.1Pinned DigestS3 Backup Ready

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

Komga Helm Chart

Deploy Komga on Kubernetes — a media server for comics, mangas, BDs, magazines, and eBooks with OPDS support.

Features

  • SQLite Database — zero database configuration, persistent via PVC
  • Dual Persistent Volumes — separate PVCs for config (/config) and library data (/data)
  • Java Tool Options — configurable JVM tuning via JAVA_TOOL_OPTIONS
  • Timezone Support — configurable via TZ environment variable
  • Ingress — optional with TLS and cert-manager support
  • Gateway API — optional HTTPRoute for clusters using Gateway API
  • External Secrets — optional ExternalSecret for S3 backup credentials
  • S3 Backup — scheduled CronJob with consistent SQLite exports, static credentials or workload identity, and config archive upload
  • Common Annotations — chart-wide metadata with resource-specific precedence

Design

See DESIGN.md for the chart architecture, production boundary, and explicit non-goals.

Installation

HTTPS Repository

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install komga helmforge/komga

OCI Registry

helm install komga oci://ghcr.io/helmforgedev/helm/komga

Quick Start

persistence:
  config:
    enabled: true
    size: 2Gi
  data:
    enabled: true
    size: 100Gi

After deploying, port-forward to access the web interface and create your admin account:

kubectl port-forward svc/<release>-komga 25600:80

Upgrade Notes

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 for Docker deployments. The chart's /config PVC covers both the main database and the session database. Back up that PVC before upgrading.

Chart upgrades preserve the root UID/GID behavior used by previous releases. The container now drops all Linux capabilities, so verify that existing /config and /data files are accessible to the configured runAsUser, runAsGroup, or fsGroup before upgrading. Set podSecurityContext.fsGroup to the storage group when an existing PVC is not root-readable. Both regular upgrades and --reuse-values upgrades retain the PVC claims.

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.

Production Example

komga:
  timezone: "UTC"
  javaToolOptions: "-Xmx2g -XX:+UseG1GC"
  sessionTimeout: "7d"

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

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

backup:
  enabled: true
  schedule: "0 3 * * *"
  s3:
    endpoint: https://s3.amazonaws.com
    bucket: my-backups
    prefix: komga
    existingSecret: komga-s3-credentials

Values

Common Metadata

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

Image

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

Komga Configuration

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

Persistence

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

Service

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

Ingress

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

Gateway API

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

External Secrets

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

Example projecting S3 backup credentials:

backup:
  enabled: true
  s3:
    endpoint: https://s3.amazonaws.com
    bucket: my-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

Backup

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

Backup Behavior

The backup CronJob exports each SQLite database found in /config using sqlite3 VACUUM INTO, then packages those exported databases together with top-level application config files and optional logs before uploading the archive to S3. Search indexes are intentionally excluded because Komga can rebuild them.

Security

The default Pod does not receive a Kubernetes API token. Komga and the backup containers run with privilege escalation disabled and the runtime-default seccomp profile. The upstream image currently starts as root, and the chart preserves that UID and its filesystem access by default so upgrades can continue reading existing SQLite databases even when an older custom UID created restrictive files. Set runAsUser, runAsGroup, runAsNonRoot, or capability overrides only after confirming ownership and access on /config and /data.

Use TLS for external routes and an existing Secret or ExternalSecret for backup credentials. NetworkPolicy, storage encryption, and image admission are cluster responsibilities.

Security Scan

Security Scan: komga

Framework Score
MITRE + NSA + SOC2 73%

Security posture: acceptable with follow-up hardening candidates documented in DESIGN.md.

Architecture

Komga runs as a single Deployment with a Java-based server on port 25600. It uses SQLite for its database (stored in /config) and serves comic/manga libraries from /data.

The chart creates two separate PVCs:

  • config — small volume for SQLite database and application settings
  • data — large volume for comic/manga library files

Documentation

Troubleshooting

kubectl get pods,pvc -n komga
kubectl logs deployment/komga-komga -n komga
kubectl get events -n komga --sort-by=.lastTimestamp

If Komga cannot open its SQLite database after setting a custom UID or GID, restore the prior security context and correct ownership on the /config PVC before retrying. If a probe fails behind a subpath, ensure komga.contextPath and the probe paths describe the same route.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  users[Readers and admins] --> service[Komga Service]
  ingress[Ingress optional] --> service
  route[HTTPRoute optional] --> service
  service --> deploy[Komga Deployment]
  deploy --> config[(Config PVC /config)]
  deploy --> data[(Library PVC /data)]
  cron[Backup CronJob optional] --> config
  cron --> s3[S3-compatible bucket]
  eso[ExternalSecret optional] --> secret[S3 credentials Secret]
  secret --> cron
Official Contractvalues.schema.json

Komga Values Schema Reference

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

127 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Override the chart name used in resource names

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Override the full release name used in resource names

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart

Common Annotations(1)

ParameterTypeDefaultDescription
commonAnnotationsobject-Annotations added to every resource created by this chart

Image(3)

ParameterTypeDefaultDescription
image.repositorystringdocker.io/gotson/komgaKomga image repository
image.tagstring""Komga image tag (defaults to appVersion)
image.pullPolicystringIfNotPresentImage pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Komga(7)

ParameterTypeDefaultDescription
komga.portinteger25600Server port inside the container
komga.contextPathstring/Base URL path for reverse proxy (e.g. "/komga")
komga.sessionTimeoutstring30mSession timeout duration (e.g. "30m", "7d")
komga.timezonestringUTCTimezone (for example: "UTC", "Europe/London")
komga.javaToolOptionsstring""Value passed to JAVA_TOOL_OPTIONS (for example: "-Xmx1g", "-Xms512m -Xmx2g", "-XX:+UseG1GC")
komga.javaMemorystring""Deprecated: use komga.javaToolOptions instead
komga.extraEnvarray-Extra environment variables

Service Account(3)

ParameterTypeDefaultDescription
serviceAccount.createbooleanfalseCreate a ServiceAccount for Komga
serviceAccount.namestring""ServiceAccount name (defaults to fullname)
serviceAccount.annotationsobject-Annotations added to the ServiceAccount

Persistence(12)

ParameterTypeDefaultDescription
persistence.config.enabledbooleantruePersist /config with a PVC (database and application config)
persistence.config.existingClaimstring""Existing PVC name for config
persistence.config.storageClassstring""Storage class for the config PVC
persistence.config.accessModestringReadWriteOnceAccess mode for the config PVC
Allowed:ReadWriteOnceReadOnlyManyReadWriteMany
persistence.config.sizestring2GiSize of the config PVC
persistence.config.annotationsobject-Annotations added to the config PVC
persistence.data.enabledbooleantruePersist /data with a PVC (comics/manga libraries)
persistence.data.existingClaimstring""Existing PVC name for data
persistence.data.storageClassstring""Storage class for the data PVC
persistence.data.accessModestringReadWriteOnceAccess mode for the data PVC
Allowed:ReadWriteOnceReadOnlyManyReadWriteMany
persistence.data.sizestring50GiSize of the data PVC
persistence.data.annotationsobject-Annotations added to the data PVC

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestringClusterIPService type
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger80HTTP service port
service.annotationsobject-Annotations for the Service
service.ipFamilyPolicystring-Service IP family policy
Allowed:SingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Service IP families

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledbooleanfalseEnable ingress for Komga
ingress.ingressClassNamestringtraefikIngress class name (for example: traefik, nginx)
ingress.annotationsobject-Annotations for the Ingress resource
ingress.hostsarray-Ingress hosts
ingress.tlsarray-Ingress TLS configuration

Health Probes(18)

ParameterTypeDefaultDescription
probes.startup.enabledbooleantrueChart configuration parameter
probes.startup.pathstring/Chart configuration parameter
probes.startup.initialDelaySecondsinteger15Chart configuration parameter
probes.startup.periodSecondsinteger5Chart configuration parameter
probes.startup.timeoutSecondsinteger3Chart configuration parameter
probes.startup.failureThresholdinteger30Chart configuration parameter
probes.liveness.enabledbooleantrueChart configuration parameter
probes.liveness.pathstring/Chart configuration parameter
probes.liveness.initialDelaySecondsinteger0Chart configuration parameter
probes.liveness.periodSecondsinteger15Chart configuration parameter
probes.liveness.timeoutSecondsinteger5Chart configuration parameter
probes.liveness.failureThresholdinteger3Chart configuration parameter
probes.readiness.enabledbooleantrueChart configuration parameter
probes.readiness.pathstring/Chart configuration parameter
probes.readiness.initialDelaySecondsinteger0Chart configuration parameter
probes.readiness.periodSecondsinteger10Chart configuration parameter
probes.readiness.timeoutSecondsinteger5Chart configuration parameter
probes.readiness.failureThresholdinteger3Chart configuration parameter

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-CPU and memory requests/limits for the Komga container

Pod Security(4)

ParameterTypeDefaultDescription
podSecurityContext.runAsUserintegernull-Chart configuration parameter
podSecurityContext.runAsGroupintegernull-Chart configuration parameter
podSecurityContext.fsGroupintegernull-Chart configuration parameter
podSecurityContext.seccompProfileobjectnull-Chart configuration parameter

Container Security(6)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationbooleannull-Chart configuration parameter
securityContext.runAsNonRootbooleannull-Chart configuration parameter
securityContext.runAsUserintegernull-Chart configuration parameter
securityContext.runAsGroupintegernull-Chart configuration parameter
securityContext.readOnlyRootFilesystembooleannull-Chart configuration parameter
securityContext.capabilitiesobjectnull-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector for pod scheduling

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations for pod scheduling

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules for pod scheduling

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Topology spread constraints

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring""Priority class name

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger30Grace period for pod termination in seconds

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Additional labels for the pod

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Additional annotations for the pod

Backup(32)

ParameterTypeDefaultDescription
backup.enabledbooleanfalseEnable built-in backup CronJob support (consistent SQLite export + config archive + S3 upload)
backup.schedulestring0 2 * * *Backup schedule in Cron format
backup.suspendbooleanfalseSuspend backup execution
backup.concurrencyPolicystringForbidCronJob concurrency policy
Allowed:ForbidReplaceAllow
backup.successfulJobsHistoryLimitinteger3Successful job history retained
backup.failedJobsHistoryLimitinteger3Failed job history retained
backup.backoffLimitinteger1Job backoff limit
backup.archivePrefixstringkomgaPrefix used in generated backup archive names
backup.includeLogsbooleantrueInclude the logs directory in backup archives when it exists
backup.resourcesobject-Resources for backup containers
backup.podSecurityContextobject-Backup pod security context merged over the application podSecurityContext
backup.serviceAccount.createbooleantrueChart configuration parameter
backup.serviceAccount.namestring""Chart configuration parameter
backup.serviceAccount.annotationsobject-Chart configuration parameter
backup.serviceAccount.automountServiceAccountTokenbooleantrueChart configuration parameter
backup.images.uploader.repositorystringdocker.io/helmforge/mcChart configuration parameter
backup.images.uploader.tagstring-Chart configuration parameter
backup.images.uploader.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
backup.images.sqlite.repositorystringdocker.io/library/alpineChart configuration parameter
backup.images.sqlite.tagstring-Chart configuration parameter
backup.images.sqlite.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
backup.s3.endpointstring""S3-compatible endpoint URL
backup.s3.bucketstring""Target bucket name
backup.s3.prefixstringkomgaOptional key prefix inside the bucket
backup.s3.regionstring""AWS region used by ambient workload identity credentials
backup.s3.credentialsFromPodIdentitybooleanfalseUse ambient workload identity instead of static S3 credentials
backup.s3.createBucketIfNotExistsbooleantrueCreate the bucket automatically when it does not exist
backup.s3.existingSecretstring""Existing secret containing access-key and secret-key
backup.s3.existingSecretAccessKeyKeystringaccess-keyKey in the existing secret for the access key
backup.s3.existingSecretSecretKeyKeystringsecret-keyKey in the existing secret for the secret key
backup.s3.accessKeystring""Inline access key
backup.s3.secretKeystring""Inline secret key

Gateway(6)

ParameterTypeDefaultDescription
gateway.enabledbooleanfalseCreate an HTTPRoute. Requires Gateway API CRDs installed.
gateway.annotationsobject-Chart configuration parameter
gateway.parentRefsarray-parentRefs list pointing to your Gateway resource
gateway.hostnamesarray-Chart configuration parameter
gateway.pathstring/Chart configuration parameter
gateway.pathTypestringPathPrefixChart configuration parameter
Allowed:PathPrefixExactRegularExpression

External Secrets(8)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseRender ExternalSecret resources
externalSecrets.apiVersionstringexternal-secrets.io/v1Deprecated compatibility field. ExternalSecret resources render as external-secrets.io/v1.
externalSecrets.refreshIntervalstring1hDefault provider sync interval for ExternalSecret items that do not set spec.refreshInterval
externalSecrets.itemsarray-ExternalSecret definitions with full spec blocks
externalSecrets.secretStoreRef.namestring""Chart configuration parameter
externalSecrets.secretStoreRef.kindstringSecretStoreChart configuration parameter
Allowed:SecretStoreClusterSecretStore
externalSecrets.target.creationPolicystringOwnerChart configuration parameter
Allowed:OwnerMergeNoneOrphan
externalSecrets.dataarray-Deprecated compatibility field for the legacy single ExternalSecret surface

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Additional volumes for the pod

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Additional volume mounts for the container

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra manifests to deploy alongside the chart