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)
Three database backends — SQLite (default), PostgreSQL, MySQL with 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), pg_dump/mysqldump for SQL databases

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

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'
  primary:
    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

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	`"v1.61.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.).

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	`mysql.enabled: true`	MySQL subchart
4	None of the above	SQLite (default)

Parameter	Type	Default	Description
`database.mode`	string	`auto`	Database mode: `auto`, `sqlite`, `external`, `postgresql`, `mysql`.
`database.sqlite.path`	string	`/appdata/db/db.sqlite`	SQLite file path inside the data volume.
`database.external.vendor`	string	`postgres`	External DB vendor: `postgres` or `mysql`.
`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.primary.persistence.size`	string	`8Gi`	PVC size for PostgreSQL.
`mysql.enabled`	boolean	`false`	Deploy the bundled MySQL subchart.
`mysql.primary.persistence.size`	string	`8Gi`	PVC size for MySQL.

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 or MySQL, 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.

Gateway API

Use gatewayAPI.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.

gatewayAPI:
  enabled: true
  parentRefs:
    - name: shared-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - dash.example.com
  paths:
    - type: PathPrefix
      value: /

Parameter	Type	Default	Description
`gatewayAPI.enabled`	boolean	`false`	Render an HTTPRoute.
`gatewayAPI.parentRefs`	array	`[]`	Parent Gateway references.
`gatewayAPI.hostnames`	array	`[]`	HTTPRoute hostnames.
`gatewayAPI.paths`	array	`/`	HTTPRoute path matches.
`gatewayAPI.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 (tar). PostgreSQL uses pg_dump. MySQL uses mysqldump.

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`.
`backup.database.mysqlDumpArgs`	string	`--single-transaction ...`	Extra arguments for `mysqldump`.
`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.