Skip to content
Heimdall icon
v1.2.1App: v2.8.3Pinned DigestS3 Backup Ready

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

Heimdall

A Helm chart for deploying Heimdall application dashboard on Kubernetes using the linuxserver/heimdall Docker image.

Installation

HTTPS Repository

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

OCI Registry

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

Features

  • LinuxServer.io Image — based on the maintained linuxserver/heimdall container
  • Persistent Storage — SQLite database and settings stored in /config
  • S3-Compatible Backup — CronJob that creates a tar archive of /config and uploads to any S3 endpoint
  • Workload Identity — S3 backups can use ambient cloud credentials through a dedicated ServiceAccount
  • Ingress Support — configurable ingress with TLS for HTTPS access
  • PUID/PGID — file ownership control for the container
  • Hardened Defaults — no API token, restricted capabilities, seccomp, and ingress NetworkPolicy

Documentation

Security Scan: heimdall

Framework Score
MITRE + NSA + SOC2 72.73%

Security posture acceptable with operator-provided resource limits, security contexts, and network policy.

Configuration

Set a non-empty image.repository and image.tag; the chart rejects empty values before creating a workload.

heimdall.containerPort configures the real NGINX listener. It is independent from service.port, which controls only the Kubernetes Service port.

Use commonAnnotations to apply annotations to every chart-owned resource. Resource-specific annotations take precedence when the same key is configured.

Examples

Minimal

# Just install — defaults work out of the box

Production with Ingress and Backup

heimdall:
  timezone: "America/New_York"

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

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

Parameters

Heimdall Settings

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

S3 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

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

Security

The chart disables Kubernetes API token automount, applies RuntimeDefault seccomp, disables privilege escalation, minimizes Linux capabilities, and creates an ingress NetworkPolicy by default. The main process still starts as root because the LinuxServer /init sequence must prepare /config before switching to PUID/PGID; see the Security Guide for the documented exception and network boundaries.

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

Probes and Scheduling

Startup, readiness, and liveness probes use the named http port and expose path, delay, period, timeout, and failure threshold settings in values.yaml. Resources, scheduling, labels, annotations, extra volumes, mounts, manifests, and image pull secrets remain fully operator-configurable. The complete values contract is documented inline in values.yaml and enforced by values.schema.json.

Architecture

One Deployment runs LinuxServer's NGINX, PHP-FPM, and Heimdall processes. A single persistent /config volume contains SQLite data, settings, and assets; the Deployment therefore uses Recreate and intentionally does not expose a replica setting. The optional backup CronJob archives that same volume to S3. See Chart Design for boundaries and tradeoffs.

Troubleshooting

Inspect readiness, logs, events, and the effective NGINX listener:

kubectl get pods -l app.kubernetes.io/instance=<release>
kubectl logs -l app.kubernetes.io/instance=<release> --all-containers --tail=100
kubectl get events --sort-by=.lastTimestamp
kubectl exec deploy/<release>-heimdall -c heimdall -- grep 'listen .* default_server' /config/nginx/site-confs/default.conf

Write failures under /config usually mean heimdall.puid or heimdall.pgid does not match the volume's ownership. Connection failures on a custom listener should be checked against both heimdall.containerPort and service.port.

Notes

  • Heimdall uses SQLite internally — only a single replica is supported
  • the deployment uses Recreate strategy to avoid SQLite locking issues during upgrades
  • backup creates a tar archive of the entire /config directory including the SQLite database
  • for file permission issues, adjust heimdall.puid and heimdall.pgid to match your storage

More Information

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  Client[Dashboard user] --> Ingress[Optional Ingress]
  Ingress --> Service[Heimdall Service]
  Service --> App[Heimdall Deployment]
  App --> Config[(Config PVC)]
  Backup[Backup CronJob] --> Config
  Backup --> S3[S3-compatible storage]
  Identity[Dedicated backup ServiceAccount] -. workload identity .-> Backup
  Secret[Optional static credential Secret] -. static mode .-> Backup
Official Contractvalues.schema.json

Heimdall Values Schema Reference

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

92 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by a parent chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Override the chart name

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Override the full release name

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels to add to all resources

Common Annotations(1)

ParameterTypeDefaultDescription
commonAnnotationsobject-Annotations to add to all chart-owned resources

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Container image repository
image.tagstring-Pinned image tag
image.pullPolicystring-Image pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets

Heimdall(5)

ParameterTypeDefaultDescription
heimdall.containerPortinteger-HTTP port used by the Heimdall NGINX process; port 443 is reserved by the image TLS listener
heimdall.puidinteger-User ID for file permissions
heimdall.pgidinteger-Group ID for file permissions
heimdall.timezonestring-Timezone
heimdall.extraEnvarray-Extra environment variables

Persistence(6)

ParameterTypeDefaultDescription
persistence.enabledboolean-Enable persistent storage
persistence.storageClassstring-Storage class
persistence.accessModestring-Access mode
Allowed:ReadWriteOnceReadOnlyManyReadWriteManyReadWriteOncePod
persistence.sizestring-Volume size
persistence.existingClaimstring-Use an existing PVC
persistence.annotationsobject-PVC annotations

Backup(26)

ParameterTypeDefaultDescription
backup.enabledboolean-Enable S3 backup CronJob
backup.schedulestring-Cron schedule
backup.suspendboolean-Suspend the CronJob
backup.concurrencyPolicystring-Concurrency policy
Allowed:AllowForbidReplace
backup.successfulJobsHistoryLimitinteger-Successful job history limit
backup.failedJobsHistoryLimitinteger-Failed job history limit
backup.backoffLimitinteger-Backoff limit
backup.archivePrefixstring-Archive filename prefix
backup.images.archiverstring-Pinned image used to create archives
backup.images.uploaderstring-Pinned image used to upload archives
backup.resourcesobject-Backup job resources
backup.serviceAccount.createboolean-Create a dedicated backup ServiceAccount
backup.serviceAccount.namestring-Backup ServiceAccount name
backup.serviceAccount.annotationsobject-Backup ServiceAccount annotations
backup.serviceAccount.automountServiceAccountTokenboolean-Mount the projected ServiceAccount token
backup.s3.endpointstring-S3-compatible endpoint URL
backup.s3.bucketstring-S3 bucket name
backup.s3.prefixstring-S3 key prefix
backup.s3.regionstring-AWS region used by ambient workload identity credentials
backup.s3.credentialsFromPodIdentityboolean-Use ambient workload identity instead of static credentials
backup.s3.createBucketIfNotExistsboolean-Create bucket if it does not exist
backup.s3.existingSecretstring-Existing Secret with S3 credentials
backup.s3.existingSecretAccessKeyKeystring-Key for the access key
backup.s3.existingSecretSecretKeyKeystring-Key for the secret key
backup.s3.accessKeystring-Inline S3 access key for testing
backup.s3.secretKeystring-Inline S3 secret key for testing

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-Resource requests and limits

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContextobject-Pod security context

Container Security(1)

ParameterTypeDefaultDescription
securityContextobject-Container security context

Startup Probe(6)

ParameterTypeDefaultDescription
startupProbe.enabledboolean-Enable the startup probe
startupProbe.pathstring-HTTP request path
startupProbe.initialDelaySecondsinteger-Initial delay
startupProbe.periodSecondsinteger-Probe period
startupProbe.timeoutSecondsinteger-Probe timeout
startupProbe.failureThresholdinteger-Failure threshold

Liveness Probe(6)

ParameterTypeDefaultDescription
livenessProbe.enabledboolean-Enable the liveness probe
livenessProbe.pathstring-HTTP request path
livenessProbe.initialDelaySecondsinteger-Initial delay
livenessProbe.periodSecondsinteger-Probe period
livenessProbe.timeoutSecondsinteger-Probe timeout
livenessProbe.failureThresholdinteger-Failure threshold

Readiness Probe(6)

ParameterTypeDefaultDescription
readinessProbe.enabledboolean-Enable the readiness probe
readinessProbe.pathstring-HTTP request path
readinessProbe.initialDelaySecondsinteger-Initial delay
readinessProbe.periodSecondsinteger-Probe period
readinessProbe.timeoutSecondsinteger-Probe timeout
readinessProbe.failureThresholdinteger-Failure threshold

Service & Networking(3)

ParameterTypeDefaultDescription
service.typestring-Service type
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Service port
service.annotationsobject-Service annotations

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Enable ingress
ingress.ingressClassNamestring-Ingress class name
ingress.annotationsobject-Ingress annotations
ingress.hostsarray-Ingress hosts
ingress.tlsarray-TLS configuration

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Create a ServiceAccount
serviceAccount.namestring-ServiceAccount name
serviceAccount.annotationsobject-ServiceAccount annotations
serviceAccount.automountServiceAccountTokenboolean-Mount the Kubernetes API token

Network Policy(2)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Create the server NetworkPolicy
networkPolicy.extraIngressarray-Additional ingress rules

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Topology spread constraints

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Priority class name

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Termination grace period

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Additional pod labels

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Additional pod annotations

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Extra volume mounts

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Extra volumes

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra Kubernetes manifests