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
TZenvironment 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
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.
Image
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.
Komga Configuration
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.
Persistence
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.
Service
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.
Ingress
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.
Gateway API
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.
External Secrets
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.
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
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.
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 SyncedVerified 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
Komga 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 by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Override the chart name used in resource names |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Override the full release name used in resource names |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels added to every resource created by this chart |
Common Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonAnnotations | object | - | Annotations added to every resource created by this chart |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | docker.io/gotson/komga | Komga image repository |
| image.tag | string | "" | Komga image tag (defaults to appVersion) |
| image.pullPolicy | string | IfNotPresent | Image pull policy Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Image pull secrets for private registries |
Komga(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| komga.port | integer | 25600 | Server port inside the container |
| komga.contextPath | string | / | Base URL path for reverse proxy (e.g. "/komga") |
| komga.sessionTimeout | string | 30m | Session timeout duration (e.g. "30m", "7d") |
| komga.timezone | string | UTC | Timezone (for example: "UTC", "Europe/London") |
| komga.javaToolOptions | string | "" | Value passed to JAVA_TOOL_OPTIONS (for example: "-Xmx1g", "-Xms512m -Xmx2g", "-XX:+UseG1GC") |
| komga.javaMemory | string | "" | Deprecated: use komga.javaToolOptions instead |
| komga.extraEnv | array | - | Extra environment variables |
Service Account(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | false | Create a ServiceAccount for Komga |
| serviceAccount.name | string | "" | ServiceAccount name (defaults to fullname) |
| serviceAccount.annotations | object | - | Annotations added to the ServiceAccount |
Persistence(12)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.config.enabled | boolean | true | Persist /config with a PVC (database and application config) |
| persistence.config.existingClaim | string | "" | Existing PVC name for config |
| persistence.config.storageClass | string | "" | Storage class for the config PVC |
| persistence.config.accessMode | string | ReadWriteOnce | Access mode for the config PVC Allowed: ReadWriteOnceReadOnlyManyReadWriteMany |
| persistence.config.size | string | 2Gi | Size of the config PVC |
| persistence.config.annotations | object | - | Annotations added to the config PVC |
| persistence.data.enabled | boolean | true | Persist /data with a PVC (comics/manga libraries) |
| persistence.data.existingClaim | string | "" | Existing PVC name for data |
| persistence.data.storageClass | string | "" | Storage class for the data PVC |
| persistence.data.accessMode | string | ReadWriteOnce | Access mode for the data PVC Allowed: ReadWriteOnceReadOnlyManyReadWriteMany |
| persistence.data.size | string | 50Gi | Size of the data PVC |
| persistence.data.annotations | object | - | Annotations added to the data PVC |
Service & Networking(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | ClusterIP | Service type Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | 80 | HTTP service port |
| service.annotations | object | - | Annotations for the Service |
| service.ipFamilyPolicy | string | - | Service IP family policy Allowed: SingleStackPreferDualStackRequireDualStack |
| service.ipFamilies | array | - | Service IP families |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | false | Enable ingress for Komga |
| ingress.ingressClassName | string | traefik | Ingress class name (for example: traefik, nginx) |
| ingress.annotations | object | - | Annotations for the Ingress resource |
| ingress.hosts | array | - | Ingress hosts |
| ingress.tls | array | - | Ingress TLS configuration |
Health Probes(18)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | true | Chart configuration parameter |
| probes.startup.path | string | / | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | 15 | Chart configuration parameter |
| probes.startup.periodSeconds | integer | 5 | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | 3 | Chart configuration parameter |
| probes.startup.failureThreshold | integer | 30 | Chart configuration parameter |
| probes.liveness.enabled | boolean | true | Chart configuration parameter |
| probes.liveness.path | string | / | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | 0 | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | 15 | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | 5 | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | 3 | Chart configuration parameter |
| probes.readiness.enabled | boolean | true | Chart configuration parameter |
| probes.readiness.path | string | / | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | 0 | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | 10 | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | 5 | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | 3 | Chart configuration parameter |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | CPU and memory requests/limits for the Komga container |
Pod Security(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.runAsUser | integernull | - | Chart configuration parameter |
| podSecurityContext.runAsGroup | integernull | - | Chart configuration parameter |
| podSecurityContext.fsGroup | integernull | - | Chart configuration parameter |
| podSecurityContext.seccompProfile | objectnull | - | Chart configuration parameter |
Container Security(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | booleannull | - | Chart configuration parameter |
| securityContext.runAsNonRoot | booleannull | - | Chart configuration parameter |
| securityContext.runAsUser | integernull | - | Chart configuration parameter |
| securityContext.runAsGroup | integernull | - | Chart configuration parameter |
| securityContext.readOnlyRootFilesystem | booleannull | - | Chart configuration parameter |
| securityContext.capabilities | objectnull | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Node selector for pod scheduling |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Tolerations for pod scheduling |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Affinity rules for pod scheduling |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Topology spread constraints |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | "" | Priority class name |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | 30 | Grace period for pod termination in seconds |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Additional labels for the pod |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Additional annotations for the pod |
Backup(32)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | false | Enable built-in backup CronJob support (consistent SQLite export + config archive + S3 upload) |
| backup.schedule | string | 0 2 * * * | Backup schedule in Cron format |
| backup.suspend | boolean | false | Suspend backup execution |
| backup.concurrencyPolicy | string | Forbid | CronJob concurrency policy Allowed: ForbidReplaceAllow |
| backup.successfulJobsHistoryLimit | integer | 3 | Successful job history retained |
| backup.failedJobsHistoryLimit | integer | 3 | Failed job history retained |
| backup.backoffLimit | integer | 1 | Job backoff limit |
| backup.archivePrefix | string | komga | Prefix used in generated backup archive names |
| backup.includeLogs | boolean | true | Include the logs directory in backup archives when it exists |
| backup.resources | object | - | Resources for backup containers |
| backup.podSecurityContext | object | - | Backup pod security context merged over the application podSecurityContext |
| backup.serviceAccount.create | boolean | true | Chart configuration parameter |
| backup.serviceAccount.name | string | "" | Chart configuration parameter |
| backup.serviceAccount.annotations | object | - | Chart configuration parameter |
| backup.serviceAccount.automountServiceAccountToken | boolean | true | Chart configuration parameter |
| backup.images.uploader.repository | string | docker.io/helmforge/mc | Chart configuration parameter |
| backup.images.uploader.tag | string | - | Chart configuration parameter |
| backup.images.uploader.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| backup.images.sqlite.repository | string | docker.io/library/alpine | Chart configuration parameter |
| backup.images.sqlite.tag | string | - | Chart configuration parameter |
| backup.images.sqlite.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| backup.s3.endpoint | string | "" | S3-compatible endpoint URL |
| backup.s3.bucket | string | "" | Target bucket name |
| backup.s3.prefix | string | komga | Optional key prefix inside the bucket |
| backup.s3.region | string | "" | AWS region used by ambient workload identity credentials |
| backup.s3.credentialsFromPodIdentity | boolean | false | Use ambient workload identity instead of static S3 credentials |
| backup.s3.createBucketIfNotExists | boolean | true | Create the bucket automatically when it does not exist |
| backup.s3.existingSecret | string | "" | Existing secret containing access-key and secret-key |
| backup.s3.existingSecretAccessKeyKey | string | access-key | Key in the existing secret for the access key |
| backup.s3.existingSecretSecretKeyKey | string | secret-key | Key in the existing secret for the secret key |
| backup.s3.accessKey | string | "" | Inline access key |
| backup.s3.secretKey | string | "" | Inline secret key |
Gateway(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gateway.enabled | boolean | false | Create an HTTPRoute. Requires Gateway API CRDs installed. |
| gateway.annotations | object | - | Chart configuration parameter |
| gateway.parentRefs | array | - | parentRefs list pointing to your Gateway resource |
| gateway.hostnames | array | - | Chart configuration parameter |
| gateway.path | string | / | Chart configuration parameter |
| gateway.pathType | string | PathPrefix | Chart configuration parameter Allowed: PathPrefixExactRegularExpression |
External Secrets(8)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | false | Render ExternalSecret resources |
| externalSecrets.apiVersion | string | external-secrets.io/v1 | Deprecated compatibility field. ExternalSecret resources render as external-secrets.io/v1. |
| externalSecrets.refreshInterval | string | 1h | Default provider sync interval for ExternalSecret items that do not set spec.refreshInterval |
| externalSecrets.items | array | - | ExternalSecret definitions with full spec blocks |
| externalSecrets.secretStoreRef.name | string | "" | Chart configuration parameter |
| externalSecrets.secretStoreRef.kind | string | SecretStore | Chart configuration parameter Allowed: SecretStoreClusterSecretStore |
| externalSecrets.target.creationPolicy | string | Owner | Chart configuration parameter Allowed: OwnerMergeNoneOrphan |
| externalSecrets.data | array | - | Deprecated compatibility field for the legacy single ExternalSecret surface |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Additional volumes for the pod |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Additional volume mounts for the container |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Extra manifests to deploy alongside the chart |
No schema parameters match your search
Try searching for a different keyword or reset the filter.