Homarr¶

A Helm chart to deploy homarr for Kubernetes

Source Code¶

• https://github.com/homarr-labs/homarr

Requirements¶

Kubernetes: >=1.24.0-0

Dependencies¶

This chart has no dependencies.

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:

Database¶

You have multiple options for configuring the 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.

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

kubectl create secret generic db-encryption \
--from-literal=db-encryption-key='<SECRET_ENCRYPTION_KEY_SECRET_TO_CHANGE>' \
--namespace homarr

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 :

kubectl create secret generic db-encryption \
--from-literal=db-encryption-key='<SECRET_ENCRYPTION_KEY_SECRET_TO_CHANGE>' \
--namespace homarr

Bellow an example of the override value file :

persistence:
  homarrDatabase:
    enabled: true
    storageClassName: "default"
    size: "1Gi"

External MySql database¶

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

kubectl create secret generic db-encryption \
--from-literal=db-encryption-key='<SECRET_ENCRYPTION_KEY_SECRET_TO_CHANGE>' \
--namespace homarr

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:

database:
  type: mysql

External Postgresql database¶

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

kubectl create secret generic db-encryption \
--from-literal=db-encryption-key='<SECRET_ENCRYPTION_KEY_SECRET_TO_CHANGE>' \
--namespace homarr

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

Below is an example of the override values file:

database:
  type: postgresql

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.

service:
  enabled: true # Ensure the service is enabled for Ingress to route traffic
ingress:
  enabled: true
  ingressClassName: "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

HTTPRoute (Gateway API)¶

The httproute section in the values.yaml file allows you to configure how external traffic accesses your application using the Kubernetes Gateway API. This provides a more expressive and future-proof alternative to Ingress, with support for advanced routing, filters, and multiple parent Gateways.

service:
  enabled: true  # must be enabled for HTTPRoute to forward traffic
httproute:
  enabled: true
  parentRefs:
    - name: my-gateway
      namespace: default
  hostnames:
    - homarr.homelab.dev
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: homarr
          port: 7575

Notes:¶

• parentRefs: the Gateway(s) this route attaches to. Gateways must already exist.
• hostnames: domain names this route applies to.
• rules: each rule can define matches (paths, headers, queries), optional filters, and backendRefs to services
• TLS must be configured on the Gateway (not on HTTPRoute). For example, the Gateway can have a TLS listener for homarr.homelab.dev, and this route will automatically apply once matched.

Certificates¶

Configuration for trusted certificate persistence. Supports:

• Declarative config via configmap or secret
• Pre-existing secret with existingSecret

type: configmap¶

Use inline certificates to generate a ConfigMap, mounted as individual files.

persistence:
  homarrTrustedCerts:
    enabled: true
    type: configmap
    certificates:
      cert1.crt: |
        -----BEGIN CERTIFICATE-----
        MIID...ABCD==
        -----END CERTIFICATE-----
      cert2.crt: |
        -----BEGIN CERTIFICATE-----
        MIID...EFGH==
        -----END CERTIFICATE-----

Behavior:

• Helm creates a ConfigMap with keys cert1.crt and cert2.crt
• Mounts them as /appdata/trusted-certificates/cert1.crt and /appdata/trusted-certificates/cert2.crt

type: secret¶

Use inline certificates to generate a Kubernetes Secret, mounted as files.

persistence:
  homarrTrustedCerts:
    enabled: true
    type: secret
    certificates:
      cert1.crt: |
        -----BEGIN CERTIFICATE-----
        MIIC...XYZ==
        -----END CERTIFICATE-----
      cart2.crt: |
        -----BEGIN CERTIFICATE-----
        MIIC...XYZ==
        -----END CERTIFICATE-----

Behavior:

• Helm creates a Kubernetes Secret with cert1.crt and cart2.crt keys
• Mounts it into the container

type: existingSecret¶

Use an existing Kubernetes Secret, assuming its keys are filenames.

persistence:
  homarrTrustedCerts:
    enabled: true
    type: existingSecret
    existingSecretName: "existingSecretName"
    existingSecretKeys:
        - cert3.crt
        - cert4.crt

Behavior:

• No new Secret is created
• Uses existingSecretName directly
• Mounts all keys as files in /appdata/trusted-certificates

Summary Table¶

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

Values¶

Autogenerated from chart metadata using helm-docs