Immich Self-Hosted Photo and Video Backup

Immich is a high-performance self-hosted photo and video backup solution designed as a Google Photos alternative, with a mobile app that automatically backs up your camera roll to your own Linux server. Built with a microservices architecture using Docker, Immich provides machine learning-powered face detection, object recognition, a timeline view, shared libraries, and real-time mobile sync.

Prerequisites

  • Ubuntu 20.04+, Debian 11+, or CentOS/Rocky 8+
  • Docker and Docker Compose installed
  • Minimum 4 GB RAM (8+ GB recommended for ML features)
  • Sufficient storage for photos/videos
  • Root or sudo access
  • A domain name or public IP for mobile app access

Installing Immich with Docker

# Create the Immich directory
sudo mkdir -p /opt/immich
cd /opt/immich

# Download the official docker-compose.yml and .env files
curl -LO https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
curl -LO https://github.com/immich-app/immich/releases/latest/download/example.env
cp example.env .env

# Edit the .env file with your configuration
nano .env

Key .env settings:

# .env file
# Upload directory — where photos are stored
UPLOAD_LOCATION=/opt/immich/data/upload

# Database password (change these!)
DB_PASSWORD=postgres_password_here

# Immich version
IMMICH_VERSION=release

# Timezone for metadata
TZ=America/New_York

# Create the upload directory
sudo mkdir -p /opt/immich/data/upload
sudo chmod 755 /opt/immich/data/upload

# Start Immich
sudo docker compose up -d

# Monitor startup (takes 2-3 minutes on first run)
sudo docker compose logs -f immich-server

Immich runs on port 2283 by default. Access at http://your-server:2283.

Initial Setup

Complete the initial setup wizard:

  1. Navigate to http://your-server:2283
  2. Create the first admin account (email + password)
  3. Click Getting Started to finish setup

Configure storage template:

# In Admin Panel > Settings > Storage Template
# Default template organizes by date:
# {{y}}/{{y}}-{{MM}}-{{DD}}/{{filename}}

# Custom templates available:
# {{y}}/{{MM}}/{{filename}}
# {{albumName}}/{{filename}}

Configure thumbnail settings:

# Admin > Settings > Thumbnail Settings
# Thumbnail sizes:
# Large:  1440 (for desktop)
# Small:  360 (for mobile)
# Preview: 250 (for timeline)

Mobile App Configuration

Install the Immich mobile app:

  • Android: Available on Google Play and F-Droid
  • iOS: Available on the App Store

Connect the mobile app:

  1. Open the Immich app
  2. Enter your server URL: https://photos.example.com or http://your-server-ip:2283
  3. Log in with your email and password
  4. Go to Settings > Background Backup
  5. Enable backup for Photos and Videos
  6. Choose backup frequency and wifi-only option

Backup configuration tips:

- Enable "Background backup" for automatic sync
- Set "Backup when charging" to avoid battery drain  
- Enable "Wifi only" to avoid mobile data usage
- Configure "Backup albums" to exclude screenshots

Machine Learning Features

Immich uses machine learning for face clustering and CLIP-based search:

# The immich-machine-learning service runs automatically
# Check its status
sudo docker compose ps immich-machine-learning

# View ML processing logs
sudo docker compose logs immich-machine-learning -f

Enable smart search and face detection:

# In Admin Panel > Settings > Machine Learning Settings
# Enable:
# - Smart Search (CLIP model for semantic search)
# - Facial Recognition
# - Object Detection (labels)

Trigger ML reprocessing:

# Via admin panel: Jobs > Smart Search > Run all
# Or via API
curl -X POST "http://localhost:2283/api/jobs/smartSearch" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "start", "force": true}'

Configure hardware acceleration for ML (optional):

# In docker-compose.yml, modify immich-machine-learning service:
services:
  immich-machine-learning:
    # For NVIDIA GPU:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    environment:
      - MACHINE_LEARNING_DEVICE_IDS=0

Shared Libraries and Albums

Create a shared album:

  1. Open Immich web interface
  2. Go to Albums > Create Album
  3. Add photos to the album
  4. Click Share > Invite Users to share with other Immich users
  5. Or click Create Link for external sharing

Partner sharing (share entire library):

  1. Go to Settings > Sharing
  2. Under Partner Sharing, search for a user
  3. Select the partner — they will see your entire library in their timeline

External sharing via link:

# Albums can be shared with public links
# Settings per shared link:
# - Expiration date
# - Password protection
# - Allow downloading
# - Show metadata (GPS, camera info)

External Storage and Libraries

Import photos from existing directories without moving them:

# Mount external storage in docker-compose.yml
services:
  immich-server:
    volumes:
      - /opt/immich/data/upload:/usr/src/app/upload
      - /mnt/nas/photos:/mnt/nas/photos:ro  # External library (read-only)

Create an external library in the admin panel:

  1. Go to Admin > External Libraries
  2. Click Create External Library
  3. Set the import path: /mnt/nas/photos
  4. Assign to a user
  5. Click Scan to index the files
# Trigger external library scan via CLI
sudo docker compose exec immich-server \
  node /usr/src/app/dist/main.js trigger-external-library-scan

Backup Strategies

Back up the database:

# Dump PostgreSQL database
sudo docker compose exec database pg_dumpall \
  --clean \
  --if-exists \
  --username=postgres > \
  /backup/immich-db-$(date +%Y%m%d).sql

# Compress
gzip /backup/immich-db-$(date +%Y%m%d).sql

Automate database backups:

sudo tee /opt/immich/backup.sh <<'EOF'
#!/bin/bash
BACKUP_DIR="/backup/immich"
mkdir -p "$BACKUP_DIR"

# Database backup
cd /opt/immich
docker compose exec -T database pg_dumpall \
  --clean --if-exists --username=postgres | \
  gzip > "${BACKUP_DIR}/db-$(date +%Y%m%d).sql.gz"

# Keep only last 7 database backups
find "$BACKUP_DIR" -name "db-*.sql.gz" -mtime +7 -delete

echo "Backup completed: $(date)"
EOF
chmod +x /opt/immich/backup.sh

# Schedule daily backup
(crontab -l 2>/dev/null; echo "0 2 * * * /opt/immich/backup.sh >> /var/log/immich-backup.log 2>&1") | crontab -

Troubleshooting

Photos not syncing from mobile:

# Check server connectivity from mobile app
# Settings > Server Info should show green

# Verify server is accessible
curl -I https://photos.example.com/api/server-info/ping

# Check for upload errors
sudo docker compose logs immich-server | grep -i error

# Restart the server service
sudo docker compose restart immich-server

ML processing stuck or not working:

# Check ML service logs
sudo docker compose logs immich-machine-learning -n 50

# Restart ML service
sudo docker compose restart immich-machine-learning

# Check available memory
free -h
sudo docker stats

High disk usage from thumbnails:

# Check thumbnail storage
sudo du -sh /opt/immich/data/upload/thumbs/

# Reduce thumbnail quality in Admin > Settings
# Or clean up orphaned thumbnails
sudo docker compose exec immich-server \
  node /usr/src/app/dist/main.js clean-database orphans

Conclusion

Immich provides a feature-complete self-hosted photo backup platform that matches the convenience of Google Photos with automatic mobile backup, machine learning-powered search, face clustering, and timeline organization — while keeping all your memories on your own infrastructure. With Docker-based deployment and active development, Immich continues to improve rapidly and represents the best open-source alternative for users who need both the ease of cloud photo services and the privacy of self-hosting.