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/heimdallcontainer - Persistent Storage — SQLite database and settings stored in
/config - S3-Compatible Backup — CronJob that creates a tar archive of
/configand 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
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.
S3 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.
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.
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.
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.
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
Recreatestrategy to avoid SQLite locking issues during upgrades - backup creates a tar archive of the entire
/configdirectory including the SQLite database - for file permission issues, adjust
heimdall.puidandheimdall.pgidto match your storage
More Information
System Architecture
DESIGN.md SyncedVerified 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
Heimdall 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 a parent chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | - | Override the chart name |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | - | Override the full release name |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels to add to all resources |
Common Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonAnnotations | object | - | Annotations to add to all chart-owned resources |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | - | Container image repository |
| image.tag | string | - | Pinned image tag |
| image.pullPolicy | string | - | Image pull policy Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Image pull secrets |
Heimdall(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| heimdall.containerPort | integer | - | HTTP port used by the Heimdall NGINX process; port 443 is reserved by the image TLS listener |
| heimdall.puid | integer | - | User ID for file permissions |
| heimdall.pgid | integer | - | Group ID for file permissions |
| heimdall.timezone | string | - | Timezone |
| heimdall.extraEnv | array | - | Extra environment variables |
Persistence(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | - | Enable persistent storage |
| persistence.storageClass | string | - | Storage class |
| persistence.accessMode | string | - | Access mode Allowed: ReadWriteOnceReadOnlyManyReadWriteManyReadWriteOncePod |
| persistence.size | string | - | Volume size |
| persistence.existingClaim | string | - | Use an existing PVC |
| persistence.annotations | object | - | PVC annotations |
Backup(26)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | - | Enable S3 backup CronJob |
| backup.schedule | string | - | Cron schedule |
| backup.suspend | boolean | - | Suspend the CronJob |
| backup.concurrencyPolicy | string | - | Concurrency policy Allowed: AllowForbidReplace |
| backup.successfulJobsHistoryLimit | integer | - | Successful job history limit |
| backup.failedJobsHistoryLimit | integer | - | Failed job history limit |
| backup.backoffLimit | integer | - | Backoff limit |
| backup.archivePrefix | string | - | Archive filename prefix |
| backup.images.archiver | string | - | Pinned image used to create archives |
| backup.images.uploader | string | - | Pinned image used to upload archives |
| backup.resources | object | - | Backup job resources |
| backup.serviceAccount.create | boolean | - | Create a dedicated backup ServiceAccount |
| backup.serviceAccount.name | string | - | Backup ServiceAccount name |
| backup.serviceAccount.annotations | object | - | Backup ServiceAccount annotations |
| backup.serviceAccount.automountServiceAccountToken | boolean | - | Mount the projected ServiceAccount token |
| backup.s3.endpoint | string | - | S3-compatible endpoint URL |
| backup.s3.bucket | string | - | S3 bucket name |
| backup.s3.prefix | string | - | S3 key prefix |
| backup.s3.region | string | - | AWS region used by ambient workload identity credentials |
| backup.s3.credentialsFromPodIdentity | boolean | - | Use ambient workload identity instead of static credentials |
| backup.s3.createBucketIfNotExists | boolean | - | Create bucket if it does not exist |
| backup.s3.existingSecret | string | - | Existing Secret with S3 credentials |
| backup.s3.existingSecretAccessKeyKey | string | - | Key for the access key |
| backup.s3.existingSecretSecretKeyKey | string | - | Key for the secret key |
| backup.s3.accessKey | string | - | Inline S3 access key for testing |
| backup.s3.secretKey | string | - | Inline S3 secret key for testing |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | Resource requests and limits |
Pod Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext | object | - | Pod security context |
Container Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext | object | - | Container security context |
Startup Probe(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| startupProbe.enabled | boolean | - | Enable the startup probe |
| startupProbe.path | string | - | HTTP request path |
| startupProbe.initialDelaySeconds | integer | - | Initial delay |
| startupProbe.periodSeconds | integer | - | Probe period |
| startupProbe.timeoutSeconds | integer | - | Probe timeout |
| startupProbe.failureThreshold | integer | - | Failure threshold |
Liveness Probe(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| livenessProbe.enabled | boolean | - | Enable the liveness probe |
| livenessProbe.path | string | - | HTTP request path |
| livenessProbe.initialDelaySeconds | integer | - | Initial delay |
| livenessProbe.periodSeconds | integer | - | Probe period |
| livenessProbe.timeoutSeconds | integer | - | Probe timeout |
| livenessProbe.failureThreshold | integer | - | Failure threshold |
Readiness Probe(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| readinessProbe.enabled | boolean | - | Enable the readiness probe |
| readinessProbe.path | string | - | HTTP request path |
| readinessProbe.initialDelaySeconds | integer | - | Initial delay |
| readinessProbe.periodSeconds | integer | - | Probe period |
| readinessProbe.timeoutSeconds | integer | - | Probe timeout |
| readinessProbe.failureThreshold | integer | - | Failure threshold |
Service & Networking(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | - | Service type Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | - | Service port |
| service.annotations | object | - | Service annotations |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | - | Enable ingress |
| ingress.ingressClassName | string | - | Ingress class name |
| ingress.annotations | object | - | Ingress annotations |
| ingress.hosts | array | - | Ingress hosts |
| ingress.tls | array | - | TLS configuration |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | - | Create a ServiceAccount |
| serviceAccount.name | string | - | ServiceAccount name |
| serviceAccount.annotations | object | - | ServiceAccount annotations |
| serviceAccount.automountServiceAccountToken | boolean | - | Mount the Kubernetes API token |
Network Policy(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | - | Create the server NetworkPolicy |
| networkPolicy.extraIngress | array | - | Additional ingress rules |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Node selector |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Tolerations |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Affinity rules |
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 | - | Termination grace period |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Additional pod labels |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Additional pod annotations |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Extra volume mounts |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Extra volumes |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Extra Kubernetes manifests |
No schema parameters match your search
Try searching for a different keyword or reset the filter.