fukuops/k8s/charts/immich/README.md

immich

A Helm chart for Immich, a self-hosted photo and video backup solution.

TL;DR

helm install immich oci://git.roboces.dev/catalin/fukuops/immich --version 1.0.0 -n apps-roboces

Prerequisites

• Kubernetes 1.19+
• Helm 3+
• A NFS storage class (default: truenas-nfs-csi)
• External PostgreSQL database
• External Redis instance

Configuration

All values are nested under the immich: key. Example:

immich:
  replicaCount: 1
  service:
    type: ClusterIP
    port: 2283
  config:
    database:
      hostname: "192.168.1.3"
      port: 55432
      username: ""
      password: ""
      name: ""
    redis:
      hostname: "192.168.1.3"
      port: 6379
    general:
      timezone: Europe/Madrid
  persistence:
    library:
      enabled: true
      storageClass: "truenas-nfs-csi"
      accessMode: ReadWriteMany
      size: 10Gi
  machineLearning:
    enabled: false
  secret:
    enabled: false
    existingSecretName: ""

Values Reference

Main Application

Key	Type	Default	Description
immich.replicaCount	int	1	Number of replicas
immich.image.repository	string	ghcr.io/immich-app/immich-server	Image repository
immich.image.pullPolicy	string	Always	Image pull policy
immich.image.tag	string	.Chart.AppVersion	Image tag
immich.service.type	string	ClusterIP	Service type
immich.service.port	int	2283	Service port
immich.service.targetPort	int	2283	Container port
immich.ingress.enabled	bool	false	Enable ingress
immich.debug.enabled	bool	false	Enable debug mode (adds init container for troubleshooting)
immich.resources	object	{}	Container resources
immich.livenessProbe	object	(see values.yaml)	Liveness probe
immich.readinessProbe	object	(see values.yaml)	Readiness probe

Database Configuration

Key	Type	Default	Description
immich.config.database.hostname	string	""	External database hostname
immich.config.database.port	int	55432	Database port
immich.config.database.username	string	""	Database username
immich.config.database.password	string	""	Database password
immich.config.database.name	string	""	Database name

Redis Configuration

Key	Type	Default	Description
immich.config.redis.hostname	string	""	External Redis hostname
immich.config.redis.port	int	6379	Redis port
immich.config.redis.dbIndex	string	""	Redis database index

General Configuration

Key	Type	Default	Description
immich.config.general.timezone	string	Europe/Madrid	Timezone

Persistence

Key	Type	Default	Description
immich.persistence.library.enabled	bool	true	Enable library persistence
immich.persistence.library.storageClass	string	truenas-nfs-csi	Storage class
immich.persistence.library.size	string	10Gi	PVC size
immich.persistence.encodedVideo.enabled	bool	true	Enable encoded video persistence
immich.persistence.thumbs.enabled	bool	true	Enable thumbnails persistence
immich.persistence.upload.enabled	bool	true	Enable uploads persistence
immich.persistence.profile.enabled	bool	true	Enable profiles persistence
immich.persistence.backups.enabled	bool	true	Enable backups persistence
immich.persistence.modelCache.enabled	bool	true	Enable model cache persistence

Machine Learning

Key	Type	Default	Description
immich.machineLearning.enabled	bool	false	Enable machine learning module
immich.machineLearning.image.repository	string	ghcr.io/immich-app/immich-machine-learning	ML image repository
immich.machineLearning.replicaCount	int	1	Number of ML replicas
immich.machineLearning.service.port	int	3003	ML service port
immich.machineLearning.persistence.modelCache.enabled	bool	true	Enable model cache persistence

Secret Management

Key	Type	Default	Description
immich.secret.enabled	bool	false	Enable secret management
immich.secret.existingSecretName	string	""	Existing secret name

ConfigMap

The chart creates a ConfigMap with database and Redis environment variables:

• TZ
• IMMICH_PORT
• IMMICH_MACHINE_LEARNING_URL
• DB_HOSTNAME, DB_PORT, DB_USERNAME, DB_DATABASE_NAME
• REDIS_HOSTNAME, REDIS_PORT, REDIS_DB

Persistence

The chart creates multiple PVCs:

• immich-library - Original photos and videos
• immich-encoded-video - Transcoded videos
• immich-thumbs - Generated thumbnails
• immich-upload - Upload queue
• immich-profile - User profiles
• immich-backups - Backup data
• immich-model-cache - ML model cache

The library PVC uses truenas-nfs-csi storage class by default with ReadWriteMany access mode.

Troubleshooting

Debug Mode

Enable debug mode to troubleshoot issues by adding an init container with a shell:

immich:
  debug:
    enabled: true

This adds an alpine:3.19 init container with sleep infinity that mounts all volumes and inherits env vars. You can exec into it to inspect the environment:

kubectl exec -it <pod-name> -c debug -- sh

When debug mode is enabled, liveness and readiness probes are disabled to prevent restarts.

Pod not starting

kubectl get pvc -n apps-roboces -l app.kubernetes.io/name=immich

Check logs

kubectl logs immich-server-0 -n apps-roboces

Check ML logs (if enabled)

kubectl logs immich-machine-learning-0 -n apps-roboces

Verify configmap

kubectl get configmap immich-config -n apps-roboces -o yaml