Immich Docker Deployment with Traefik

Manage Immich self-hosted photo and video management deployment using Docker Compose with Traefik reverse proxy integration.

What This Skill Does

This skill helps you deploy, configure, and maintain an Immich photo/video management system running in Docker containers behind a Traefik reverse proxy with SSL termination. It handles environment setup, service orchestration, troubleshooting, and performance optimization.

Repository Architecture

Core Components

**Immich Server**: Main application container (API + web interface)

**Immich Machine Learning**: Photo/video analysis, face detection, AI features

**PostgreSQL Database**: Metadata storage with vector extensions

**Redis/Valkey**: Caching layer

**Traefik Integration**: External reverse proxy with SSL

Networks

`proxy`: External network connecting to Traefik

`immich`: Internal network for service communication

Storage

Photo/Video storage: Configurable upload location (default: `./library`)

Database storage: Configurable database location (default: `./postgres`)

Model cache: Docker volume for ML models

Instructions

Initial Setup

1. **Verify Environment File**

- Check for `.env` file existence

- If missing, create from `.env.example`: `cp .env.example .env`

- Verify required variables are set:

- `UPLOAD_LOCATION`: Photo/video storage path

- `DB_DATA_LOCATION`: PostgreSQL data path

- `DB_PASSWORD`: Database password (must be changed from default)

- `TZ`: Timezone setting

- `IMMICH_VERSION`: Version tag (default: release)

2. **Verify External Network**

- Confirm `traefik` external network exists

- If not, create it: `docker network create traefik`

3. **Check Traefik Configuration**

- Verify Traefik labels in `docker-compose.yml`

- Confirm domain configuration (`photos.waugze.com`)

- Ensure SSL resolver is configured

Deployment Operations

**Start Services**

```bash

docker-compose up -d

```

**Stop Services**

```bash

docker-compose down

```

**Update to Latest Version**

```bash

docker-compose pull

docker-compose up -d

```

**Restart Specific Service**

```bash

docker-compose restart immich-server

```

**Check Service Status**

```bash

docker-compose ps

```

Monitoring and Logs

**View All Logs (Follow Mode)**

```bash

docker-compose logs -f

```

**View Specific Service Logs**

```bash

docker-compose logs -f immich-server

docker-compose logs -f immich-machine-learning

docker-compose logs -f database

```

**Check Last 100 Lines**

```bash

docker-compose logs --tail=100 immich-server

```

Troubleshooting

**Database Connection Issues**

Access database shell: `docker-compose exec database psql -U postgres -d immich`

Verify `DB_PASSWORD`, `DB_USERNAME`, `DB_DATABASE_NAME` in `.env`

Check database logs: `docker-compose logs database`

**ML Processing Slow or Failing**

Increase `MACHINE_LEARNING_WORKERS` in `.env` (default: 1)

Adjust `MACHINE_LEARNING_WORKER_TIMEOUT` if needed (default: 120)

Check ML logs: `docker-compose logs immich-machine-learning`

Verify model cache volume is mounted correctly

**Upload Failures**

Verify `UPLOAD_LOCATION` path exists and has correct permissions

Check Traefik timeout middleware configuration

Review server logs for specific error messages

**Container Won't Start**

Access container shell: `docker-compose exec immich-server sh`

Check network connectivity between containers

Verify all required environment variables are set

Ensure no port conflicts with host system

Performance Tuning

**For Multi-Core Systems**

Increase `MACHINE_LEARNING_WORKERS` to utilize more CPU cores

Monitor resource usage: `docker stats`

**Storage Optimization**

Database (`DB_DATA_LOCATION`): Use SSD for optimal performance

Upload location (`UPLOAD_LOCATION`): HDD acceptable for photo/video storage

Verify disk space: `df -h`

**Cache Management**

Model cache persists in Docker volume `model-cache`

Redis/Valkey provides application-level caching

No manual cache clearing typically needed

Security Considerations

**Required Actions**

Change `DB_PASSWORD` from default value

Verify SSL certificates are provisioned by Traefik/Let's Encrypt

Ensure `proxy` network isolates public-facing services

**Access Control**

SSL/TLS termination handled by Traefik

Immich has built-in user authentication

Consider additional network isolation for production

Maintenance Tasks

**Backup Database**

```bash

docker-compose exec database pg_dump -U postgres immich > backup.sql

```

**Backup Photos**

Copy contents of `UPLOAD_LOCATION` directory to backup destination

Ensure permissions are preserved

**Check Disk Usage**

```bash

du -sh $UPLOAD_LOCATION

du -sh $DB_DATA_LOCATION

```

Common Issues and Solutions

**"Network traefik not found"**

Create external network: `docker network create traefik`

**"Permission denied" errors**

Check ownership of `UPLOAD_LOCATION` and `DB_DATA_LOCATION`

Adjust permissions: `chown -R 1000:1000 ./library ./postgres`

**SSL certificate issues**

Verify Traefik is running and configured correctly

Check Traefik logs for Let's Encrypt challenges

Confirm DNS points to correct server

**High memory usage**

Reduce `MACHINE_LEARNING_WORKERS`

Check for memory leaks in logs

Consider increasing host system RAM

Configuration Files

**docker-compose.yml**: Service definitions, networks, volumes

**.env**: Environment variables (create from `.env.example`)

**.env.example**: Template with all available configuration options

External Dependencies

Traefik reverse proxy (must be running on external `traefik` network)

Docker and Docker Compose installed on host

Valid domain with DNS pointing to server (for SSL)

Immich Docker Deployment with Traefik

Immich Docker Deployment with Traefik

What This Skill Does

Repository Architecture

Core Components

Networks

Storage

Instructions

Initial Setup

Deployment Operations

Monitoring and Logs

Troubleshooting

Performance Tuning

Security Considerations

Maintenance Tasks

Common Issues and Solutions

Configuration Files

External Dependencies

Reviews (0)