Upstream docs: https://docs.immich.app/overview/quick-start/

Everything not listed in this document should behave the same as upstream Immich. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.

Immich is a self-hosted photo and video backup solution with automatic mobile device backup, machine learning-powered search, face recognition, and a modern web interface.

• Image and Container Runtime
• Volume and Data Layout
• Installation and First-Run Flow
• Configuration Management
• Network Access and Interfaces
• Actions (StartOS UI)
• Dependencies
• Backups and Restore
• Health Checks
• Limitations and Differences
• What Is Unchanged from Upstream
• Contributing
• Quick Reference for AI Consumers

All images are upstream unmodified. PostgreSQL uses Immich's custom image with vector extensions for similarity search.

StartOS selects the variant automatically from the GPU it detects on the host (via each variant's manifest hardwareRequirements); there is no manual picker. Only the machine-learning image differs between variants; server, postgres, and valkey are identical.

AMD GPUs — discrete only: the rocm variant is offered only to discrete AMD GPUs. ROCm's MIGraphX backend crashes during model compilation on integrated Radeon graphics (e.g. the Radeon 680M in Ryzen APUs), so those hosts get the CPU-only generic variant instead. Selection matches the GPU product name in rocm's hardwareRequirements, so a discrete card StartOS doesn't recognize also falls back to generic — sideload the -rocm s9pk manually if you need GPU ML on such a card.

NVIDIA GPUs — -nvidia flavor only: the cuda variant (and NVENC transcoding) require StartOS to be installed from a -nvidia platform flavor (x86_64-nvidia / aarch64-nvidia), which bundles the NVIDIA driver and container toolkit. On the standard or -nonfree flavors the NVIDIA driver is absent, so an NVIDIA card isn't detected — its nvidia driver never appears, so the cuda variant isn't auto-selected and machine learning falls back to the CPU (generic) variant, even with an NVIDIA card physically present.

Hardware video transcoding (NVENC, VAAPI, QSV) is available on any variant whose host has the matching GPU. After install, enable it in Immich → Administration → Settings → Video Transcoding and pick the acceleration API. Note: NVENC specifically requires the cuda variant (which enables the NVIDIA container runtime, and therefore the -nvidia flavor above); VAAPI and QSV work on any variant via StartOS /dev/dri passthrough.

Machine-learning CPU requirement: the machine-learning container requires an x86-64-v2 CPU (or any aarch64 host). On older x86 hardware that predates x86-64-v2, the machine-learning container fails to start while the server, database, and cache keep running — smart search and facial recognition are lost, but core photo management is not.

StartOS-specific files:

• store.json — PostgreSQL password, primary URL, SMTP settings, external library configurations

First-run steps:

1. Install Immich from StartOS marketplace. Install takes a few extra minutes because Immich's database schema is created during install rather than on first boot.
2. Access the web UI — it comes up immediately after install completes.
3. Register your account (first user becomes administrator)
4. Install mobile apps and configure backup
5. Optionally configure external libraries via action

StartOS reasserts the following values on every startup. Editing them in the Immich Admin UI will not persist across restarts.

The first two are enforced from the very first boot. server.externalDomain applies once your admin account exists and a URL has been chosen via the Set Primary URL action.

All other Immich settings are configured through the web interface:

• User management
• Storage templates
• Machine learning settings
• Job queues
• Server settings
• Notification preferences (after SMTP configured)

Access methods (StartOS 0.4.0):

• LAN IP with unique port
• <hostname>.local with unique port
• Tor .onion address
• Custom domains (if configured)

Mobile app connection: Use any of the above URLs in the Immich mobile app settings.

Immich embeds its external domain in public share links (albums, assets). This action lets you pick a URL from the available non-local interfaces (LAN IP, .local, Tor, custom domains). On first install the .local URL is selected by default. If the previously selected URL is removed (e.g., Tor disabled, custom domain deleted), a critical task prompts you to pick a new one.

Note: Changes apply on next restart.

Options:

• Disabled — No email notifications
• System SMTP — Use StartOS system SMTP server
• Custom — Enter your own SMTP credentials

Note: Changes apply on next restart.

Supported sources:

• File Browser — Index photos from File Browser's data volume
• Nextcloud — Index photos from a Nextcloud user's files

How it works:

1. Add a library with a name and source
2. Select File Browser or Nextcloud
3. Specify the folder path containing photos
4. Libraries are created/updated and scanned on restart

Output: Displays the new randomly generated password.

Dependencies are only needed if you configure external libraries pointing to those services.

Database: Uses pg_dump/pg_restore for PostgreSQL instead of raw volume rsync. The dump is written directly to the backup target.

Volumes backed up via rsync:

• startos volume — Configuration and credentials
• upload volume — All photos and videos

NOT included in backup:

• db volume — Not rsynced directly; database is captured via pg_dump
• model-cache volume — ML models are re-downloaded as needed

Restore behavior:

• All photos, albums, and metadata restored
• Database is rebuilt from dump via pg_restore
• User accounts preserved
• External library configurations restored (re-scan needed)

Messages:

• Success: "The web interface is ready"
• Error: "The web interface is not ready"

1. External libraries limited to StartOS services — Can only index from File Browser or Nextcloud (not arbitrary filesystem paths)
2. SMTP via action — Configure through StartOS action rather than Immich web UI
3. No custom upload paths — Upload location is fixed
4. Upstream version-check banner suppressed — StartOS manages Immich updates, so newVersionCheck.enabled is forced to false in the system config on every startup to hide the "new version available" modal.
5. Immich's internal database backup disabled — backup.database.enabled is forced to false because StartOS already dumps the database via pg_dump during its backup flow.
6. External domain managed via action — server.externalDomain is set to the URL selected in the Set Primary URL action; editing it in the Immich Admin UI does not persist.

• Full photo/video backup and management
• Mobile app automatic backup (iOS, Android, F-Droid)
• Machine learning features (face recognition, object detection, smart search)
• Album management and sharing
• Timeline and map views
• Memories and favorites
• User management and permissions
• Partner sharing
• External library scanning (via StartOS services)
• All web UI features
• REST API

See CONTRIBUTING.md for build instructions and development workflow.

package_id: immich
images:
  immich-server: ghcr.io/immich-app/immich-server
  immich-ml: ghcr.io/immich-app/immich-machine-learning
  postgres: ghcr.io/immich-app/postgres
  valkey: valkey/valkey
architectures: [x86_64, aarch64] # GPU variants (cuda, rocm, openvino) are x86_64 only
variants: [generic, cuda, rocm, openvino]
volumes:
  upload: /usr/src/app/upload
  db: /var/lib/postgresql/data
  model-cache: /cache
  startos: (StartOS state)
ports:
  ui: 2283
dependencies:
  filebrowser: optional (external library source, >= 2.62.2)
  nextcloud: optional (external library source, >= 32.0.7)
startos_managed_env_vars:
  - DB_HOSTNAME
  - DB_USERNAME
  - DB_PASSWORD
  - DB_DATABASE_NAME
  - REDIS_HOSTNAME
  - IMMICH_MACHINE_LEARNING_URL
  - POSTGRES_DB
  - POSTGRES_USER
  - POSTGRES_PASSWORD
  - POSTGRES_INITDB_ARGS
actions:
  - configure-smtp (enabled, any)
  - set-primary-url (enabled, any)
  - external-libraries (enabled, any)
  - reset-admin-password (enabled, only-running)
startos_forced_system_config:
  newVersionCheck.enabled: false
  backup.database.enabled: false
  server.externalDomain: <primary URL from set-primary-url action>
health_checks:
  - pg_isready (postgres)
  - valkey-cli ping (valkey)
  - port_listening: 3003 (immich-ml)
  - port_listening: 2283 (immich-server, 40s grace)
backup_strategy: pg_dump (db) + volume rsync (startos, upload)
excluded_from_backup:
  - model-cache (re-downloaded as needed)
not_available:
  - Arbitrary external library paths
  - Custom upload paths