Helm
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​
Repository | Name | Version |
---|---|---|
https://charts.bitnami.com/bitnami | mysql | 11.1.17 |
Installing the Chart​
To install the chart with the release name homarr
OCI (Recommended)​
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:
FEATURE | SECRET NAME | SECRET KEYS | Required |
---|---|---|---|
NEXT AUTH | auth-credentials-secret | auth-secret | Yes |
OIDC | auth-oidc-secret | oidc-client-id oidc-client-secret | No |
LDAP | auth-ldap-secret | bind-password | No |
DATABASE | db-secret | db-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 TYPE | Persistence mode |
---|---|
better-sqlite3 | Pod disk |
better-sqlite3 | homarr-database PVC |
mysql2 | MySql database chart dependency |
mysql2 | External 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​
Key | Type | Default | Description |
---|---|---|---|
affinity | object | {} | Node affinity for pod scheduling |
autoscaling.enabled | bool | false | Enable autoscaling |
autoscaling.maxReplicas | int | 100 | Maximum replicas |
autoscaling.minReplicas | int | 1 | Minimum replicas |
autoscaling.targetCPUUtilizationPercentage | int | 80 | Target CPU utilization for autoscaling |
containerPorts | object | {"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.externalDatabaseEnabled | bool | false | Enable external database |
database.migrationEnabled | bool | true | Database migration configuration. DB_MIGRATIONS_DISABLED Set to true to disable database migrations. Migrations are enabled by default (false ). |
env.AUTH_LDAP_ADMIN_GROUP | string | "admin" | Admin group |
env.AUTH_LDAP_BASE | string | nil | Base dn of your LDAP server |
env.AUTH_LDAP_BIND_DN | string | nil | User used for finding users and groups |
env.AUTH_LDAP_GROUP_CLASS | string | "groupOfUniqueNames" | Class used for querying groups |
env.AUTH_LDAP_GROUP_MEMBER_ATTRIBUTE | string | "member" | Attribute used for querying group member |
env.AUTH_LDAP_GROUP_MEMBER_USER_ATTRIBUTE | string | "dn" | User attribute used for comparing with group member |
env.AUTH_LDAP_OWNER_GROUP | string | "admin" | Owner group |
env.AUTH_LDAP_SEARCH_SCOPE | string | "base" | LDAP search scope between base, one or sub |
env.AUTH_LDAP_URI | string | nil | URI of your LDAP server |
env.AUTH_LDAP_USERNAME_ATTRIBUTE | string | "uid" | Attribute used for username |
env.AUTH_OIDC_ADMIN_GROUP | string | "admin" | Admin group |
env.AUTH_OIDC_CLIENT_NAME | string | "OIDC" | Display name of provider (in login screen) |
env.AUTH_OIDC_OWNER_GROUP | string | "admin" | Owner group |
env.AUTH_OIDC_SCOPE_OVERWRITE | string | "openid email profile groups" | Override the OIDC scopes |
env.AUTH_OIDC_URI | string | nil | URI of OIDC provider |
env.AUTH_PROVIDERS | string | "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_SCHEME | string | "dark" | Colors and preferences, possible values dark / light |
env.TZ | string | "Europe/Paris" | Your local time zone |
envSecrets.authCredentials.authSecret | string | "auth-secret" | Next Auth secret key |
envSecrets.authCredentials.existingSecret | string | "auth-credentials-secret" | Name of existing secret containing Next Auth secret |
envSecrets.authLdapCredentials.existingSecret | string | "auth-ldap-secret" | Name of existing secret containing LDAP credentials |
envSecrets.authLdapCredentials.ldapBindingPassword | string | "bind-password" | Password for bind user secret key |
envSecrets.authOidcCredentials.existingSecret | string | "auth-oidc-secret" | Name of existing secret containing OIDC credentials |
envSecrets.authOidcCredentials.oidcClientId | string | "oidc-client-id" | ID of OIDC client (application) secret key |
envSecrets.authOidcCredentials.oidcClientSecret | string | "oidc-client-secret" | Secret of OIDC client (application) secret key |
envSecrets.dbCredentials.dbPasswordKey | string | "mysql-root-password" | Secret key for DB_PASSWORD |
envSecrets.dbCredentials.dbUrlKey | string | "db-url" | Secret key for DB_URL Example for internal database: mysql://username:password@homarr-mysql:3306/homarrdb |
envSecrets.dbCredentials.dbUserPasswordKey | string | "mysql-password" | Secret key for database user |
envSecrets.dbCredentials.existingSecret | string | "db-secret" | Name of existing secret containing DB credentials |
fullnameOverride | string | "" | Overrides chart's fullname |
image.pullPolicy | string | "IfNotPresent" | Image pull policy |
image.repository | string | "ghcr.io/homarr-labs/homarr" | Image repository |
image.tag | string | "early-adopters" | Overrides the image tag whose default is the chart appVersion |
imagePullSecrets | list | [] | Secrets for Docker registry |
imagesCopy.enabled | bool | false | Set to true to enable the init container for copying local images to the PVC. Requires homarr-images PVC to be enabled. |
imagesCopy.pathToLocalImages | string | "/path-to-local-images" | The path where local images are stored for copying to the PVC |
ingress.annotations | object | {} | Ingress annotations |
ingress.enabled | bool | false | Enable ingress |
ingress.hosts | list | [{"host":"chart-example.local","paths":[{"path":"/"}]}] | Ingress hosts configuration |
ingress.ingressClassName | string | "" | Ingress class name |
ingress.tls | list | [] | Ingress TLS configuration |
livenessProbe.httpGet.path | string | "/api/health/live" | This is the liveness check endpoint used by Kubernetes to determine if the application is still running. |
livenessProbe.httpGet.port | int | 7575 | The port on which the liveness check will be performed. This must be the same as the container port exposed by the application. |
mysql | object | See values.yaml | Enable and configure Mysql database subchart under this key. For more options see Mysql chart documentation |
nameOverride | string | "" | Overrides chart's name |
nodeSelector | object | {} | Node selectors for pod scheduling |
persistence.homarrDatabase.accessMode | string | "ReadWriteOnce" | homarr-database access mode |
persistence.homarrDatabase.enabled | bool | false | Enable homarr-database persistent storage |
persistence.homarrDatabase.mountPath | string | "/appdata/db" | homarr-database mount path inside the pod |
persistence.homarrDatabase.name | string | "homarr-database" | homarr-database persistent storage name |
persistence.homarrDatabase.size | string | "50Mi" | homarr-database storage size |
persistence.homarrDatabase.storageClassName | string | "local-path" | homarr-database storage class name |
persistence.homarrImages.accessMode | string | "ReadWriteOnce" | homarr-images access mode |
persistence.homarrImages.enabled | bool | false | Enable homarr-images persistent storage |
persistence.homarrImages.mountPath | string | "/images" | homarr-images mount path inside the pod |
persistence.homarrImages.name | string | "homarr-images" | homarr-images persistent storage name |
persistence.homarrImages.size | string | "50Mi" | homarr-images storage size |
persistence.homarrImages.storageClassName | string | "local-path" | homarr-images storage class name |
podAnnotations | object | {} | Pod annotations |
podLabels | object | {} | Pod labels |
podSecurityContext | object | {} | Pod security context |
readinessProbe.httpGet.path | string | "/api/health/ready" | This is the readiness check endpoint used by Kubernetes to determine if the application is ready to handle traffic. |
readinessProbe.httpGet.port | int | 7575 | The port on which the readiness check will be performed. This must match the container's exposed port. |
replicaCount | int | 1 | Number of replicas |
resources | object | {} | Resource configuration |
securityContext | object | {} | Security context |
service.enabled | bool | false | Enable service |
service.ports.app.port | int | 7575 | Service port |
service.ports.app.protocol | string | "TCP" | Service protocol |
service.ports.app.targetPort | string | "http" | Service target port |
service.type | string | "ClusterIP" | Service type |
tolerations | list | [] | Node tolerations for pod scheduling |
Autogenerated from chart metadata using helm-docs