The Problem
Self-hosted photo management has long meant choosing between Google Photos-like polish and full control over your data. Immich addresses the gap: a feature-complete photo and video platform (auto-backup, facial recognition, search, multi-user) that runs entirely on your own infrastructure, with no per-user cloud costs or vendor lock-in.
What This Does
Immich is a full-stack photo management platform. The repo contains the server, web, and mobile clients (mobile lives in the mobile/ directory), a CLI (cli/src/index.ts), Docker deployment configs (docker/docker-compose.yml, docker/docker-compose.prod.yml), and Terraform infrastructure for the project's own docs site (deployment/modules/cloudflare/). The CLI handles asset upload, authentication, and server info commands.
The docs/ folder is substantial (76 files) and covers installation, administration, and developer setup. The design/ folder holds branding assets. CI/CD is extensive: 20+ GitHub Actions workflows handle builds, tests, static analysis, and releases.
How To Use It
Setup: The canonical install path is Docker Compose. Copy docker/example.env to .env, edit it, then run docker compose -f docker/docker-compose.yml up -d. A Makefile exists with common targets. Configuration: Environment variables live in .env (modeled on docker/example.env). Key settings include database credentials, JWT secrets, and upload storage paths. For development, docker/docker-compose.dev.yml spins up backing services. Running it: For production, the Docker containers run the server and web UI. The CLI is a separate TypeScript project (cli/) built with vite; after npm install and npm run build, run ./cli/bin/immich to upload assets or manage a server.
Production
cp docker/example.env .env edit .env with your secrets and paths docker compose -f docker/docker-compose.yml up -d
CLI (from cli/ directory)
npm install npm run build ./bin/immich login --server https://photos.example.com --key YOURAPIKEY ./bin/immich upload /path/to/photos
Real-World Use
A small team or family runs Immich on a home server with a 4TB NAS volume. The server handles auto-backup from family phones, deduplication, and facial recognition. The admin uses the web UI for user management and storage quotas. The CLI is scripted in a cron job to sync an external photography archive weekly. OAuth is configured against a self-hosted Authentik instance for single sign-on (documented in docs/docs/administration/oauth.md).
Code Health & Issues
High - Potential secrets committed - deployment/.env exists in the repo. Verify it contains no real credentials; if it does, rotate and remove immediately. Med - Non-reproducible builds - .github/package.json and cli/package.json lack lockfiles. Dependencies can drift between installs. Add pnpm-lock.yaml or package-lock.json. Low - Sparse test coverage - Only 4 test files exist (cli/src/commands/asset.spec.ts, cli/src/utils.spec.ts, plus two others). For a project this size, the server and web codebases appear untested. Low - Binary files in version control - design/.DSStore and .webp/.png screenshots are committed. Fine for a docs repo, but .DSStore should be gitignored.
The CI/CD setup is thorough (lint, typecheck, tests, CodeQL, Docker builds), and the project has a clear license (AGPLv3), contributing guide, and security policy. The core risk is the deployment/.env file and the missing lockfiles.
The Bottom Line
Immich is a mature, actively maintained self-hosted photo platform with serious feature depth and solid documentation. It is well-suited for anyone wanting a Google Photos alternative without the cloud. The main caveats are the AGPLv3 license (relevant for commercial use) and the need to verify the deployment/.env file before trusting the repo. Worth deploying for personal or small-team use.