Skip to content

Homarr

Deploy Homarr on Kubernetes — a modern application dashboard with real-time status monitoring, Docker/Kubernetes integration, and a drag-and-drop widget editor. Connects to media servers (Plex, Jellyfin), *arr apps (Sonarr, Radarr), and many other services.

encryption.existingSecret protects all integration credentials — losing the key invalidates every integration

Homarr uses SECRET_ENCRYPTION_KEY to encrypt the API keys and passwords stored for every dashboard integration (Plex, Sonarr, Radarr, etc.). Without encryption.existingSecret, a reinstall generates a new key and permanently invalidates all saved integration credentials. Always provide a stable encryption.existingSecret before the first deployment.

Key Features

  • Embedded Redis — no separate Redis required (external Redis optional for multi-instance)
  • Supported database backends — SQLite (default) or PostgreSQL with deterministic auto-detection
  • Integration encryption — all service credentials encrypted via SECRET_ENCRYPTION_KEY
  • Kubernetes workload discovery — optional live workload status in the dashboard
  • Auth providers — local credentials, LDAP, and OIDC
  • Database-aware backup — tar for SQLite (/appdata) or pg_dump for PostgreSQL

Installation

HTTPS repository:

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

OCI registry:

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

Upgrade Notes

The chart defaults to Homarr v2.6.0. Back up /appdata and any external database before upgrading. Homarr v2 supports SQLite and PostgreSQL, but not MySQL. Existing MySQL installations must complete Homarr’s official MySQL-to-SQLite conversion and deploy and validate the resulting SQLite database before completing this chart upgrade. The converter does not populate PostgreSQL; switching afterward requires a separate, operator-controlled and validated migration. The chart deliberately rejects the obsolete MySQL configuration instead of starting an incompatible application image. Review the upstream v2.6.0 release before a production rollout.

Deployment Examples

# values.yaml — Homarr with SQLite (zero database configuration)
homarr:
  authProviders: credentials
  logLevel: info

encryption:
  existingSecret: homarr-encryption-key # key: secret-encryption-key
  existingSecretKey: secret-encryption-key # Generate: openssl rand -hex 32

persistence:
  enabled: true
  size: 1Gi

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: dash.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: homarr-tls
      hosts:
        - dash.example.com
# values.yaml — Homarr with bundled PostgreSQL
homarr:
  authProviders: credentials

encryption:
  existingSecret: homarr-encryption-key

postgresql:
  enabled: true
  auth:
    database: homarr
    username: homarr
    password: 'strong-db-password'
  standalone:
    persistence:
      enabled: true
      size: 10Gi

persistence:
  enabled: true
  size: 1Gi

backup:
  enabled: true
  schedule: '0 3 * * *'
  s3:
    endpoint: https://s3.amazonaws.com
    bucket: homarr-backups
    existingSecret: homarr-s3-credentials

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: dash.example.com
      paths:
        - path: /
          pathType: Prefix
# values.yaml — Homarr with Kubernetes workload discovery enabled
# Requires cluster RBAC access; configure serviceAccount if needed
homarr:
  enableKubernetes: true # live workload status in the dashboard
  authProviders: credentials

serviceAccount:
  automountServiceAccountToken: true

encryption:
  existingSecret: homarr-encryption-key

persistence:
  enabled: true
  size: 1Gi

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: dash.example.com
      paths:
        - path: /
          pathType: Prefix
# values.yaml — Homarr with OIDC authentication (e.g. Keycloak, Authelia)
homarr:
  authProviders: oidc # or: credentials,oidc for both
  extraEnv:
    - name: AUTH_OIDC_ISSUER
      value: 'https://auth.example.com/realms/myrealm'
    - name: AUTH_OIDC_CLIENT_ID
      value: homarr
    - name: AUTH_OIDC_CLIENT_SECRET
      valueFrom:
        secretKeyRef:
          name: homarr-oidc-credentials
          key: client-secret
    - name: AUTH_OIDC_CALLBACK_URL
      value: 'https://dash.example.com/api/auth/callback/oidc'

encryption:
  existingSecret: homarr-encryption-key

persistence:
  enabled: true
  size: 1Gi

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

Configuration Reference

Core

Parameter Type Default Description
replicaCount integer 1 Pod replicas. SQLite supports 1 only.
nameOverride string "" Override the chart name.
fullnameOverride string "" Override the full release name.

Image

Parameter Type Default Description
image.repository string ghcr.io/homarr-labs/homarr Homarr image.
image.tag string "v2.6.0" Image tag.
image.pullPolicy string IfNotPresent Image pull policy.

Homarr Configuration

Parameter Type Default Description
homarr.logLevel string info Log level: trace, debug, info, warn, error, fatal.
homarr.authProviders string credentials Auth providers (comma-separated): credentials, ldap, oidc.
homarr.enableKubernetes boolean false Enable Kubernetes workload discovery (requires cluster RBAC).
homarr.extraEnv array [] Extra environment variables (OIDC settings, custom certs, etc.).

Kubernetes discovery also requires serviceAccount.automountServiceAccountToken=true and deliberately scoped RBAC.

Encryption Key

Parameter Type Default Description
encryption.key string "" 32-byte hex encryption key. Auto-generated if empty.
encryption.existingSecret string "" Existing secret with the encryption key.
encryption.existingSecretKey string secret-encryption-key Key for the encryption key in the existing secret.

Database

Auto-detection precedence (database.mode: auto):

Priority Condition Result
1 database.external.host or external.existingSecret External DB
2 postgresql.enabled: true PostgreSQL subchart
3 None of the above SQLite (default)
Parameter Type Default Description
database.mode string auto Database mode: auto, sqlite, external, or postgresql.
database.sqlite.path string /appdata/db/db.sqlite SQLite file path inside the data volume.
database.external.vendor string postgres External database vendor. Homarr v2 supports postgres.
database.external.host string "" External database hostname.
database.external.existingSecret string "" Existing secret with database password.

Subcharts

Parameter Type Default Description
postgresql.enabled boolean false Deploy the bundled PostgreSQL subchart.
postgresql.auth.password string "" Password. Auto-generated if empty.
postgresql.auth.existingSecret string "" Existing PostgreSQL password Secret.
postgresql.auth.existingSecretUserPasswordKey string user-password Application password key.
postgresql.standalone.persistence.size string 8Gi PVC size for PostgreSQL.

Redis

Homarr includes embedded Redis — no external Redis required for single-instance deployments

Homarr ships with an embedded Redis process. External Redis is only needed if you are running multiple Homarr replicas sharing a common cache (requires PostgreSQL, not SQLite).

Parameter Type Default Description
redis.external boolean false Use an external Redis instead of the embedded one.
redis.host string "" External Redis hostname.
redis.port integer 6379 External Redis port.
redis.existingSecret string "" Existing secret with external Redis password.
redis.existingSecretKey string redis-password Key for the password in the existing secret.

Persistence

Parameter Type Default Description
persistence.enabled boolean true Enable PVC for /appdata (SQLite DB + dashboard config + themes).
persistence.size string 1Gi PVC size.
persistence.storageClass string "" StorageClass for the PVC.
persistence.existingClaim string "" Use an existing PVC.

Service and Ingress

Parameter Type Default Description
service.type string ClusterIP Service type.
service.port integer 7575 Service port (non-standard).
service.ipFamilyPolicy string null Service IP family policy.
service.ipFamilies array [] Ordered Service IP families.
ingress.enabled boolean false Enable an Ingress resource.
ingress.ingressClassName string "" Ingress class name.
ingress.annotations object {} Ingress annotations.
ingress.hosts array [] Host and path rules.
ingress.tls array [] TLS configuration.

The official Homarr image listens on fixed container port 7575. service.port may expose a different Kubernetes Service port, but the named target port continues to route to that fixed application listener.

Health Probes and ServiceAccount

Parameter Type Default Description
startupProbe.path string /api/health/ready Startup health endpoint.
livenessProbe.path string /api/health/live Liveness health endpoint.
readinessProbe.path string /api/health/ready Readiness health endpoint.
serviceAccount.create boolean false Create a dedicated ServiceAccount.
serviceAccount.automountServiceAccountToken boolean false Mount an API token for scoped workload discovery.

Gateway API

Use gateway.enabled to render a native Kubernetes Gateway API HTTPRoute for Homarr. Ingress stays disabled by default and can coexist with the route when a migration needs both objects.

gateway:
  enabled: true
  parentRefs:
    - name: shared-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - dash.example.com
  path: /
  pathType: PathPrefix
Parameter Type Default Description
gateway.enabled boolean false Render an HTTPRoute.
gateway.parentRefs array [] Parent Gateway references.
gateway.hostnames array [] HTTPRoute hostnames.
gateway.path string / HTTPRoute path match.
gateway.pathType string PathPrefix HTTPRoute path type.
gateway.annotations object {} HTTPRoute annotations.

Dual-Stack Networking

Homarr’s Service supports Kubernetes dual-stack networking through optional service.ipFamilyPolicy and service.ipFamilies values. Defaults omit both fields so existing installs inherit cluster defaults.

service:
  ipFamilyPolicy: PreferDualStack

Backup

Database-aware backup: SQLite archives the full /appdata directory with tar. PostgreSQL uses pg_dump.

Parameter Type Default Description
backup.enabled boolean false Enable scheduled S3 backup CronJob.
backup.schedule string "0 3 * * *" Cron schedule.
backup.archivePrefix string homarr Prefix for backup archive filenames.
backup.s3.endpoint string "" S3-compatible endpoint URL.
backup.s3.bucket string "" Target bucket name.
backup.s3.existingSecret string "" Existing secret with S3 credentials.
backup.database.postgresDumpArgs string "" Extra arguments for pg_dump.
extraManifests array [] Extra Kubernetes manifests.

External Secrets

Homarr can render an External Secrets Operator ExternalSecret that projects SECRET_ENCRYPTION_KEY and AUTH_SECRET into the Kubernetes Secret configured by encryption.existingSecret.

encryption:
  existingSecret: homarr-encryption

externalSecrets:
  enabled: true
  secretStoreRef:
    name: platform-secrets
    kind: ClusterSecretStore
  data:
    - secretKey: secret-encryption-key
      remoteRef:
        key: homarr/credentials
        property: secret-encryption-key
    - secretKey: auth-secret
      remoteRef:
        key: homarr/credentials
        property: auth-secret
Parameter Type Default Description
externalSecrets.enabled boolean false Render an ExternalSecret.
externalSecrets.secretStoreRef.name string "" SecretStore or ClusterSecretStore.
externalSecrets.secretStoreRef.kind string SecretStore Secret store kind.
externalSecrets.refreshInterval string "0" ExternalSecret refresh interval.
externalSecrets.data array [] Remote key mappings for Secret data.

More Information

Edit this page on GitHub