### Quick-start DevPod setup Source: https://docs.immich.app/developer/devcontainers Commands to clone the repository, configure the DevPod Docker provider, build the development image, and start the container. ```bash # Step 1: Clone the Repository git clone https://github.com/immich-app/immich.git cd immich # Step 2: Prepare DevPod (if you haven't already) devpod provider add docker devpod provider use docker # Step 3: Build 'immich-server-dev' docker image first manually docker build -f server/Dockerfile.dev -t immich-server-dev . # Step 4: Now you can start devcontainer devpod up . ``` -------------------------------- ### Execute Immich installation script Source: https://docs.immich.app/install/script Runs the installation script from the main branch to download configuration files and start containers. Requires Linux and pre-installed Docker. ```bash curl -o- https://raw.githubusercontent.com/immich-app/immich/main/install.sh | bash ``` -------------------------------- ### Start Development Server Source: https://docs.immich.app/developer/setup Launches the development environment with hot-reloading enabled. ```bash mise dev ``` -------------------------------- ### Create and navigate to the installation directory Source: https://docs.immich.app/install/docker-compose Initialize a new directory for the Immich deployment and move into it. ```bash mkdir ./immich-app cd ./immich-app ``` -------------------------------- ### Install Immich CLI via NPM Source: https://docs.immich.app/features/command-line-interface Global installation of the Immich CLI package using NPM. ```bash npm i -g @immich/cli ``` -------------------------------- ### Run Server Unit Tests Source: https://docs.immich.app/developer/testing Executes unit tests for the server. Ensure dependencies are installed once using the install command first. ```bash mise //server:test ``` -------------------------------- ### Clone the Immich Repository Source: https://docs.immich.app/developer/devcontainers Download the source code to your local machine to begin the setup process. ```bash git clone https://github.com/immich-app/immich.git cd immich ``` -------------------------------- ### Start E2E Test Environment Source: https://docs.immich.app/developer/testing Initializes the production-like environment required for end-to-end testing. ```bash mise e2e ``` -------------------------------- ### Print Immich Version Source: https://docs.immich.app/administration/server-commands Displays the currently installed version of Immich. ```bash immich-admin version v1.129.0 ``` -------------------------------- ### Launch Flutter Widget Previewer Source: https://docs.immich.app/developer/setup Starts the isolated component previewer for the mobile UI package. ```bash cd mobile/packages/ui flutter widget-preview start ``` -------------------------------- ### Start Immich with pgAdmin Source: https://docs.immich.app/guides/database-gui Use the docker compose command to launch both the Immich and pgAdmin services simultaneously. ```bash docker compose -f docker-compose.yml -f docker-compose-pgadmin.yml up ``` -------------------------------- ### Default environment variable configuration Source: https://docs.immich.app/install/docker-compose Example content for the .env file used to configure Immich storage locations, database credentials, and versioning. ```bash # You can find documentation for all the supported env variables at https://docs.immich.app/install/environment-variables # The location where your uploaded files are stored UPLOAD_LOCATION=./library # The location where your database files are stored. Network shares are not supported for the database DB_DATA_LOCATION=./postgres # To set a timezone, uncomment the next line and change Etc/UTC to a TZ identifier from this list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List # TZ=Etc/UTC # The Immich version to use. You can pin this to a specific version like "v2.1.0" IMMICH_VERSION=v3 # Connection secret for postgres. You should change it to a random password # Please use only the characters `A-Za-z0-9`, without special characters or spaces DB_PASSWORD=postgres # The values below this line do not need to be changed ################################################################################### DB_USERNAME=postgres DB_DATABASE_NAME=immich ``` -------------------------------- ### Immich Configuration JSON Structure Source: https://docs.immich.app/install/config-file Example of the JSON structure used for Immich configuration settings. ```json "username": "" } } }, "oauth": { "autoLaunch": false, "autoRegister": true, "buttonText": "Login with OAuth", "clientId": "", "clientSecret": "", "defaultStorageQuota": null, "enabled": false, "issuerUrl": "", "endSessionEndpoint": "", "mobileOverrideEnabled": false, "mobileRedirectUri": "", "profileSigningAlgorithm": "none", "roleClaim": "immich_role", "scope": "openid email profile", "signingAlgorithm": "RS256", "storageLabelClaim": "preferred_username", "storageQuotaClaim": "immich_quota", "timeout": 30000, "tokenEndpointAuthMethod": "client_secret_post" }, "passwordLogin": { "enabled": true }, "reverseGeocoding": { "enabled": true }, "server": { "externalDomain": "", "loginPageMessage": "", "publicUsers": true }, "storageTemplate": { "enabled": false, "hashVerificationEnabled": true, "template": "{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}" }, "templates": { "email": { "albumInviteTemplate": "", "albumUpdateTemplate": "", "welcomeTemplate": "" } }, "theme": { "customCss": "" }, "trash": { "days": 30, "enabled": true }, "user": { "deleteDelay": 7 } } ``` -------------------------------- ### Inline hardware acceleration in docker-compose.yml Source: https://docs.immich.app/features/hardware-transcoding Example of adding device mapping directly to the immich-server service for platforms not supporting multiple compose files. ```yaml immich-server: container_name: immich_server image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release} # Note the lack of an `extends` section devices: - /dev/dri:/dev/dri volumes: ... ``` -------------------------------- ### Example Structured JSON Logs Source: https://docs.immich.app/features/monitoring Sample output showing the structure of JSON logs generated by Immich when enabled. ```json {"level":"log","pid":36,"timestamp":1766533331507,"message":"Initialized websocket server","context":"WebsocketRepository"} {"level":"warn","pid":48,"timestamp":1766533331629,"message":"Unable to open /build/www/index.html, skipping SSR.","context":"ApiService"} {"level":"error","pid":36,"timestamp":1766533331690,"message":"Failed to load plugin immich-core:","context":"Error"} ``` -------------------------------- ### Start SSH Agent for Git Authentication Source: https://docs.immich.app/developer/devcontainers Commands to initialize the SSH agent and add your private key on the host machine for use within the Dev Container. ```bash eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_rsa # or your key path ``` -------------------------------- ### Switch to VectorChord-only image Source: https://docs.immich.app/install/upgrading Use this image variant for a leaner database installation after completing the migration to VectorChord. ```text ghcr.io/immich-app/postgres:14-vectorchord0.4.3 ``` -------------------------------- ### Migrate data directories for fresh installation Source: https://docs.immich.app/administration/backup-and-restore Move existing data directories to the new UPLOAD_LOCATION when setting up a fresh Immich instance. ```bash /my-broken-instance/media/backups -> /a-brand-new-instance/data/backups /my-broken-instance/media/encoded-video -> /a-brand-new-instance/data/encoded-video /my-broken-instance/media/library -> /a-brand-new-instance/data/library /my-broken-instance/media/profile -> /a-brand-new-instance/data/profile /my-broken-instance/media/thumbs -> /a-brand-new-instance/data/thumbs /my-broken-instance/media/upload -> /a-brand-new-instance/data/upload ``` -------------------------------- ### Configure Immich Machine Learning Service with Inline GPU Support Source: https://docs.immich.app/features/ml-hardware-acceleration Example of configuring the immich-machine-learning service directly within a single Docker Compose file for platforms that do not support multiple files. ```yaml immich-machine-learning: container_name: immich_machine_learning # Note the `-cuda` at the end image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-cuda # Note the lack of an `extends` section deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: - gpu volumes: - model-cache:/cache env_file: - .env restart: always ``` -------------------------------- ### Example error message for outdated Docker Compose Source: https://docs.immich.app/install/docker-compose Error output encountered when using an incompatible version of Docker Compose. ```text The Compose file './docker-compose.yml' is invalid because: 'name' does not match any of the regexes: '^x-' ``` -------------------------------- ### Restore Immich Database via Linux Command Line Source: https://docs.immich.app/administration/backup-and-restore Restores a database dump to a fresh Immich installation using docker compose and psql. ```bash docker compose down -v # CAUTION! Deletes all Immich data to start from scratch ## Uncomment the next line and replace DB_DATA_LOCATION with your Postgres path to permanently reset the Postgres database # rm -rf DB_DATA_LOCATION # CAUTION! Deletes all Immich data to start from scratch docker compose pull # Update to latest version of Immich (if desired) docker compose create # Create Docker containers for Immich apps without running them docker start immich_postgres # Start Postgres server sleep 10 # Wait for Postgres server to start up # Check the database user if you deviated from the default # Replace with the database username - usually postgres unless you have changed it. # Replace with the database name - usually immich unless you have changed it. gunzip --stdout "/path/to/backup/dump.sql.gz" \ | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \ | docker exec -i immich_postgres psql --dbname= --username= --single-transaction --set ON_ERROR_STOP=on # Restore Backup docker compose up -d # Start remainder of Immich apps ``` -------------------------------- ### Conditional Storage Template Source: https://docs.immich.app/administration/storage-template A template example using conditional logic to organize assets into album folders or an 'Other' folder if no album is present. ```text {{y}}/{{#if album}}{{album}}{{else}}Other{{/if}}/{{MM}}/{{filename}} ``` -------------------------------- ### Initialize Borg Repository Source: https://docs.immich.app/guides/template-backup-script Commands to set up local and remote Borg repositories for Immich backups. ```bash UPLOAD_LOCATION="/path/to/immich/directory" # Immich database location, as set in your .env file BACKUP_PATH="/path/to/local/backup/directory" mkdir "$UPLOAD_LOCATION/database-backup" borg init --encryption=none "$BACKUP_PATH/immich-borg" ## Remote set up REMOTE_HOST="remote_host@IP" REMOTE_BACKUP_PATH="/path/to/remote/backup/directory" borg init --encryption=none "$REMOTE_HOST:$REMOTE_BACKUP_PATH/immich-borg" ``` -------------------------------- ### Download configuration files Source: https://docs.immich.app/install/docker-compose Fetch the required docker-compose.yml and example.env files from the official repository. ```bash wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml ``` ```bash wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env ``` -------------------------------- ### Run E2E Tests Source: https://docs.immich.app/developer/testing Executes the end-to-end test suite after the environment has been started. ```bash mise //e2e:test ``` -------------------------------- ### Run additional development commands Source: https://docs.immich.app/developer/devcontainers Generate OpenAPI specifications and SDKs, or synchronize the database schema using mise. ```bash # API generation mise //:open-api # Generate OpenAPI specs mise //:open-api-typescript # Generate TypeScript SDK mise //:open-api-dart # Generate Dart SDK # Database mise //server:sql # Sync database schema ``` -------------------------------- ### Display Immich CLI Help Source: https://docs.immich.app/features/command-line-interface View the main help menu and available global options for the Immich CLI. ```bash $ immich Usage: immich [options] [command] Command line interface for Immich Options: -V, --version output the version number -d, --config-directory Configuration directory where auth.yml will be stored (default: "~/.config/immich/", env: IMMICH_CONFIG_DIR) -u, --url [url] Immich server URL (env: IMMICH_INSTANCE_URL) -k, --key [key] Immich API key (env: IMMICH_API_KEY) -h, --help display help for command Commands: login|login-key Login using an API key logout Remove stored credentials server-info Display server information upload [options] [paths...] Upload assets help [command] display help for command ``` -------------------------------- ### Uninstall Legacy Immich CLI Source: https://docs.immich.app/features/command-line-interface Remove the deprecated CLI package before installing the current version. ```bash npm uninstall -g immich ``` -------------------------------- ### Initialize database without superuser Source: https://docs.immich.app/administration/postgres-standalone Execute these commands at the psql prompt to prepare the database for Immich when superuser access is restricted. ```sql CREATE DATABASE ; \c BEGIN; ALTER DATABASE OWNER TO ; CREATE EXTENSION vchord CASCADE; CREATE EXTENSION earthdistance CASCADE; COMMIT; ``` -------------------------------- ### Get owner info by asset ID Source: https://docs.immich.app/guides/database-queries Retrieves user details for the owner of a specific asset. ```sql SELECT "user".* FROM "user" JOIN "asset" ON "user"."id" = "asset"."ownerId" WHERE "asset"."id" = 'fa310b01-2f26-4b7a-9042-d578226e021f'; ``` -------------------------------- ### Backup database via command line Source: https://docs.immich.app/administration/backup-and-restore Use pg_dump to create a compressed SQL backup of the Immich database container. ```bash # Replace with the database username - usually postgres unless you have changed it. # Replace with the database name - usually immich unless you have changed it. docker exec -t immich_postgres pg_dump --clean --if-exists --dbname= --username= | gzip > "/path/to/backup/dump.sql.gz" ``` -------------------------------- ### Remove pgvecto.rs references Source: https://docs.immich.app/administration/postgres-standalone Execute these commands to drop existing indices and revert column types before installing VectorChord. ```sql DROP INDEX IF EXISTS clip_index; DROP INDEX IF EXISTS face_index; ALTER TABLE smart_search ALTER COLUMN embedding SET DATA TYPE real[]; ALTER TABLE face_search ALTER COLUMN embedding SET DATA TYPE real[]; ``` -------------------------------- ### Retrieve embedding dimension size Source: https://docs.immich.app/administration/postgres-standalone Run this query while pgvecto.rs is installed to determine the dimension size of the embedding column. ```sql SELECT atttypmod as dimsize FROM pg_attribute f JOIN pg_class c ON c.oid = f.attrelid WHERE c.relkind = 'r'::char AND f.attnum > 0 AND c.relname = 'smart_search'::text AND f.attname = 'embedding'::text; ``` -------------------------------- ### Update VectorChord extension Source: https://docs.immich.app/administration/postgres-standalone Run these commands after installing a new version of VectorChord to update the extension and reindex the database. ```sql ALTER EXTENSION vchord UPDATE; REINDEX INDEX face_index; REINDEX INDEX clip_index; ``` -------------------------------- ### Redis Sentinel Configuration JSON Source: https://docs.immich.app/install/environment-variables Example JSON structure for Redis Sentinel configuration before base64 encoding for the REDIS_URL variable. ```json { "sentinels": [ { "host": "redis-sentinel-node-0", "port": 26379 }, { "host": "redis-sentinel-node-1", "port": 26379 }, { "host": "redis-sentinel-node-2", "port": 26379 } ], "name": "redis-sentinel" } ``` -------------------------------- ### Connect to Database Source: https://docs.immich.app/guides/database-queries Command to connect to the Immich PostgreSQL database via the container. ```bash docker exec -it immich_postgres psql --dbname= --username= ``` -------------------------------- ### View Upload Command Options Source: https://docs.immich.app/features/command-line-interface Review specific flags and arguments available for the upload command, including environment variable support. ```bash Usage: immich upload [paths...] [options] Upload assets Arguments: paths One or more paths to assets to be uploaded Options: -r, --recursive Recursive (default: false, env: IMMICH_RECURSIVE) -i, --ignore Pattern to ignore (env: IMMICH_IGNORE_PATHS) -h, --skip-hash Don't hash files before upload (default: false, env: IMMICH_SKIP_HASH) -H, --include-hidden Include hidden folders (default: false, env: IMMICH_INCLUDE_HIDDEN) -a, --album Automatically create albums based on folder name (default: false, env: IMMICH_AUTO_CREATE_ALBUM) -A, --album-name Add all assets to specified album (env: IMMICH_ALBUM_NAME) --visibility Set the visibility of uploaded assets (choices: "archive", "timeline", "hidden", "locked", env: IMMICH_VISIBILITY) -n, --dry-run Don't perform any actions, just show what will be done (default: false, env: IMMICH_DRY_RUN) -c, --concurrency Number of assets to upload at the same time (default: 4, env: IMMICH_UPLOAD_CONCURRENCY) -j, --json-output Output detailed information in json format (default: false, env: IMMICH_JSON_OUTPUT) --delete Delete local assets after upload (env: IMMICH_DELETE_ASSETS) --delete-duplicates Delete local assets that are duplicates (already exist on server) (env: IMMICH_DELETE_DUPLICATES) --no-progress Hide progress bars (env: IMMICH_PROGRESS_BAR) --watch Watch for changes and upload automatically (default: false, env: IMMICH_WATCH_CHANGES) --help display help for command ``` -------------------------------- ### Troubleshoot ENOSPC file watcher error Source: https://docs.immich.app/features/libraries Example of the error log encountered when the system limit for file watchers is reached. ```text ERROR [LibraryService] Library watcher for library c69faf55-f96d-4aa0-b83b-2d80cbc27d98 encountered error: Error: ENOSPC: System limit for number of file watchers reached, watch '/media/photo.jpg' ``` -------------------------------- ### Connect Web to Remote Backend Source: https://docs.immich.app/developer/setup Commands to run the web development server against a remote backend instance. ```bash IMMICH_SERVER_URL=https://demo.immich.app/ mise //web:start ``` ```bash mise //web:start-demo ``` ```powershell $env:IMMICH_SERVER_URL = "https://demo.immich.app/" mise //web:start ``` -------------------------------- ### Authelia OAuth Configuration Source: https://docs.immich.app/administration/oauth Example configuration for integrating Authelia with Immich, including optional storage quota mapping via LDAP attributes. ```yaml authentication_backend: ldap: # The LDAP server configuration goes here. # See: https://www.authelia.com/c/ldap attributes: extra: immichquota: # The attribute name from LDAP name: 'immich_quota' multi_valued: false value_type: 'integer' identity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. ## See: https://www.authelia.com/c/oidc claims_policies: immich_policy: custom_claims: immich_quota: attribute: 'immich_quota' scopes: immich_scope: claims: - 'immich_quota' clients: - client_id: 'immich' client_name: 'Immich' # https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng' public: false require_pkce: false redirect_uris: - 'https://example.immich.app/auth/login' - 'https://example.immich.app/user-settings' - 'app.immich:///oauth-callback' scopes: - 'openid' - 'profile' - 'email' - 'immich_scope' claims_policy: 'immich_policy' response_types: - 'code' grant_types: - 'authorization_code' id_token_signed_response_alg: 'RS256' userinfo_signed_response_alg: 'RS256' token_endpoint_auth_method: 'client_secret_post' ``` -------------------------------- ### Launch Dev Container via CLI Source: https://docs.immich.app/developer/devcontainers Use the DevContainer CLI to initialize the development environment from the terminal. ```bash # Using the DevContainer CLI devcontainer up --workspace-folder . ``` -------------------------------- ### Configure hardware acceleration in immich.json Source: https://docs.immich.app/features/hardware-transcoding Use the accel option to specify the hardware backend and enable hardware decoding. ```json { "ffmpeg": { "accel": "qsv", "accelDecode": true } } ``` -------------------------------- ### List Docker Containers Source: https://docs.immich.app/guides/docker-help Use these commands to view the status of running or all containers. ```bash docker ps # see a list of running containers docker ps -a # see a list of running and stopped containers ``` -------------------------------- ### Verify system mount folder check error output Source: https://docs.immich.app/administration/system-integrity Example of the error log generated when the system fails to detect expected .immich marker files in storage directories. ```text Verifying system mount folder checks (enabled=true) ... ENOENT: no such file or directory, open 'upload/encoded-video/.immich' ``` -------------------------------- ### Query Assets by Metadata Source: https://docs.immich.app/guides/database-queries Queries for filtering assets based on live photo status, descriptions, or file size. ```sql SELECT * FROM "asset" WHERE "livePhotoVideoId" IS NOT NULL; ``` ```sql SELECT "asset".*, "asset_exif"."description" FROM "asset_exif" JOIN "asset" ON "asset"."id" = "asset_exif"."assetId" WHERE TRIM("asset_exif"."description") <> ''; -- all files with a description SELECT "asset".*, "asset_exif"."description" FROM "asset_exif" JOIN "asset" ON "asset"."id" = "asset_exif"."assetId" WHERE "asset_exif"."description" ILIKE '%string to match%'; -- search by string ``` ```sql SELECT "asset".* FROM "asset_exif" LEFT JOIN "asset" ON "asset"."id" = "asset_exif"."assetId" WHERE "asset_exif"."assetId" IS NULL; ``` ```sql SELECT * FROM "asset" JOIN "asset_exif" ON "asset"."id" = "asset_exif"."assetId" WHERE "asset_exif"."fileSizeInByte" < 100000 ORDER BY "asset_exif"."fileSizeInByte" ASC; ``` -------------------------------- ### Troubleshoot common container issues Source: https://docs.immich.app/developer/devcontainers Commands for verifying Docker status, checking ports, and setting environment variables. ```bash docker ps docker system prune -a lsof -i :3000 export UPLOAD_LOCATION=./Library ``` -------------------------------- ### Retrieve custom system settings Source: https://docs.immich.app/guides/database-queries Fetches system configuration metadata when not using a config file. ```sql SELECT "key", "value" FROM "system_metadata" WHERE "key" = 'system-config'; ``` -------------------------------- ### Configure OpenVINO WSL Hardware Acceleration Source: https://docs.immich.app/features/ml-hardware-acceleration Docker Compose configuration for enabling OpenVINO hardware acceleration on WSL, including device mapping and group permissions. ```yaml openvino-wsl: devices: - /dev/dri:/dev/dri - /dev/dxg:/dev/dxg volumes: - /dev/bus/usb:/dev/bus/usb - /usr/lib/wsl:/usr/lib/wsl group_add: - 44 # Replace this number with the number you found with getent group video - 992 # Replace this number with the number you found with getent group render ``` -------------------------------- ### Find Assets by Path Source: https://docs.immich.app/guides/database-queries Queries to locate assets based on their original storage path. ```sql SELECT * FROM "asset" WHERE "originalPath" = 'upload/library/admin/2023/2023-09-03/PXL_2023.jpg'; SELECT * FROM "asset" WHERE "originalPath" LIKE 'upload/library/admin/2023/%'; ``` -------------------------------- ### List Users Source: https://docs.immich.app/administration/server-commands Displays a list of all registered users in the system. ```bash immich-admin list-users [ { id: 'e65e6f88-2a30-4dbe-8dd9-1885f4889b53', email: 'immich@example.com', name: 'Immich Admin', storageLabel: 'admin', externalPath: null, profileImagePath: 'upload/profile/e65e6f88-2a30-4dbe-8dd9-1885f4889b53/e65e6f88-2a30-4dbe-8dd9-1885f4889b53.jpg', shouldChangePassword: true, isAdmin: true, createdAt: 2023-07-11T20:12:20.602Z, deletedAt: null, updatedAt: 2023-09-21T15:42:28.129Z, oauthId: '', } ] ```