# Immich Photo Management - Installatie Handleiding

Complete handleiding voor het opzetten van Immich met Synology NAS storage en Portainer deployment.

## 📋 Overzicht

Immich is een zelfgehoste foto en video management oplossing met AI-powered features voor gezichtsherkenning, object detectie en smart search.

## ✨ Features

- 📸 Automatische foto en video backup vanaf mobiele apps
- 🔍 AI-powered zoeken (gezichten, objecten, locaties)
- 🗺️ Kaart weergave van foto's op basis van GPS metadata
- 📱 Native mobile apps voor iOS en Android
- 🖼️ Moderne web interface
- 🤖 Machine learning voor automatische tagging
- 👥 Multi-user support
- 🔄 Real-time synchronisatie

## 🔧 Vereisten

### Hardware
- **Server**: Proxmox VE of vergelijkbaar (minimaal 4GB RAM voor Immich)
- **Storage**: Synology NAS met NFS support
- **Netwerk**: Stabiele LAN verbinding tussen server en NAS

### Software
- Docker en Docker Compose
- Portainer (voor container management)
- NFS client tools op de Docker host
- Git (voor repo management)

### Netwerk Configuratie
In dit voorbeeld:
- **Proxmox Server IP**: `10.1.80.2`
- **Synology NAS IP**: `10.1.10.7`
- **NAS Share**: `/volume1/immich`
- **Immich Web Port**: `2283`

## 📁 Repository Structuur

```
mijn-docker-stacks/
└── immich/
    ├── docker-compose.yml
    ├── .env.example
    ├── .gitignore
    └── README.md (dit bestand)
```

## 🚀 Installatie Stappen

### Stap 1: NFS Configureren op Synology NAS

1. **Log in op Synology DSM**
   - Open je browser en ga naar `http://10.1.10.7:6801`

2. **Maak een Shared Folder aan** (indien nog niet aanwezig)
   - Ga naar **Configuratiescherm** → **Gedeelde map**
   - Klik **Maken**
   - Naam: `immich`
   - Klik **OK**

3. **Schakel NFS in**
   - Ga naar **Configuratiescherm** → **Bestandsservices**
   - Tab **NFS**
   - Vink aan: **NFS inschakelen**
   - Klik **Toepassen**

4. **Configureer NFS Permissions**
   - Ga terug naar **Configuratiescherm** → **Gedeelde map**
   - Selecteer de `immich` map
   - Klik **Bewerken** → **NFS-machtigingen**
   - Klik **Maken** en voeg toe:
     - **Server of IP-adres**: `10.1.80.2` (IP van je Proxmox/Docker host)
     - **Bevoegdheid**: Lezen/schrijven
     - **Squash**: Map all users to admin
     - **Beveiliging**: sys
     - **Asynchrone modus**: ✓ (aangevinkt voor betere prestaties)
   - Klik **OK** en **OK**

### Stap 2: NFS Mount Configureren op Docker Host

SSH naar je Proxmox/Docker host:

```bash
ssh root@10.1.80.2
```

#### 2.1 Installeer NFS Client Tools

```bash
# Update package lijst
apt update

# Installeer NFS client
apt install nfs-common -y
```

#### 2.2 Maak Mount Directory

```bash
# Maak de mount directory aan
mkdir -p /mnt/immich-nas
```

#### 2.3 Test de NFS Mount

```bash
# Controleer beschikbare NFS exports op de NAS
showmount -e 10.1.10.7

# Mount de NFS share (tijdelijk voor test)
mount -t nfs -o rw,soft,intr,vers=3 10.1.10.7:/volume1/immich /mnt/immich-nas

# Controleer of de mount werkt
df -h | grep immich

# Test schrijfrechten
touch /mnt/immich-nas/test.txt
ls -la /mnt/immich-nas/
```

#### 2.4 Configureer Permanente Mount via fstab

```bash
# Open fstab
nano /etc/fstab

# Voeg deze regel toe onderaan:
10.1.10.7:/volume1/immich /mnt/immich-nas nfs rw,soft,intr,vers=3 0 0

# Sla op met: Ctrl+X, dan Y, dan Enter

# Herlaad systemd
systemctl daemon-reload

# Test de fstab configuratie
umount /mnt/immich-nas
mount -a

# Controleer of het werkt
df -h | grep immich
```

### Stap 3: GitHub Repository Setup

#### 3.1 SSH Key Genereren (eenmalig)

```bash
# Genereer SSH key voor GitHub authenticatie
ssh-keygen -t ed25519 -C "jouw@email.com"
# Druk 3x op Enter (geen passphrase nodig)

# Toon de public key
cat ~/.ssh/id_ed25519.pub
```

Kopieer de **volledige output** (begint met `ssh-ed25519` en eindigt met je email).

#### 3.2 SSH Key Toevoegen aan GitHub

1. Ga naar: https://github.com/settings/keys
2. Klik **"New SSH key"**
3. **Title**: `Proxmox Server` (of een beschrijvende naam)
4. **Key**: plak de complete public key
5. Klik **"Add SSH key"**

#### 3.3 Test SSH Verbinding

```bash
# Test de verbinding met GitHub
ssh -T git@github.com

# Als het vraagt "Are you sure...", typ: yes
# Je zou moeten zien: "Hi [username]! You've successfully authenticated..."
```

#### 3.4 Clone de Repository

```bash
# Ga naar home directory
cd ~

# Clone je repository
git clone git@github.com:MisticDruid/mijn-docker-stacks.git

# Ga naar de immich folder
cd mijn-docker-stacks/immich

# Bekijk de bestanden
ls -la
```

### Stap 4: Docker Compose Configuratie

#### 4.1 Verwijder env_file References

De `docker-compose.yml` moet aangepast worden om te werken met Portainer's environment variables.

```bash
cd ~/mijn-docker-stacks/immich

# Open docker-compose.yml
nano docker-compose.yml
```

**Verwijder of comment out** alle `env_file:` secties in het bestand:

**VOOR** (verwijder deze regels):
```yaml
services:
  immich-server:
    env_file:
      - stack.env
```

**NA** (zonder env_file):
```yaml
services:
  immich-server:
    # env_file verwijderd - wordt via Portainer ingesteld
```

Doe dit voor ALLE services in het bestand:
- `immich-server`
- `immich-machine-learning`
- `database`

Sla op met `Ctrl+X`, dan `Y`, dan `Enter`.

#### 4.2 Commit en Push de Wijzigingen

```bash
# Voeg wijzigingen toe
git add docker-compose.yml

# Commit
git commit -m "Remove env_file references for Portainer compatibility"

# Push naar GitHub
git push
```

### Stap 5: Deploy in Portainer

#### 5.1 Open Portainer

Open je browser en ga naar: `https://10.1.80.2:9443` (of jouw Portainer URL)

#### 5.2 Nieuwe Stack Aanmaken

1. Klik in het menu op **Stacks**
2. Klik rechtsboven op **Add stack**
3. Vul de volgende gegevens in:

**Stack Configuration:**
- **Name**: `immich`
- **Build method**: Kies **Repository**

**Git Repository Settings:**
- **Authentication**: Laat op "none" staan (voor public repo) of configureer SSH
- **Repository URL**: `https://github.com/MisticDruid/mijn-docker-stacks`
- **Repository reference**: `refs/heads/main`
- **Compose path**: `immich/docker-compose.yml`

#### 5.3 Environment Variables Configureren

Scroll naar beneden naar **Environment variables**.

Klik op **Advanced mode** en plak de volgende configuratie:

```env
DB_HOSTNAME=database
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE_NAME=immich
UPLOAD_LOCATION=/mnt/immich-nas
REDIS_HOSTNAME=redis
MACHINE_LEARNING_HOST=immich-machine-learning
MACHINE_LEARNING_PORT=3003
LOG_LEVEL=log
TZ=Europe/Amsterdam
```

**⚠️ BELANGRIJK**: Pas `DB_PASSWORD` aan naar een veilig wachtwoord voor productie gebruik!

#### 5.4 Access Control

Scroll verder naar **Access control**:
- Zet toggle aan bij **Enable access control**
- Selecteer **Administrators**

#### 5.5 Deploy

1. Scroll helemaal naar beneden
2. Klik op de blauwe knop **"Deploy the stack"**

Portainer zal nu:
- De repository clonen
- Docker images downloaden (dit kan enkele minuten duren)
- Containers starten
- Database initialiseren

### Stap 6: Eerste Start en Configuratie

#### 6.1 Monitor de Deployment

In Portainer:
1. Ga naar **Stacks** → **immich**
2. Bekijk de container status
3. Alle containers moeten **"running"** zijn:
   - `immich_server`
   - `immich_machine_learning`
   - `immich_postgres`
   - `immich_redis`

#### 6.2 Check Container Logs

Als er problemen zijn, bekijk de logs:

```bash
# Via terminal
docker logs immich_server
docker logs immich_postgres
docker logs immich_machine_learning
docker logs immich_redis

# Of via Portainer UI:
# Containers → klik op container → Logs
```

#### 6.3 Open Immich Web Interface

1. Open je browser
2. Ga naar: `http://10.1.80.2:2283`
3. Je ziet het Immich welkomstscherm

#### 6.4 Maak Admin Account

Bij eerste keer openen:
1. Klik op **"Getting Started"**
2. Vul in:
   - **Email**: je email adres
   - **Password**: een sterk wachtwoord
   - **Confirm Password**: herhaal wachtwoord
   - **Name**: je naam
3. Klik **"Sign Up"**

🎉 **Gefeliciteerd!** Immich is nu geïnstalleerd en klaar voor gebruik!

## 📱 Mobile Apps Installeren

### iOS
1. Open de **App Store**
2. Zoek naar **"Immich"**
3. Download en installeer

### Android
1. Open de **Google Play Store**
2. Zoek naar **"Immich"**
3. Download en installeer

### App Configureren

1. Open de Immich app
2. Tap **"Connect to Server"**
3. Vul in:
   - **Server URL**: `http://10.1.80.2:2283`
   - **Email**: je admin email
   - **Password**: je admin wachtwoord
4. Tap **"Login"**
5. Geef de app foto toegang permissions
6. Schakel **Auto Backup** in

## 🔄 Updates

### Update via Portainer

1. Ga naar **Stacks** → **immich**
2. Klik op **Editor**
3. Klik rechtsboven op **Pull and redeploy**
4. Bevestig de update

Dit zal automatisch de nieuwste images downloaden en containers herstarten.

### Update via Terminal

```bash
# SSH naar je server
ssh root@10.1.80.2

# Ga naar de immich stack directory
cd ~/mijn-docker-stacks/immich

# Pull laatste changes van Git
git pull

# Pull nieuwe Docker images
docker compose pull

# Herstart containers met nieuwe images
docker compose up -d
```

## 🔧 Onderhoud

### Database Backup

```bash
# Maak een backup van de PostgreSQL database
docker exec immich_postgres pg_dump -U postgres immich > immich_backup_$(date +%Y%m%d).sql

# Of via Portainer:
# Containers → immich_postgres → Console → voer uit:
# pg_dump -U postgres immich > /tmp/backup.sql
# Download daarna via Portainer's file browser
```

### Database Restore

```bash
# Restore een backup
docker exec -i immich_postgres psql -U postgres immich < immich_backup_20241129.sql
```

### Logs Roteren

```bash
# Limiteer Docker log sizes in /etc/docker/daemon.json
nano /etc/docker/daemon.json

# Voeg toe:
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

# Herstart Docker
systemctl restart docker
```

### Volume Cleanup

```bash
# Verwijder ongebruikte volumes (VOORZICHTIG!)
docker volume prune

# Of specifiek:
docker volume ls
docker volume rm <volume_name>
```

## 🐛 Troubleshooting

### NFS Mount Werkt Niet

**Probleem**: Mount error of "no such file or directory"

**Oplossing**:
```bash
# Check NFS exports op NAS
showmount -e 10.1.10.7

# Controleer firewall
# Synology: Configuratiescherm → Beveiliging → Firewall
# Zorg dat NFS poorten open zijn (2049, 111)

# Test mount handmatig
mount -t nfs -o rw,soft,intr,vers=3 10.1.10.7:/volume1/immich /mnt/immich-nas

# Check kernel logs
dmesg | grep -i nfs

# Probeer andere NFS versie
mount -t nfs -o vers=4 10.1.10.7:/volume1/immich /mnt/immich-nas
```

### Container Start Niet

**Probleem**: Container status is "exited" of "restarting"

**Oplossing**:
```bash
# Bekijk logs
docker logs immich_server --tail 100

# Check of poort 2283 al in gebruik is
netstat -tulpn | grep 2283

# Check of volumes correct gemount zijn
docker inspect immich_server | grep -A 10 Mounts
```

### Database Connection Errors

**Probleem**: "Connection refused" of "database not found"

**Oplossing**:
```bash
# Check of PostgreSQL container draait
docker ps | grep postgres

# Bekijk database logs
docker logs immich_postgres

# Test database connectie
docker exec -it immich_postgres psql -U postgres -d immich

# Als database niet bestaat, maak hem aan:
docker exec -it immich_postgres psql -U postgres -c "CREATE DATABASE immich;"
```

### Machine Learning Issues

**Probleem**: Gezichtsherkenning werkt niet

**Oplossing**:
```bash
# Check ML container logs
docker logs immich_machine_learning

# ML container heeft veel RAM nodig (minimaal 2GB)
# Check beschikbaar geheugen:
free -h

# Herstart ML container
docker restart immich_machine_learning
```

### Permission Denied Errors

**Probleem**: "Permission denied" bij schrijven naar NAS

**Oplossing**:
```bash
# Check mount permissions
ls -la /mnt/immich-nas

# Test schrijfrechten
touch /mnt/immich-nas/test.txt

# Verander NFS Squash settings op Synology:
# Gebruik "Map all users to admin" in NFS permissions

# Of verander ownership
chown -R 1000:1000 /mnt/immich-nas
```

### Slow Upload/Backup Speed

**Probleem**: Foto uploads zijn traag

**Oplossing**:
```bash
# Check netwerk verbinding
ping 10.1.10.7

# Test NFS performance
dd if=/dev/zero of=/mnt/immich-nas/testfile bs=1M count=1000

# Gebruik async mount voor betere prestaties
mount -t nfs -o rw,soft,intr,vers=3,async 10.1.10.7:/volume1/immich /mnt/immich-nas

# Update fstab met async:
10.1.10.7:/volume1/immich /mnt/immich-nas nfs rw,soft,intr,vers=3,async 0 0
```

### Poort 2283 al in Gebruik

**Probleem**: "port is already allocated"

**Oplossing**:
```bash
# Check wat de poort gebruikt
lsof -i :2283

# Verander de poort in docker-compose.yml:
ports:
  - 2284:3001  # Gebruik 2284 in plaats van 2283

# Of stop de conflicterende service
docker stop <container_name>
```

## 📊 Performance Optimalisatie

### Database Tuning

Voor betere performance, pas de PostgreSQL settings aan in `docker-compose.yml`:

```yaml
database:
  command: [
    "postgres",
    "-c", "shared_preload_libraries=vectors.so",
    "-c", "search_path=\"$$user\", public, vectors",
    "-c", "logging_collector=on",
    "-c", "max_wal_size=2GB",
    "-c", "shared_buffers=512MB",      # Verhoog voor meer RAM
    "-c", "effective_cache_size=2GB",  # Toevoegen
    "-c", "maintenance_work_mem=256MB", # Toevoegen
    "-c", "wal_compression=on"
  ]
```

### Redis Memory Limit

```yaml
redis:
  image: redis:6.2-alpine
  command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
```

### NFS Performance

Beste mount opties voor performance:
```bash
mount -t nfs -o rw,soft,intr,vers=3,async,noatime,nodiratime 10.1.10.7:/volume1/immich /mnt/immich-nas
```

## 🔒 Beveiliging

### Verander Default Passwords

```bash
# Update in .env of Portainer environment variables:
DB_PASSWORD=JeEigenVeiligWachtwoord123!
```

### Firewall Regels

```bash
# Limiteer toegang tot Immich (UFW voorbeeld)
ufw allow from 10.1.10.0/24 to any port 2283
ufw deny 2283
```

### HTTPS Setup met Reverse Proxy

Voor productie gebruik, setup een reverse proxy (Nginx/Traefik) met SSL:

```nginx
server {
    listen 443 ssl http2;
    server_name photos.jouwdomein.nl;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://10.1.80.2:2283;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

## 📚 Nuttige Links

- **Immich Documentatie**: https://immich.app/docs
- **GitHub Repository**: https://github.com/immich-app/immich
- **Discord Community**: https://discord.gg/immich
- **Feature Requests**: https://github.com/immich-app/immich/discussions
- **Bug Reports**: https://github.com/immich-app/immich/issues

## 📝 Environment Variables Reference

| Variable | Standaard | Beschrijving |
|----------|-----------|--------------|
| `DB_HOSTNAME` | `database` | PostgreSQL container hostname |
| `DB_PORT` | `5432` | PostgreSQL poort |
| `DB_USERNAME` | `postgres` | Database gebruikersnaam |
| `DB_PASSWORD` | `postgres` | Database wachtwoord (VERANDER DIT!) |
| `DB_DATABASE_NAME` | `immich` | Database naam |
| `UPLOAD_LOCATION` | `/mnt/immich-nas` | Pad naar foto storage |
| `REDIS_HOSTNAME` | `redis` | Redis container hostname |
| `MACHINE_LEARNING_HOST` | `immich-machine-learning` | ML container hostname |
| `MACHINE_LEARNING_PORT` | `3003` | ML service poort |
| `LOG_LEVEL` | `log` | Log niveau (log, verbose, debug) |
| `TZ` | `Europe/Amsterdam` | Timezone |

## 🎯 Tips & Best Practices

1. **Regelmatige Backups**: Maak wekelijks een backup van je database
2. **Monitor Storage**: Houd je NAS storage in de gaten, foto's kunnen snel oplopen
3. **Updates**: Update Immich regelmatig voor nieuwe features en bugfixes
4. **Mobile Backup**: Stel backup in op WiFi-only om data te besparen
5. **Duplicaten**: Immich detecteert automatisch duplicaten
6. **Albums**: Organiseer je foto's in albums voor betere overzicht
7. **Sharing**: Gebruik de share functie voor het delen met familie
8. **Face Recognition**: Laat de ML container even draaien na upload voor gezichtsherkenning

## 🆘 Support

Bij problemen:
1. Check eerst de logs: `docker logs immich_server`
2. Bekijk de Troubleshooting sectie hierboven
3. Zoek in de Immich GitHub Issues
4. Vraag hulp in de Discord community
5. Open een issue op GitHub met logs en configuratie

## 📄 Licentie

Deze handleiding is vrij te gebruiken en aan te passen.
Immich zelf is gelicenseerd onder AGPL-3.0.

---

**Versie**: 1.0
**Laatst bijgewerkt**: November 2024
**Auteur**: Setup voor Proxmox + Synology NAS + Portainer