immich-docker/README.md

# Immich Docker Setup

Self-hosted photo and video management solution with Docker Compose.

## Overview

This repository contains a production-ready Docker Compose setup for [Immich](https://immich.app/), a high-performance self-hosted photo and video management solution.

## Features

- 🐳 Easy Docker Compose deployment
- 🔒 Secure configuration with environment variables
- 📦 Automated daily database backups
- 🔄 Health checks for all services
- 🚀 Reverse proxy ready (Caddy/Nginx)
- 📱 Mobile app support (iOS/Android)

## Architecture

This setup includes the following services:

- **immich-server**: Main application server
- **immich-machine-learning**: AI-powered photo recognition and classification
- **postgres**: Database with vector extensions for AI features
- **redis/valkey**: Caching layer

## Quick Start

### Prerequisites

- Docker 20.10+ and Docker Compose v2.0+
- At least 4GB RAM
- 10GB+ storage (plus space for your media)

### Installation

1. Clone this repository:
   ```bash
   git clone https://gitea.jeffemmett.com/jeff/immich-docker.git
   cd immich-docker
   ```

2. Create your environment file:
   ```bash
   cp .env.example .env
   ```

3. Generate a secure database password:
   ```bash
   # On Linux/macOS
   openssl rand -base64 32 | tr -d "=+/" | cut -c1-32
   
   # Or use this one-liner to update .env directly
   sed -i "s/CHANGE_ME_TO_RANDOM_PASSWORD/$(openssl rand -base64 32 | tr -d '=+\/' | cut -c1-32)/" .env
   ```

4. (Optional) Customize settings in `.env`:
   - `UPLOAD_LOCATION`: Where your photos/videos are stored
   - `DB_DATA_LOCATION`: Database storage location
   - `TZ`: Your timezone
   - `IMMICH_VERSION`: Pin to specific version if desired

5. Start the services:
   ```bash
   docker compose up -d
   ```

6. Access Immich at `http://localhost:2283`

## Configuration

### Environment Variables

All configuration is done through the `.env` file. See `.env.example` for all available options.

Key variables:
- `UPLOAD_LOCATION`: Media storage path (default: `./library`)
- `DB_DATA_LOCATION`: Database path (default: `./postgres`)
- `DB_PASSWORD`: PostgreSQL password (**must change before first run**)
- `IMMICH_VERSION`: Version tag (default: `v2`)
- `TZ`: Timezone (default: `Etc/UTC`)

### Reverse Proxy Setup

#### With Caddy

Create a Caddyfile:
```caddy
photos.yourdomain.com {
    reverse_proxy localhost:2283
    
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "SAMEORIGIN"
        Referrer-Policy "no-referrer-when-downgrade"
    }
}
```

#### With Nginx

```nginx
server {
    listen 443 ssl http2;
    server_name photos.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost: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;
    }
}
```

## Backup & Restore

### Automated Backups

Daily backups are configured via cron (if using the provided scripts):

```bash
# Run backup manually
./scripts/backup-database.sh

# Set up automated daily backups (2 AM)
crontab -e
# Add: 0 2 * * * /path/to/immich-docker/scripts/backup-database.sh >> /var/log/immich-backup.log 2>&1
```

### Manual Backup

```bash
# Backup database
docker compose exec -T database pg_dump -U postgres immich | gzip > backup-$(date +%Y%m%d_%H%M%S).sql.gz

# Backup uploaded files
tar -czf library-backup-$(date +%Y%m%d).tar.gz library/
```

### Restore from Backup

```bash
# Restore database
gunzip -c backup.sql.gz | docker compose exec -T database psql -U postgres immich

# Restore files
tar -xzf library-backup.tar.gz
```

## Maintenance

### Update Immich

```bash
# Pull latest images
docker compose pull

# Restart with new images
docker compose up -d

# Remove old images
docker image prune -f
```

### View Logs

```bash
# All services
docker compose logs -f

# Specific service
docker compose logs -f immich-server

# Last 100 lines
docker compose logs --tail=100
```

### Health Check

```bash
# Check container status
docker compose ps

# Run health check script
./scripts/health-check.sh
```

## Mobile Apps

Download the Immich mobile app to automatically backup your photos:

- **iOS**: [App Store - Immich](https://apps.apple.com/app/immich/id1613945652)
- **Android**: [Play Store - Immich](https://play.google.com/store/apps/details?id=app.alextran.immich)

Configure the app with:
- Server URL: `https://photos.yourdomain.com` (or your server address)
- Email/Password: Created during first-time setup

## Troubleshooting

### Cannot connect to Immich

1. Check if containers are running:
   ```bash
   docker compose ps
   ```

2. Check logs for errors:
   ```bash
   docker compose logs immich-server
   ```

3. Verify port is accessible:
   ```bash
   curl http://localhost:2283
   ```

### Database connection errors

1. Check database is healthy:
   ```bash
   docker compose exec database pg_isready -U postgres
   ```

2. Verify DB_PASSWORD matches in `.env`

### Out of disk space

1. Check Docker disk usage:
   ```bash
   docker system df
   ```

2. Clean up old images and containers:
   ```bash
   docker system prune -a
   ```

## Hardware Acceleration

For better performance with video transcoding and ML inference, enable hardware acceleration:

1. Uncomment the appropriate `extends` section in `docker-compose.yml`
2. Download the appropriate hwaccel file from Immich docs
3. Restart services

See [Immich Hardware Acceleration Docs](https://docs.immich.app/features/ml-hardware-acceleration) for details.

## Security Considerations

- ✅ Change `DB_PASSWORD` to a strong random password
- ✅ Use HTTPS with a reverse proxy
- ✅ Keep Immich updated regularly
- ✅ Restrict port 2283 to localhost if using a reverse proxy
- ✅ Enable firewall on your server
- ✅ Regular backups of database and media files

## Documentation

- [Official Immich Docs](https://docs.immich.app/)
- [Docker Installation Guide](https://docs.immich.app/install/docker-compose)
- [Environment Variables Reference](https://docs.immich.app/install/environment-variables)

## License

This setup configuration is MIT licensed. Immich itself is AGPL-3.0 licensed.

## Support

- [Immich GitHub](https://github.com/immich-app/immich)
- [Immich Discord](https://discord.gg/immich)
- [Immich Documentation](https://docs.immich.app/)