The Problem

Immich solves the problem of self-hosting a Google Photos alternative. Most open-source photo managers either lack mobile backup, miss machine-learning search, or require complex multi-service setups. Immich packages a full stack—mobile app, web UI, API server, and ML pipeline—into a single Docker deployment.

What This Does

This repository is a fork of immich-app/immich (112k stars) with zero stars of its own. It contains the complete Immich platform: a Dart/Flutter mobile app (mobile/), a Svelte web client (web/), a NestJS API server (server/), and a Python machine-learning service (machine-learning/). The feature set covers auto-backup, album sharing, EXIF metadata, face recognition, CLIP-based search, and OAuth.

The repo also includes supporting projects: a CLI (cli/), OpenAPI specs (open-api/), end-to-end tests (e2e/), and a 297-file documentation site (docs/). This is a portfolio of 10 self-contained projects, not a single codebase.

How It Is Wired

Execution starts at mobile/lib/main.dart for the Flutter app, server/ for the NestJS API, and machine-learning/immich_ml/main.py for the Python service. The server exposes REST endpoints that the web and mobile clients consume; the machine-learning service runs as a separate container and communicates with the server for face detection and object search. The cli/src/index.ts provides a TypeScript command-line interface for server administration.

The server is the hub: it owns database access, authentication, and API routes. The web client is a Svelte app (402 Svelte files) that talks exclusively to the server. The mobile app (1,160 Dart files, though only 3 are actual code—the rest are generated bindings) also routes through the server. The machine-learning service has the widest blast radius because search and face features depend on it, but it is isolated as a separate container.

Docker Compose (docker/docker-compose.dev.yml) wires everything together: server, web, machine-learning, Redis, and Postgres. The Makefile at the root orchestrates builds and development tasks.

How To Use It

Setup: Clone with git clone https://github.com/moses-y/immich. The repo uses pnpm for package management and Docker for deployment.

Configuration: Copy deployment/.env to .env and set credentials. The server requires Postgres, Redis, and the machine-learning container.

Running it: Follow the README's Docker Compose instructions. The Makefile provides dev targets. For development, run the server from server/, the web client from web/, and the mobile app via Flutter from mobile/.

git clone https://github.com/moses-y/immich
cd immich
docker compose -f docker/docker-compose.dev.yml up -d

Real-World Use

A family runs Immich on a home NAS with a 4TB volume. The mobile app auto-backups photos in the background. The ML service indexes faces and objects, enabling natural-language search ("beach vacation 2023"). The web UI serves as the desktop gallery. The CLI handles batch operations like user management from a script.

Code Health & Issues

Static analysis found 8 issues, 2 critical:

  • Critical - Committed credentials in deployment/.env (contains CLOUDFLARE_API_TOKEN). Rotate, remove from index, commit a keys-only example.
  • Critical - Secrets in fork-triggerable workflow .github/workflows/docs-deploy.yml (PUSH_O_MATIC_APP_ID, PUSH_O_MATIC_APP_KEY). Move secret-using steps to a workflow_run job.
  • High - Tracked .env file that the app loads at boot. Remove and rotate.
  • High - .github/workflows/build-mobile.yml line 291 discards exit codes, so failures report green.
  • Medium - No dependency vulnerability scan in CI.
  • Medium - No pre-commit secret gate.
  • Medium - cli/Dockerfile runs as root; add a non-root USER.
  • Low - Workflow jobs lack timeout-minutes.

CI runs Travis CI, tests exist (404 files), and a license is present.

The Bottom Line

This is a faithful fork of a well-maintained, production-grade project. The codebase is substantial and the architecture is sound. The committed credentials and fork-triggerable secrets are real problems that must be fixed before any public use. For someone wanting to run Immich or study a full-stack self-hosted app, this works—after rotating those keys.