immich

Identity

• Stack: multi-container Docker Compose application — 5 services minimum
  • immich-server — API, web UI, upload handling (port 2283)
  • immich-microservices — background job worker (thumbnail generation, metadata extraction, video transcoding)
  • immich-machine-learning — face detection, CLIP semantic search (optional but common)
  • database — PostgreSQL with pgvecto-rs extension (NOT standard postgres — the vector extension is required)
  • redis — job queue broker between server and microservices
• Config: .env file in the same directory as docker-compose.yml
• Port: 2283/tcp (HTTP — reverse-proxy this; Immich has no built-in TLS)
• Upload dir: controlled by UPLOAD_LOCATION in .env — must be a persistent volume mount
• Project page: https://immich.app

Key Operations

Expected State

• All 5 containers show Up (or Up (healthy) if healthchecks are configured) in docker compose ps
• No containers in Restarting or Exit state
• Job queue shows no permanently failed jobs (occasional transient failures are normal)
• immich-machine-learning may be absent if ML is disabled via IMMICH_MACHINE_LEARNING_ENABLED=false

Health Checks

1. docker compose ps — all services show Up; nothing in Restarting or Exit
2. curl -s http://localhost:2283/api/server-info/ping — returns {"res":"pong"}
3. Web UI → Administration → Jobs — no queue items stuck in a failed/error state indefinitely

Common Failures

Pain Points

• Immich updates frequently and can be breaking. The project moves fast — breaking changes appear in minor versions. Always read the GitHub release notes before running docker compose pull. Never update without a current database backup.
• PostgreSQL is not standard postgres. Immich requires the pgvecto-rs extension for vector similarity search. Use the ghcr.io/immich-app/postgres image (or the official Immich-provided compose file) — a plain postgres:16 image will fail to start with migration errors.
• Machine learning is optional but memory-hungry. The ML container runs CLIP and facial recognition models that can consume 2–4 GB RAM. On memory-constrained hosts, disable it with MACHINE_LEARNING_ENABLED=false in .env; the core photo library remains fully functional without it.
• The upload directory must have sufficient space. Immich stores originals, thumbnails, video transcodes, and encoded clips all under UPLOAD_LOCATION. Plan for at least 2–3× your raw photo storage. Monitor with df -h or integrate with a monitoring stack.
• Backup strategy must cover two things: the PostgreSQL database AND the upload directory. Neither alone is sufficient. The database holds metadata, albums, faces, and user accounts; the upload directory holds the actual media. A restored database pointing at missing files — or media files with no metadata — leaves the library unusable.
• External library scanning is a separate job. Photos in an external library path are not automatically indexed. You must configure the library in the UI, mount the path as a Docker volume, and trigger a scan manually or via a cron-based docker compose exec call.

References

See references/ for:

• docker-compose-env.annotated — annotated .env and docker-compose.yml structure with hardware transcoding, external library, and backup strategy notes
• docs.md — official documentation and community links