diff --git a/immich/README.md b/immich/README.md index e69de29..d9414d9 100644 --- a/immich/README.md +++ b/immich/README.md @@ -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 +``` + +## πŸ› 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 +``` + +## πŸ“Š 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