# immich

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

## TL;DR

```bash
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:

```yaml
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:

```yaml
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:

```bash
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

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

### Check logs

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

### Check ML logs (if enabled)

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

### Verify configmap

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