immichframe-helm/README.md

# ImmichFrame Helm chart

This repository packages the upstream
[ImmichFrame](https://github.com/immichFrame/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:

```sh
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.

```yaml
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](https://code.brunner.ninja/feedc0de/homelab-gitops/src/branch/main/apps/immichframe),
where the API key is stored only as Sealed Secrets ciphertext.