# Project pack: Immich @ b9269f8

Facts about **Immich** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Immich is a private home for your family's photos and videos. The phone app backs up new pictures automatically, and the website lets you browse them on a timeline, a map or by the people in them. Share albums with relatives, see "on this day" memories and search for things like "beach" or "dog". It runs on your own computer or server, so your pictures are not stored with a big tech company.

## Version and source
- Repository: https://github.com/immich-app/immich
- Pinned commit: `b9269f873982c9b1c0f9267aefad8b8b9eacb7d9`. Use exactly this version.
- Get it: `git clone https://github.com/immich-app/immich immich && cd immich && git checkout b9269f873982c9b1c0f9267aefad8b8b9eacb7d9`
- Or download a zip: https://github.com/immich-app/immich/archive/b9269f873982c9b1c0f9267aefad8b8b9eacb7d9.zip
- Official docs: https://docs.immich.app
- Live demo: https://demo.immich.app (email: demo@immich.app / password: demo). Public shared demo. Don't upload anything private.
- Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (not just your own household), you must offer them your source code under the same licence. Private family use has no extra obligations.

## Running it
- Easiest: mkdir immich-app && cd immich-app && wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml && wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env && docker compose up -d # edit UPLOAD_LOCATION and DB_PASSWORD in .env first, then open http://localhost:2283
- Needs: Docker with Docker Compose (the official Docker Engine, not an old distro package), At least 6 GB RAM and 2 CPU cores (8 GB and 4 cores recommended), For development, mise (installs Node, pnpm and the other tools)
- Develop: `cp docker/example.env docker/.env && mise x -- pnpm i && mise dev   # website on :3000 with hot reload`
- Test: `mise //server:test && mise //web:test`
- Check/lint: `mise //server:lint && mise //web:lint && mise //server:check && mise //web:check`
- Stack: typescript, svelte, dart, python (NestJS, Kysely, BullMQ, SvelteKit, Tailwind CSS, Flutter). Difficulty for a non-developer with an AI: **advanced**. A large project with four parts: the NestJS server, the SvelteKit website, the Flutter phone app and a Python machine-learning service. Theme, sharing and storage layout are settings. Code changes need the full Docker development stack and usually touch both server and website, with an OpenAPI client generated between them.

## Customisation points (settings → extend → code)
- **theme-and-custom-css** [settings]: Change colours, fonts and small layout details with CSS, without rebuilding anything. → `Administration → Settings → Theme Settings (custom CSS); docs/docs/administration/system-settings.md`
- **storage-template** [settings]: Choose how files are named and foldered on disk, e.g. year/month/event. → `Administration → Settings → Storage Template (docs/docs/administration/storage-template.mdx)`
- **sharing-and-users** [settings]: Give each family member an account, share albums with grandparents, or send a public link. → `Shared albums, partner sharing and shared links (docs/docs/features/sharing.md, partner-sharing.md)`
- **notifications-and-welcome** [settings]: Email set-up, the wording of album invitation emails and the login page message. → `Administration → Settings → Notification Settings / Notification Templates / Server Settings → Welcome Message`
- **api-and-cli** [extend]: Bulk upload old photo folders, build a digital photo frame, or sync with other tools. → `REST API with API keys (docs/docs/api.md); immich CLI (docs/docs/features/command-line-interface.md)`
- **external-libraries** [extend]: Show photos that already live in a folder on your server without copying them. → `Administration → External Libraries (docs/docs/features/libraries.md)`
- **web-pages** [code]: New views in the website, e.g. a slideshow page for a kitchen screen. → `web/src/routes/(user)/**, web/src/lib/components/**, text in i18n/en.json`
- **server-features** [code]: New data or behaviour on the server. Regenerate the OpenAPI client after API changes. → `server/src/controllers/ → server/src/services/ (e.g. memory.service.ts, album.service.ts) → server/src/schema/migrations/`
- **email-templates** [code]: The look of album invitation, album update and welcome emails. → `server/src/emails/*.email.tsx`

## Must keep working
- Original photos and videos in the upload folder. Never let code move or delete originals without a backup.
- Privacy between users. One person's library, locked folder and partner sharing must stay private.
- Phone backup. The mobile app talks to the server API, so don't change existing endpoints in ways that break older apps.
- Database changes need a migration in server/src/schema/migrations/.

## Staying updatable
Custom CSS, the storage template, sharing, the API and the CLI cover most family needs without a fork. Immich's CONTRIBUTING.md asks people not to open pull requests generated with an AI, so keep code changes in your own copy.

## Data, costs and safety
- Personal data: **yes**. Stored in: Original photos and videos in UPLOAD_LOCATION; albums, people, faces and metadata in PostgreSQL (DB_DATA_LOCATION). Photos are irreplaceable. Follow a 3-2-1 backup plan, back up both the upload folder and the database (Immich makes automatic database dumps), and test a restore before changing code or upgrading.
- Service: Machine learning container (runs locally) (optional, free (uses your own hardware)): Face recognition, smart search ("photos of a red car") and duplicate detection. Included in the default compose file.
- Service: Email (SMTP) (optional, free with most providers): Album invitations and other email notifications.
- Service: OAuth / single sign-on provider (optional, free (self-hosted) or varies): Log in with an existing account such as Authelia, Authentik or Google.
- Setting `UPLOAD_LOCATION`: Folder on your computer where photos and videos are stored.
- Setting `DB_DATA_LOCATION`: Folder for the database files. Must be a local disk, not a network share.
- Setting `DB_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password. Change it to a random string of letters and numbers. Never paste it into an AI chat.
- Setting `TZ`: Your time zone (e.g. Europe/London).
- Setting `IMMICH_VERSION`: Which Immich release to run. Pin a version to avoid surprise upgrades.
- Photos often show children, homes and locations. Think before putting Immich on the open internet; use a reverse proxy with HTTPS.
- Shared links can be opened by anyone who has them. Add a password or expiry date.
- Keep at least one backup copy that Immich cannot delete.

---

# Customising Immich

Immich is a big project (server, website, phone app and a machine-learning service). **Most family adaptations are settings or use the API.** Exhaust levels 1 and 2 before touching code.

## Level 1: Settings (no code)
- **Colours and look:** Administration → Settings → Theme Settings → *Custom CSS*. Takes effect without a rebuild.
- **Login page text:** Administration → Settings → Server Settings → *Welcome Message*.
- **Family accounts:** Administration → Users. Give each person their own account and storage quota.
- **Sharing:** shared albums (invite family members), *partner sharing* (see a partner's whole timeline) and *shared links* (anyone with the link, optional password and expiry). See `docs/docs/features/sharing.md` and `docs/docs/features/partner-sharing.md`.
- **Folders on disk:** Administration → Settings → *Storage Template*. Enable it, pick a pattern such as `{{y}}/{{MM}}/{{filename}}`, then run the *Storage Template Migration* job to move existing files. See `docs/docs/administration/storage-template.mdx`.
- **Emails:** Administration → Settings → Notification Settings (SMTP) and Notification Templates (wording).
- **Smart features:** Administration → Settings → Machine Learning (face recognition, smart search, duplicate detection).

## Level 2: Extend (no fork)
- **REST API** with an API key (Account settings → API Keys). See `docs/docs/api.md`. Good for a photo frame, a weekly "new photos" message or syncing with other tools.
- **Immich CLI** for bulk uploads from old drives: `docs/docs/features/command-line-interface.md`.
- **External libraries:** show photos that already sit in a folder on your server without copying them: `docs/docs/features/libraries.md`.
- **Workflows:** automations built on server plugins (`web/src/routes/(user)/workflows`, `server/src/services/workflow.service.ts`). Newer feature; check the docs for your version.

## Level 3: Code
Read upstream `CONTRIBUTING.md` and `docs/docs/developer/setup.md` first.

| Change | Where |
|---|---|
| New page or view in the website | `web/src/routes/(user)/**` (e.g. `memories/`, `albums/`, `photos/`), components in `web/src/lib/components/` |
| Text and translations | `i18n/en.json` (shared by website and phone app) |
| New endpoint | `server/src/controllers/` → `server/src/services/` (e.g. `memory.service.ts`, `album.service.ts`) |
| New data | `server/src/schema/` + a migration in `server/src/schema/migrations/` (see `docs/docs/developer/database-migrations.md`) |
| Email look | `server/src/emails/*.email.tsx` |
| Phone app | `mobile/` (Flutter). Only if you really need it; it is a separate build. |

After changing the API, regenerate the OpenAPI client with `mise //:open-api`.

## Running locally
- **Just use it:**
  1. `mkdir immich-app && cd immich-app`
  2. Download `docker-compose.yml` and `example.env` (saved as `.env`) from the latest release.
  3. Edit `UPLOAD_LOCATION` and `DB_PASSWORD` in `.env`.
  4. `docker compose up -d`, then open http://localhost:2283 and create the admin account.
- **Develop:**
  1. Install mise, then run `mise trust` and `mise install` in the repo.
  2. `cp docker/example.env docker/.env` and set `UPLOAD_LOCATION`.
  3. `mise x -- pnpm i`, then `mise dev`.
  4. Open http://localhost:3000.
  - Website-only work can use the public demo as the server: `mise //web:start-demo`.
- **Check:** `mise //server:test`, `mise //web:test`, `mise //server:lint`, `mise //web:lint`, `mise //server:check`, `mise //web:check`.

## Pitfalls
- Back up the upload folder **and** the database before any upgrade or code change. Test that the backup restores.
- Immich needs at least 6 GB of RAM. Small single-board computers may struggle with the machine-learning container.
- The database must be on a local disk, not a network share.
- The phone app and server must stay compatible. Don't rename or remove existing API fields.
- Upstream asks for no AI-generated pull requests. Keep personal changes in your own fork.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/immich/b9269f8/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/immich/b9269f8/SKILL.md)