immichframe-helm/README.md

ImmichFrame Helm chart

This repository packages the upstream ImmichFrame container for Kubernetes. It is an independent community chart and is not maintained by the ImmichFrame project.

The chart creates a Deployment, ConfigMap, Service, optional Ingress, optional PVC, optional PodDisruptionBudget, and optional PrometheusRule. ImmichFrame does not currently expose a Prometheus metrics endpoint, so the chart deliberately does not create a ServiceMonitor. Its alerts use metrics supplied by kube-state-metrics.

Install

Add brunner.ninja's public chart repository and choose an immutable chart version:

helm repo add brunner.ninja https://brunner.ninja/charts
helm repo update brunner.ninja
helm upgrade --install immichframe brunner.ninja/immichframe \
  --version CHART_VERSION \
  --namespace immichframe --create-namespace \
  --values values.yaml

The chart version has no latest alias. Git tags follow the upstream ImmichFrame release (for example v1.0.39.0). Because Helm chart versions must be SemVer, the fourth upstream component becomes a prerelease component: v1.0.39.0 publishes chart 1.0.39-0; a later chart-only commit publishes 1.0.39-0-1-g<commit>. GitOps pins the exact package. The default upstream image is the chart's appVersion; image.registry, image.repository, and image.tag can all be overridden independently.

Each configured Immich account references an existing Kubernetes Secret. The chart mounts its key as a file and writes only ApiKeyFile into Settings.yml; API keys never enter Helm values or rendered ConfigMaps.

config:
  accounts:
    - immichServerUrl: https://immich.example.com
      apiKeySecret:
        name: immichframe-api
        key: api-key
      options:
        Albums:
          - 00000000-0000-0000-0000-000000000000

Deployment and persistence model

ImmichFrame v1.0.38.0 and newer imports Settings.yml once into a SQLite database under /app/Config; afterward the database is its source of truth. With persistence.enabled: false (the default), each Deployment replica has an ephemeral database and reimports the declarative settings whenever its Pod is recreated. This is suitable when Git remains the configuration owner and admin UI edits are intentionally disposable.

Enable persistence and normally use one replica if admin UI changes must survive. With a persistent database, later Settings.yml changes are ignored by ImmichFrame and must instead be applied through its admin UI. Multiple replicas require storage that supports the chosen access mode and careful application-level consideration; they must not share one SQLite database.

CI publication

Gitea Actions lints, renders, schema-validates, and publishes the chart to https://brunner.ninja/charts. The repository needs these Actions secrets:

• PACKAGE_USERNAME and PACKAGE_TOKEN for the Gitea Helm package registry.
• GITOPS_TOKEN with write access to feedc0de/homelab-gitops so CI can promote the exact published chart version.

The live homelab values are intentionally kept in the public homelab-gitops application, where the API key is stored only as Sealed Secrets ciphertext.