Skip to main content

Helm

homarr logo

Version: 0.0.1 Type: application AppVersion: 0.0.1

A Helm chart to deploy homarr for Kubernetes

Homepage: https://homarr-labs.github.io/charts/charts/homarr/

Source Code​

Requirements​

Kubernetes: >=1.22.0-0

Dependencies​

RepositoryNameVersion
https://charts.bitnami.com/bitnamimysql11.1.17

Installing the Chart​

To install the chart with the release name homarr

helm install homarr oci://ghcr.io/homarr-labs/charts/homarr

Traditional​

helm repo add homarr-labs https://homarr-labs.github.io/charts/
helm repo update
helm install homarr homarr-labs/homarr

Uninstalling the Chart​

To uninstall the homarr deployment

helm uninstall homarr

The command removes all the Kubernetes components associated with the chart including persistent volumes and deletes the release.

Configuration​

Read through the values.yaml file. It has several commented out suggested values.

Specify each parameter using the --set key=value[,key=value] argument to helm install.

helm install homarr \
--set env.TZ="America/New York" \
homarr-labs/homarr

Alternatively, a YAML file that specifies the values for the above parameters can be provided while installing the chart.

helm install homarr homarr-labs/homarr -f values.yaml

Custom configuration​

Secrets​

To avoid including sensitive information in plain text within your version control, consider using a declarative approach by applying secrets directly with kubectl apply. For example, instead of including repository credentials in your Helm values, you can leverage a kubernetes secrets manager.

Below is an exhaustive list of all secrets:

FEATURESECRET NAMESECRET KEYSRequired
NEXT AUTHauth-credentials-secretauth-secretYes
OIDCauth-oidc-secretoidc-client-id
oidc-client-secret
No
LDAPauth-ldap-secretbind-passwordNo
DATABASEdb-secretdb-url
mysql-root-password
mysql-password
Depends (see Database section)

Example: Creating and Applying NEXT AUTH Secret

To generate the NEXT AUTH secret, use the following command:

openssl rand -base64 32

You can apply the generated secret with:

kubectl create secret generic auth-credentials-secret \
--from-literal=auth-secret='<TO_CHANGE>' \
--namespace homarr

For further information see next-auth-secret

Database​

You have multiple options for configuring the database:

DRIVER TYPEPersistence mode
better-sqlite3Pod disk
better-sqlite3homarr-database PVC
mysql2MySql database chart dependency
mysql2External MySql database

Pod disk​

No additional configuration is required. However, keep in mind that if the pod restarts, all data will be lost. This setup is not recommended for production use.

PVC​

To persist data, you need to enable the homarr-database PVC. This will store the Homarr database on a mounted volume.

Associated secret to create :

Next Auth secret
kubectl create secret generic auth-credentials-secret \
--from-literal=auth-secret='<NEXT_AUTH_SECRET_TO_CHANGE>' \
--namespace homarr

Bellow an example of the override value file :

values.yaml
persistence:
homarrDatabase:
enabled: true
storageClassName: "default"
size: "1Gi"

MySql database chart dependency​

We are using mysql bitnami chart as a dependency for data persistence. For additional configuration options, refer to the Mysql chart documentation

To create the necessary database secrets, execute the following command:

Required Secrets
kubectl create secret generic db-secret \
--from-literal=db-url='mysql://homarr:your-db-password1@homarr-mysql:3306/homarrdb' \
--from-literal=mysql-root-password='your-db-password1' \
--from-literal=mysql-password='your-db-password2' \
--namespace homarr

if the key mysql.auth.usersame has been modified, please update the db-url accordingly. The database host and port should remain unchanged.

Below is an example of the override values file:

values.yaml
mysql:
internal: true

External MySql database​

The chart offer the possibility to use an external database.

To create the necessary database secrets, execute the following command:

Required Secrets
kubectl create secret generic db-secret \
--from-literal=db-url='mysql://user:password@host:port/homarrdb' \
--namespace homarr

Below is an example of the override values file:

values.yaml
database:
externalDatabaseEnabled: true

Images​

You can import your local images into homarr-images PVC

values.yaml
persistence:
homarrImages:
enabled: true

imagesCopy:
enabled: true
pathToLocalImages: "/path-to-local-images"

Ingress​

The ingress section in the values.yaml file allows you to configure how external traffic accesses your application through an Ingress resource. This section defines whether Ingress is enabled, the class to use, and how to set up hosts, paths, and TLS for secure connections.

values.yaml
service:
enabled: true # Ensure the service is enabled for Ingress to route traffic
ingress:
enabled: true
className: "traefik"
annotations:
# Add any additional annotations as needed
hosts:
- host: homarr.homelab.dev
paths:
- path: /
pathType: ImplementationSpecific
tls:
- hosts:
- "homarr.homelab.dev"
- "www.homarr.homelab.dev"
secretName: homelab-tls

All available values are listed on the artifacthub. If you find any issue please open an issue on github

Values​

KeyTypeDefaultDescription
affinityobject{}Node affinity for pod scheduling
autoscaling.enabledboolfalseEnable autoscaling
autoscaling.maxReplicasint100Maximum replicas
autoscaling.minReplicasint1Minimum replicas
autoscaling.targetCPUUtilizationPercentageint80Target CPU utilization for autoscaling
containerPortsobject{"http":{"port":7575,"protocol":"TCP"}}containerPorts defines the ports to open on the container. It is a map where each entry specifies: - port (int) (required): The port number to expose inside the container. - protocol (string) (required): The network protocol (TCP or UDP) used for the port. - disabled (bool) : Optional flag to disable this port (defaults to false). Can be overridden via Helm values. By default, this configuration exposes TCP port 7575 with the name http.
database.externalDatabaseEnabledboolfalseEnable external database
database.migrationEnabledbooltrueDatabase migration configuration. DB_MIGRATIONS_DISABLED Set to true to disable database migrations. Migrations are enabled by default (false).
env.AUTH_LDAP_ADMIN_GROUPstring"admin"Admin group
env.AUTH_LDAP_BASEstringnilBase dn of your LDAP server
env.AUTH_LDAP_BIND_DNstringnilUser used for finding users and groups
env.AUTH_LDAP_GROUP_CLASSstring"groupOfUniqueNames"Class used for querying groups
env.AUTH_LDAP_GROUP_MEMBER_ATTRIBUTEstring"member"Attribute used for querying group member
env.AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTEstring"dn"User attribute used for comparing with group member
env.AUTH_LDAP_OWNER_GROUPstring"admin"Owner group
env.AUTH_LDAP_SEARCH_SCOPEstring"base"LDAP search scope between base, one or sub
env.AUTH_LDAP_URIstringnilURI of your LDAP server
env.AUTH_LDAP_USERNAME_ATTRIBUTEstring"uid"Attribute used for username
env.AUTH_OIDC_ADMIN_GROUPstring"admin"Admin group
env.AUTH_OIDC_CLIENT_NAMEstring"OIDC"Display name of provider (in login screen)
env.AUTH_OIDC_OWNER_GROUPstring"admin"Owner group
env.AUTH_OIDC_SCOPE_OVERWRITEstring"openid email profile groups"Override the OIDC scopes
env.AUTH_OIDC_URIstringnilURI of OIDC provider
env.AUTH_PROVIDERSstring"credentials"Enabled authentication methods. Multiple providers can be enabled with by separating them with , (ex. AUTH_PROVIDERS=credentials,oidc, it is highly recommended to just enable one provider).
env.DEFAULT_COLOR_SCHEMEstring"dark"Colors and preferences, possible values dark / light
env.TZstring"Europe/Paris"Your local time zone
envSecrets.authCredentials.authSecretstring"auth-secret"Next Auth secret key
envSecrets.authCredentials.existingSecretstring"auth-credentials-secret"Name of existing secret containing Next Auth secret
envSecrets.authLdapCredentials.existingSecretstring"auth-ldap-secret"Name of existing secret containing LDAP credentials
envSecrets.authLdapCredentials.ldapBindingPasswordstring"bind-password"Password for bind user secret key
envSecrets.authOidcCredentials.existingSecretstring"auth-oidc-secret"Name of existing secret containing OIDC credentials
envSecrets.authOidcCredentials.oidcClientIdstring"oidc-client-id"ID of OIDC client (application) secret key
envSecrets.authOidcCredentials.oidcClientSecretstring"oidc-client-secret"Secret of OIDC client (application) secret key
envSecrets.dbCredentials.dbPasswordKeystring"mysql-root-password"Secret key for DB_PASSWORD
envSecrets.dbCredentials.dbUrlKeystring"db-url"Secret key for DB_URL Example for internal database: mysql://username:password@homarr-mysql:3306/homarrdb
envSecrets.dbCredentials.dbUserPasswordKeystring"mysql-password"Secret key for database user
envSecrets.dbCredentials.existingSecretstring"db-secret"Name of existing secret containing DB credentials
fullnameOverridestring""Overrides chart's fullname
image.pullPolicystring"IfNotPresent"Image pull policy
image.repositorystring"ghcr.io/homarr-labs/homarr"Image repository
image.tagstring"early-adopters"Overrides the image tag whose default is the chart appVersion
imagePullSecretslist[]Secrets for Docker registry
imagesCopy.enabledboolfalseSet to true to enable the init container for copying local images to the PVC. Requires homarr-images PVC to be enabled.
imagesCopy.pathToLocalImagesstring"/path-to-local-images"The path where local images are stored for copying to the PVC
ingress.annotationsobject{}Ingress annotations
ingress.enabledboolfalseEnable ingress
ingress.hostslist[{"host":"chart-example.local","paths":[{"path":"/"}]}]Ingress hosts configuration
ingress.ingressClassNamestring""Ingress class name
ingress.tlslist[]Ingress TLS configuration
livenessProbe.httpGet.pathstring"/api/health/live"This is the liveness check endpoint used by Kubernetes to determine if the application is still running.
livenessProbe.httpGet.portint7575The port on which the liveness check will be performed. This must be the same as the container port exposed by the application.
mysqlobjectSee values.yamlEnable and configure Mysql database subchart under this key. For more options see Mysql chart documentation
nameOverridestring""Overrides chart's name
nodeSelectorobject{}Node selectors for pod scheduling
persistence.homarrDatabase.accessModestring"ReadWriteOnce"homarr-database access mode
persistence.homarrDatabase.enabledboolfalseEnable homarr-database persistent storage
persistence.homarrDatabase.mountPathstring"/appdata/db"homarr-database mount path inside the pod
persistence.homarrDatabase.namestring"homarr-database"homarr-database persistent storage name
persistence.homarrDatabase.sizestring"50Mi"homarr-database storage size
persistence.homarrDatabase.storageClassNamestring"local-path"homarr-database storage class name
persistence.homarrImages.accessModestring"ReadWriteOnce"homarr-images access mode
persistence.homarrImages.enabledboolfalseEnable homarr-images persistent storage
persistence.homarrImages.mountPathstring"/images"homarr-images mount path inside the pod
persistence.homarrImages.namestring"homarr-images"homarr-images persistent storage name
persistence.homarrImages.sizestring"50Mi"homarr-images storage size
persistence.homarrImages.storageClassNamestring"local-path"homarr-images storage class name
podAnnotationsobject{}Pod annotations
podLabelsobject{}Pod labels
podSecurityContextobject{}Pod security context
readinessProbe.httpGet.pathstring"/api/health/ready"This is the readiness check endpoint used by Kubernetes to determine if the application is ready to handle traffic.
readinessProbe.httpGet.portint7575The port on which the readiness check will be performed. This must match the container's exposed port.
replicaCountint1Number of replicas
resourcesobject{}Resource configuration
securityContextobject{}Security context
service.enabledboolfalseEnable service
service.ports.app.portint7575Service port
service.ports.app.protocolstring"TCP"Service protocol
service.ports.app.targetPortstring"http"Service target port
service.typestring"ClusterIP"Service type
tolerationslist[]Node tolerations for pod scheduling

Autogenerated from chart metadata using helm-docs