Add complete Immich installation guide

2025-11-29 14:16:28 +01:00
1 parent a2c2217198
commit 7c9a58fac7
@@ -0,0 +1,722 @@
+# 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