Immich

Immich is a self-hosted photo and video management platform. The HelmForge chart deploys Immich server, machine learning, PostgreSQL, and a Redis-compatible cache with production-oriented Kubernetes defaults.

Key Features

Official Immich images pinned to v2.7.5
HelmForge PostgreSQL dependency using Immich’s VectorChord PostgreSQL image defaults
HelmForge Redis chart aliased as valkey for Redis-compatible cache support
Machine learning service with persistent model cache
External PostgreSQL and external Redis/Valkey modes
Ingress, Gateway API, dual-stack Service fields, HPA, PDB, NetworkPolicy, External Secrets, and Helm tests

Installation

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install immich helmforge/immich --namespace immich --create-namespace

helm install immich oci://ghcr.io/helmforgedev/helm/immich --namespace immich --create-namespace

Examples

External database:

postgresql:
  enabled: false
database:
  external:
    host: postgres.example.com
    database: immich
    username: immich
    existingSecret: immich-db
    existingSecretPasswordKey: database-password

Ingress:

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: immich.example.com
      paths:
        - path: /
          pathType: Prefix

Operations

Persistent uploads are application data. Keep the upload PVC backed up with your platform backup tool. For production, prefer an external PostgreSQL instance or explicitly size the bundled PostgreSQL and cache PVCs.

Architecture

The chart deploys the Immich server, the machine-learning service, HelmForge PostgreSQL, and a Redis/Valkey-compatible cache by default. Uploads, database data, cache data, and machine-learning model cache are separate persistence concerns and should be sized independently.

Runtime flow:

Ingress or Gateway API exposes the Immich server.
The server stores metadata in PostgreSQL and binary media in the uploads volume.
The cache service backs queues and application cache behavior.
The machine-learning service stores model files on its own cache volume.
Optional External Secrets wire external database or cache credentials.

Production Values

Use durable uploads, durable dependencies, stable credentials, and explicit routing:

server:
  replicaCount: 1
  persistence:
    enabled: true
    accessModes:
      - ReadWriteOnce
    storageClass: fast-retain
    size: 500Gi

machineLearning:
  persistence:
    enabled: true
    storageClass: fast-retain
    size: 20Gi

postgresql:
  auth:
    existingSecret: immich-postgresql-auth
    existingSecretPostgresPasswordKey: postgres-password
    existingSecretUserPasswordKey: user-password
  standalone:
    persistence:
      enabled: true
      storageClass: fast-retain
      size: 100Gi

valkey:
  auth:
    enabled: true
    existingSecret: immich-cache-auth
    existingSecretPasswordKey: valkey-password
  standalone:
    persistence:
      enabled: true
      storageClass: fast-retain
      size: 10Gi

Do not increase server replicas while uploads use ReadWriteOnce storage. The chart blocks unsafe multi-writer shapes so media libraries are not corrupted by multiple pods writing to a single-writer volume.

External Services

For platform-managed PostgreSQL and Redis/Valkey:

postgresql:
  enabled: false

database:
  external:
    host: postgres.example.com
    port: 5432
    database: immich
    username: immich
    existingSecret: immich-db
    existingSecretPasswordKey: database-password

valkey:
  internal:
    enabled: false
  external:
    host: valkey.example.com
    port: 6379
    existingSecret: immich-cache
    existingSecretPasswordKey: redis-password

The external database must include the extensions required by Immich before application startup. Validate extension ownership and upgrade behavior in the database runbook, not only in the Helm release.

Networking

Ingress example:

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: immich.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: immich-tls
      hosts:
        - immich.example.com

Gateway API example:

gateway:
  enabled: true
  parentRefs:
    - name: public
      namespace: gateway-system
  hostnames:
    - immich.example.com
  path: /
  pathType: PathPrefix

Storage And Backup

Back up at least:

the uploads PVC
PostgreSQL data, whether bundled or external
Secrets used for database/cache credentials
any external object storage or backup configuration used by the platform

The cache is usually rebuildable, but persistent cache storage can reduce cold-start impact. Do not treat the cache as the source of truth for photos or videos.

Validation

After deployment:

helm test immich -n immich
kubectl get pods -n immich -l app.kubernetes.io/name=immich
kubectl logs -n immich deploy/immich --since=10m
kubectl get events -n immich --sort-by=.lastTimestamp

Also validate browser login, upload, thumbnail generation, search, and machine-learning classification against a small test library.

Common Issues

Symptom	Likely Cause	Fix
Render fails when scaling server	Upload volume is single-writer	Use `ReadWriteMany` storage or keep one server replica.
Startup fails on database migrations	External PostgreSQL lacks required extensions or permissions	Prepare the database before deploying Immich.
ML features are slow after restart	Model cache is ephemeral	Enable `machineLearning.persistence`.
Uploads disappear after pod recreation	Upload persistence disabled or wrong PVC	Enable server persistence and verify PVC binding.

Values

Parameter	Default	Description
`image.repository`	`ghcr.io/immich-app/immich-server`	Immich server image repository.
`image.tag`	`v2.7.5`	Immich server image tag.
`machineLearning.enabled`	`true`	Deploy the machine learning service.
`postgresql.enabled`	`true`	Deploy HelmForge PostgreSQL dependency.
`valkey.internal.enabled`	`true`	Deploy Redis-compatible cache dependency.
`database.external.host`	`""`	External PostgreSQL hostname.
`service.ipFamilyPolicy`	`null`	Optional Service dual-stack policy.
`ingress.enabled`	`false`	Render Ingress.
`gateway.enabled`	`false`	Render Gateway API HTTPRoute.
`externalSecrets.enabled`	`false`	Render ExternalSecret resources.