fix: improve screenshot waiting, add inline images to PR comments

- Increase waitForSelector timeout from 5s to 15s for slower page loads
- Add explicit wait for loading spinners to disappear before screenshot
- Push screenshot images to a temporary branch for inline display
- Read report.md from compare.ts with raw.githubusercontent.com URLs
- Accept optional image base URL in compare.ts CLI
- Upgrade contents permission to write for pushing screenshot branch

https://claude.ai/code/session_01XSTqDJXuR4jaLN7SGm3uES

.devcontainer/devcontainer.json

@@ -2,6 +2,7 @@
   "name": "Immich - Backend, Frontend and ML",
   "service": "immich-server",
   "runServices": [
+    "immich-init",
     "immich-server",
     "redis",
     "database",
@@ -26,7 +27,59 @@
         "vitest.explorer",
         "ms-playwright.playwright",
         "ms-azuretools.vscode-docker"
-      ]
+      ],
+      "settings": {
+        "tasks": {
+          "version": "2.0.0",
+          "tasks": [
+            {
+              "label": "Immich API Server (Nest)",
+              "type": "shell",
+              "command": "[ -f /immich-devcontainer/container-start-backend.sh ] && /immich-devcontainer/container-start-backend.sh || exit 0",
+              "isBackground": true,
+              "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "dedicated",
+                "showReuseMessage": true,
+                "clear": false,
+                "group": "Devcontainer tasks",
+                "close": true
+              },
+              "runOptions": {
+                "runOn": "folderOpen"
+              },
+              "problemMatcher": []
+            },
+            {
+              "label": "Immich Web Server (Vite)",
+              "type": "shell",
+              "command": "[ -f /immich-devcontainer/container-start-frontend.sh ] && /immich-devcontainer/container-start-frontend.sh || exit 0",
+              "isBackground": true,
+              "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "dedicated",
+                "showReuseMessage": true,
+                "clear": false,
+                "group": "Devcontainer tasks",
+                "close": true
+              },
+              "runOptions": {
+                "runOn": "folderOpen"
+              },
+              "problemMatcher": []
+            },
+            {
+              "label": "Build Immich CLI",
+              "type": "shell",
+              "command": "pnpm --filter cli build:dev"
+            }
+          ]
+        }
+      }
     }
   },
   "features": {
@@ -56,8 +109,8 @@
     }
   },
   "overrideCommand": true,
-  "workspaceFolder": "/workspaces/immich",
-  "remoteUser": "node",
+  "workspaceFolder": "/usr/src/app",
+  "remoteUser": "root",
   "userEnvProbe": "loginInteractiveShell",
   "remoteEnv": {
     // The location where your uploaded files are stored

.devcontainer/mobile/container-compose-overrides.yml

@@ -1,23 +1,17 @@
 services:
+  immich-app-base:
+    image: busybox
   immich-server:
+    extends:
+      service: immich-app-base
+    profiles: !reset []
+    image: immich-server-dev:latest
     build:
       target: dev-container-mobile
     environment:
       - IMMICH_SERVER_URL=http://127.0.0.1:2283/
-    volumes: !override # bind mount host to /workspaces/immich
-      - ..:/workspaces/immich
+    volumes:
       - ${UPLOAD_LOCATION:-upload-devcontainer-volume}${UPLOAD_LOCATION:+/photos}:/data
-      - pnpm-store:/usr/src/app/.pnpm-store
-      - server-node_modules:/usr/src/app/server/node_modules
-      - web-node_modules:/usr/src/app/web/node_modules
-      - github-node_modules:/usr/src/app/.github/node_modules
-      - cli-node_modules:/usr/src/app/cli/node_modules
-      - docs-node_modules:/usr/src/app/docs/node_modules
-      - e2e-node_modules:/usr/src/app/e2e/node_modules
-      - sdk-node_modules:/usr/src/app/open-api/typescript-sdk/node_modules
-      - app-node_modules:/usr/src/app/node_modules
-      - sveltekit:/usr/src/app/web/.svelte-kit
-      - coverage:/usr/src/app/web/coverage
       - /etc/localtime:/etc/localtime:ro
   immich-web:
     env_file: !reset []

.devcontainer/mobile/devcontainer.json

@@ -2,6 +2,7 @@
   "name": "Immich - Mobile",
   "service": "immich-server",
   "runServices": [
+    "immich-init",
     "immich-server",
     "redis",
     "database",
@@ -35,7 +36,7 @@
   },
   "forwardPorts": [],
   "overrideCommand": true,
-  "workspaceFolder": "/workspaces/immich",
+  "workspaceFolder": "/usr/src/app",
   "remoteUser": "node",
   "userEnvProbe": "loginInteractiveShell",
   "remoteEnv": {

.devcontainer/server/container-common.sh

@@ -2,11 +2,6 @@
 export IMMICH_PORT="${DEV_SERVER_PORT:-2283}"
 export DEV_PORT="${DEV_PORT:-3000}"
 
-# search for immich directory inside workspace.
-# /workspaces/immich is the bind mount, but other directories can be mounted if runing
-# Devcontainer: Clone [repository|pull request] in container volumne
-WORKSPACES_DIR="/workspaces"
-IMMICH_DIR="$WORKSPACES_DIR/immich"
 IMMICH_DEVCONTAINER_LOG="$HOME/immich-devcontainer.log"
 
 log() {
@@ -30,52 +25,8 @@ run_cmd() {
     return "${PIPESTATUS[0]}"
 }
 
-# Find directories excluding /workspaces/immich
-mapfile -t other_dirs < <(find "$WORKSPACES_DIR" -mindepth 1 -maxdepth 1 -type d ! -path "$IMMICH_DIR" ! -name ".*")
-
-if [ ${#other_dirs[@]} -gt 1 ]; then
-    log "Error: More than one directory found in $WORKSPACES_DIR other than $IMMICH_DIR."
-    exit 1
-elif [ ${#other_dirs[@]} -eq 1 ]; then
-    export IMMICH_WORKSPACE="${other_dirs[0]}"
-else
-    export IMMICH_WORKSPACE="$IMMICH_DIR"
-fi
+export IMMICH_WORKSPACE="/usr/src/app"
 
 log "Found immich workspace in $IMMICH_WORKSPACE"
 log ""
 
-fix_permissions() {
-
-    log "Fixing permissions for ${IMMICH_WORKSPACE}"
-
-    # Change ownership for directories that exist
-    for dir in "${IMMICH_WORKSPACE}/.vscode" \
-        "${IMMICH_WORKSPACE}/server/upload" \
-        "${IMMICH_WORKSPACE}/.pnpm-store" \
-        "${IMMICH_WORKSPACE}/.github/node_modules" \
-        "${IMMICH_WORKSPACE}/cli/node_modules" \
-        "${IMMICH_WORKSPACE}/e2e/node_modules" \
-        "${IMMICH_WORKSPACE}/open-api/typescript-sdk/node_modules" \
-        "${IMMICH_WORKSPACE}/server/node_modules" \
-        "${IMMICH_WORKSPACE}/server/dist" \
-        "${IMMICH_WORKSPACE}/web/node_modules" \
-        "${IMMICH_WORKSPACE}/web/dist"; do
-        if [ -d "$dir" ]; then
-            run_cmd sudo chown node -R "$dir"
-        fi
-    done
-
-    log ""
-}
-
-install_dependencies() {
-
-    log "Installing dependencies"
-    (
-        cd "${IMMICH_WORKSPACE}" || exit 1
-        export CI=1 FROZEN=1 OFFLINE=1
-        run_cmd make setup-web-dev setup-server-dev
-    )
-    log ""
-}

.devcontainer/server/container-compose-overrides.yml

@@ -1,26 +1,21 @@
 services:
+  immich-app-base:
+    image: busybox
   immich-server:
+    extends:
+      service: immich-app-base
+    profiles: !reset []
+    image: immich-server-dev:latest
     build:
       target: dev-container-server
     env_file: !reset []
     hostname: immich-dev
     environment:
       - IMMICH_SERVER_URL=http://127.0.0.1:2283/
-    volumes: !override
-      - ..:/workspaces/immich
+    volumes:
       - ${UPLOAD_LOCATION:-upload-devcontainer-volume}${UPLOAD_LOCATION:+/photos}:/data
       - /etc/localtime:/etc/localtime:ro
-      - pnpm-store:/usr/src/app/.pnpm-store
-      - server-node_modules:/usr/src/app/server/node_modules
-      - web-node_modules:/usr/src/app/web/node_modules
-      - github-node_modules:/usr/src/app/.github/node_modules
-      - cli-node_modules:/usr/src/app/cli/node_modules
-      - docs-node_modules:/usr/src/app/docs/node_modules
-      - e2e-node_modules:/usr/src/app/e2e/node_modules
-      - sdk-node_modules:/usr/src/app/open-api/typescript-sdk/node_modules
-      - app-node_modules:/usr/src/app/node_modules
-      - sveltekit:/usr/src/app/web/.svelte-kit
-      - coverage:/usr/src/app/web/coverage
+      - pnpm_store_server:/buildcache/pnpm-store
       - ../plugins:/build/corePlugin
   immich-web:
     env_file: !reset []

.devcontainer/server/container-start.sh

@@ -1,17 +0,0 @@
-#!/bin/bash
-# shellcheck source=common.sh
-# shellcheck disable=SC1091
-source /immich-devcontainer/container-common.sh
-
-log "Setting up Immich dev container..."
-fix_permissions
-
-log "Setup complete, please wait while backend and frontend services automatically start"
-log
-log "If necessary, the services may be manually started using"
-log
-log "$ /immich-devcontainer/container-start-backend.sh"
-log "$ /immich-devcontainer/container-start-frontend.sh"
-log
-log "From different terminal windows, as these scripts automatically restart the server"
-log "on error, and will continuously run in a loop"

.github/.nvmrc

@@ -1 +1 @@
-24.13.0
+24.13.1

.github/pull_request_template.md

@@ -26,6 +26,7 @@ The `/api/something` endpoint is now `/api/something-else`
 
 ## Checklist:
 
+- [ ] I have carefully read CONTRIBUTING.md
 - [ ] I have performed a self-review of my own code
 - [ ] I have made corresponding changes to the documentation if applicable
 - [ ] I have no unrelated changes in the PR.

.github/workflows/build-mobile.yml

@@ -51,14 +51,14 @@ jobs:
       should_run: ${{ steps.check.outputs.should_run }}
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Check what should run
         id: check
-        uses: immich-app/devtools/actions/pre-job@08bac802a312fc89808e0dd589271ca0974087b5 # pre-job-action-v2.0.0
+        uses: immich-app/devtools/actions/pre-job@eed0f8b8165ffcb951f2ba854b2dd031935e1d73 # pre-job-action-v2.0.2
         with:
           github-token: ${{ steps.token.outputs.token }}
           filters: |
@@ -79,12 +79,12 @@ jobs:
 
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ inputs.ref || github.sha }}
           persist-credentials: false
@@ -96,14 +96,14 @@ jobs:
         working-directory: ./mobile
         run: printf "%s" $KEY_JKS | base64 -d > android/key.jks
 
-      - uses: actions/setup-java@f2beeb24e141e01a676f977032f5a29d81c9e27e # v5.1.0
+      - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
           distribution: 'zulu'
           java-version: '17'
 
       - name: Restore Gradle Cache
         id: cache-gradle-restore
-        uses: actions/cache/restore@9255dc7a253b0ccc959486e2bca901246202afeb # v5.0.1
+        uses: actions/cache/restore@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
         with:
           path: |
             ~/.gradle/caches
@@ -160,7 +160,7 @@ jobs:
 
       - name: Save Gradle Cache
         id: cache-gradle-save
-        uses: actions/cache/save@9255dc7a253b0ccc959486e2bca901246202afeb # v5.0.1
+        uses: actions/cache/save@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
         if: github.ref == 'refs/heads/main'
         with:
           path: |
@@ -185,7 +185,7 @@ jobs:
         run: sudo xcode-select -s /Applications/Xcode_26.2.app/Contents/Developer
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
           persist-credentials: false

.github/workflows/cache-cleanup.yml

@@ -19,13 +19,13 @@ jobs:
       actions: write
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Check out code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}

.github/workflows/check-openapi.yml

@@ -0,0 +1,32 @@
+name: Check OpenAPI
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - 'open-api/**'
+      - '.github/workflows/check-openapi.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  check-openapi:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Check for breaking API changes
+        # sha is pinning to a commit instead of a tag since the action does not tag versions
+        uses: oasdiff/oasdiff-action/breaking@ccb863950ce437a50f8f1a40d2a1112117e06ce4
+        with:
+          base: https://raw.githubusercontent.com/${{ github.repository }}/main/open-api/immich-openapi-specs.json
+          revision: open-api/immich-openapi-specs.json
+          fail-on: ERR

.github/workflows/cli.yml

@@ -31,12 +31,12 @@ jobs:
         working-directory: ./cli
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
@@ -45,7 +45,7 @@ jobs:
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
 
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './cli/.nvmrc'
           registry-url: 'https://registry.npmjs.org'
@@ -71,13 +71,13 @@ jobs:
 
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
@@ -89,7 +89,7 @@ jobs:
         uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         if: ${{ !github.event.pull_request.head.repo.fork }}
         with:
           registry: ghcr.io
@@ -115,7 +115,7 @@ jobs:
             type=raw,value=latest,enable=${{ github.event_name == 'release' }}
 
       - name: Build and push image
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           file: cli/Dockerfile
           platforms: linux/amd64,linux/arm64

.github/workflows/close-duplicates.yml

@@ -35,7 +35,7 @@ jobs:
     needs: [get_body, should_run]
     if: ${{ needs.should_run.outputs.should_run == 'true' }}
     container:
-      image: ghcr.io/immich-app/mdq:main@sha256:ab9f163cd5d5cec42704a26ca2769ecf3f10aa8e7bae847f1d527cdf075946e6
+      image: ghcr.io/immich-app/mdq:main@sha256:4f9860d04c88f7f87861f8ee84bfeedaec15ed7ca5ca87bc7db44b036f81645f
     outputs:
       checked: ${{ steps.get_checkbox.outputs.checked }}
     steps:

.github/workflows/close-llm-pr.yml

@@ -0,0 +1,38 @@
+name: Close LLM-generated PRs
+
+on:
+  pull_request_target:
+    types: [labeled]
+
+permissions: {}
+
+jobs:
+  comment_and_close:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.label.name == 'llm-generated' }}
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Comment and close
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NODE_ID: ${{ github.event.pull_request.node_id }}
+        run: |
+          gh api graphql \
+            -f prId="$NODE_ID" \
+            -f body="Thank you for your interest in contributing to Immich! Unfortunately this PR looks like it was generated using an LLM. As noted in our [CONTRIBUTING.md](https://github.com/immich-app/immich/blob/main/CONTRIBUTING.md#use-of-generative-ai), we request that you don't use LLMs to generate PRs as those are not a good use of maintainer time." \
+            -f query='
+              mutation CommentAndClosePR($prId: ID!, $body: String!) {
+                addComment(input: {
+                  subjectId: $prId,
+                  body: $body
+                }) {
+                  __typename
+                }
+
+                closePullRequest(input: {
+                  pullRequestId: $prId
+                }) {
+                  __typename
+                }
+              }'

.github/workflows/codeql-analysis.yml

@@ -44,20 +44,20 @@ jobs:
 
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
+        uses: github/codeql-action/init@9e907b5e64f6b83e7804b09294d44122997950d6 # v4.32.3
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -70,7 +70,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
+        uses: github/codeql-action/autobuild@9e907b5e64f6b83e7804b09294d44122997950d6 # v4.32.3
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -83,6 +83,6 @@ jobs:
       #   ./location_of_script_within_repo/buildscript.sh
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
+        uses: github/codeql-action/analyze@9e907b5e64f6b83e7804b09294d44122997950d6 # v4.32.3
         with:
           category: '/language:${{matrix.language}}'

.github/workflows/docker.yml

@@ -23,14 +23,14 @@ jobs:
       should_run: ${{ steps.check.outputs.should_run }}
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Check what should run
         id: check
-        uses: immich-app/devtools/actions/pre-job@08bac802a312fc89808e0dd589271ca0974087b5 # pre-job-action-v2.0.0
+        uses: immich-app/devtools/actions/pre-job@eed0f8b8165ffcb951f2ba854b2dd031935e1d73 # pre-job-action-v2.0.2
         with:
           github-token: ${{ steps.token.outputs.token }}
           filters: |
@@ -60,7 +60,7 @@ jobs:
         suffix: ['', '-cuda', '-rocm', '-openvino', '-armnn', '-rknn']
     steps:
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
@@ -90,7 +90,7 @@ jobs:
         suffix: ['']
     steps:
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
@@ -131,8 +131,8 @@ jobs:
           - device: rocm
             suffixes: '-rocm'
             platforms: linux/amd64
-            runner-mapping: '{"linux/amd64": "mich"}'
-    uses: immich-app/devtools/.github/workflows/multi-runner-build.yml@0477486d82313fba68f7c82c034120a4b8981297 # multi-runner-build-workflow-v2.1.0
+            runner-mapping: '{"linux/amd64": "pokedex-giant"}'
+    uses: immich-app/devtools/.github/workflows/multi-runner-build.yml@bd49ed7a5a6022149f79b6564df48177476a822b # multi-runner-build-workflow-v2.2.1
     permissions:
       contents: read
       actions: read
@@ -155,7 +155,7 @@ jobs:
     name: Build and Push Server
     needs: pre-job
     if: ${{ fromJSON(needs.pre-job.outputs.should_run).server == true }}
-    uses: immich-app/devtools/.github/workflows/multi-runner-build.yml@0477486d82313fba68f7c82c034120a4b8981297 # multi-runner-build-workflow-v2.1.0
+    uses: immich-app/devtools/.github/workflows/multi-runner-build.yml@bd49ed7a5a6022149f79b6564df48177476a822b # multi-runner-build-workflow-v2.2.1
     permissions:
       contents: read
       actions: read

.github/workflows/docs-build.yml

@@ -21,14 +21,14 @@ jobs:
       should_run: ${{ steps.check.outputs.should_run }}
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Check what should run
         id: check
-        uses: immich-app/devtools/actions/pre-job@08bac802a312fc89808e0dd589271ca0974087b5 # pre-job-action-v2.0.0
+        uses: immich-app/devtools/actions/pre-job@eed0f8b8165ffcb951f2ba854b2dd031935e1d73 # pre-job-action-v2.0.2
         with:
           github-token: ${{ steps.token.outputs.token }}
           filters: |
@@ -54,13 +54,13 @@ jobs:
 
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
@@ -70,7 +70,7 @@ jobs:
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
 
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './docs/.nvmrc'
           cache: 'pnpm'

.github/workflows/docs-deploy.yml

@@ -20,7 +20,7 @@ jobs:
       artifact: ${{ steps.get-artifact.outputs.result }}
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
@@ -119,19 +119,19 @@ jobs:
     if: ${{ fromJson(needs.checks.outputs.artifact).found && fromJson(needs.checks.outputs.parameters).shouldDeploy }}
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
 
       - name: Setup Mise
-        uses: immich-app/devtools/actions/use-mise@cd24790a7f5f6439ac32cc94f5523cb2de8bfa8c # use-mise-action-v1.1.0
+        uses: immich-app/devtools/actions/use-mise@dab18118da6476e8237ac94080fd937983fecd42 # use-mise-action-v1.1.2
 
       - name: Load parameters
         id: parameters
@@ -192,16 +192,13 @@ jobs:
           ' >> $GITHUB_OUTPUT
 
       - name: Publish to Cloudflare Pages
-        # TODO: Action is deprecated
-        uses: cloudflare/pages-action@f0a1cd58cd66095dee69bfa18fa5efd1dde93bca # v1.5.0
-        with:
-          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN_PAGES_UPLOAD }}
-          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          projectName: ${{ steps.docs-output.outputs.projectName }}
-          workingDirectory: 'docs'
-          directory: 'build'
-          branch: ${{ steps.parameters.outputs.name }}
-          wranglerVersion: '3'
+        working-directory: docs
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN_PAGES_UPLOAD }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          PROJECT_NAME: ${{ steps.docs-output.outputs.projectName }}
+          BRANCH_NAME: ${{ steps.parameters.outputs.name }}
+        run: mise run //docs:deploy
 
       - name: Deploy Docs Release Domain
         if: ${{ steps.parameters.outputs.event == 'release' }}

.github/workflows/docs-destroy.yml

@@ -17,19 +17,19 @@ jobs:
       pull-requests: write
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
 
       - name: Setup Mise
-        uses: immich-app/devtools/actions/use-mise@cd24790a7f5f6439ac32cc94f5523cb2de8bfa8c # use-mise-action-v1.1.0
+        uses: immich-app/devtools/actions/use-mise@dab18118da6476e8237ac94080fd937983fecd42 # use-mise-action-v1.1.2
 
       - name: Destroy Docs Subdomain
         env:

.github/workflows/fix-format.yml

@@ -22,7 +22,7 @@ jobs:
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: 'Checkout'
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ github.event.pull_request.head.ref }}
           token: ${{ steps.generate-token.outputs.token }}
@@ -32,14 +32,14 @@ jobs:
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
 
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './server/.nvmrc'
           cache: 'pnpm'
           cache-dependency-path: '**/pnpm-lock.yaml'
 
       - name: Fix formatting
-        run: pnpm --recursive install && pnpm run --recursive --parallel fix:format
+        run: pnpm --recursive install && pnpm run --recursive --if-present --parallel format:fix
 
       - name: Commit and push
         uses: EndBug/add-and-commit@a94899bca583c204427a224a7af87c02f9b325d5 # v9.1.4

.github/workflows/pr-label-validation.yml

@@ -14,7 +14,7 @@ jobs:
       pull-requests: write
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}

.github/workflows/pr-labeler.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}

.github/workflows/prepare-release.yml

@@ -56,20 +56,20 @@ jobs:
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           token: ${{ steps.generate-token.outputs.token }}
           persist-credentials: true
           ref: main
 
       - name: Install uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
 
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
 
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './server/.nvmrc'
           cache: 'pnpm'
@@ -130,7 +130,7 @@ jobs:
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           token: ${{ steps.generate-token.outputs.token }}
           persist-credentials: false

.github/workflows/preview-label.yaml

@@ -14,7 +14,7 @@ jobs:
       pull-requests: write
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
@@ -32,7 +32,7 @@ jobs:
       pull-requests: write
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}

.github/workflows/release-pr.yml

@@ -23,20 +23,20 @@ jobs:
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           token: ${{ steps.generate-token.outputs.token }}
           persist-credentials: true
           ref: main
 
       - name: Install uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
 
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
 
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './server/.nvmrc'
           cache: 'pnpm'
@@ -159,7 +159,7 @@ jobs:
 
       - name: Create PR
         id: create-pr
-        uses: peter-evans/create-pull-request@98357b18bf14b5342f975ff684046ec3b2a07725 # v8.0.0
+        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
         with:
           token: ${{ steps.generate-token.outputs.token }}
           commit-message: 'chore: release ${{ steps.bump-type.outputs.next }}'

.github/workflows/release.yml

@@ -58,7 +58,7 @@ jobs:
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           token: ${{ steps.generate-token.outputs.token }}
           persist-credentials: false
@@ -88,6 +88,7 @@ jobs:
           draft: true
           files: |
             docker/docker-compose.yml
+            docker/docker-compose.rootless.yml
             docker/example.env
             docker/hwaccel.ml.yml
             docker/hwaccel.transcoding.yml

.github/workflows/sdk.yml

@@ -19,12 +19,12 @@ jobs:
         working-directory: ./open-api/typescript-sdk
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
@@ -33,7 +33,7 @@ jobs:
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
 
       # Setup .npmrc file to publish to npm
-      - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './open-api/typescript-sdk/.nvmrc'
           registry-url: 'https://registry.npmjs.org'

.github/workflows/static_analysis.yml

@@ -20,14 +20,14 @@ jobs:
       should_run: ${{ steps.check.outputs.should_run }}
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Check what should run
         id: check
-        uses: immich-app/devtools/actions/pre-job@08bac802a312fc89808e0dd589271ca0974087b5 # pre-job-action-v2.0.0
+        uses: immich-app/devtools/actions/pre-job@eed0f8b8165ffcb951f2ba854b2dd031935e1d73 # pre-job-action-v2.0.2
         with:
           github-token: ${{ steps.token.outputs.token }}
           filters: |
@@ -49,13 +49,13 @@ jobs:
         working-directory: ./mobile
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
@@ -69,6 +69,14 @@ jobs:
       - name: Install dependencies
         run: dart pub get
 
+      - name: Install dependencies for UI package
+        run: dart pub get
+        working-directory: ./mobile/packages/ui
+
+      - name: Install dependencies for UI Showcase
+        run: dart pub get
+        working-directory: ./mobile/packages/ui/showcase
+
       - name: Install DCM
         uses: CQLabs/setup-dcm@8697ae0790c0852e964a6ef1d768d62a6675481a # v2.0.1
         with:

.github/workflows/test.yml

@@ -17,14 +17,14 @@ jobs:
       should_run: ${{ steps.check.outputs.should_run }}
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Check what should run
         id: check
-        uses: immich-app/devtools/actions/pre-job@08bac802a312fc89808e0dd589271ca0974087b5 # pre-job-action-v2.0.0
+        uses: immich-app/devtools/actions/pre-job@eed0f8b8165ffcb951f2ba854b2dd031935e1d73 # pre-job-action-v2.0.2
         with:
           github-token: ${{ steps.token.outputs.token }}
           filters: |
@@ -63,13 +63,13 @@ jobs:
         working-directory: ./server
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
@@ -77,7 +77,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './server/.nvmrc'
           cache: 'pnpm'
@@ -108,20 +108,20 @@ jobs:
         working-directory: ./cli
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './cli/.nvmrc'
           cache: 'pnpm'
@@ -155,20 +155,20 @@ jobs:
         working-directory: ./cli
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './cli/.nvmrc'
           cache: 'pnpm'
@@ -197,20 +197,20 @@ jobs:
         working-directory: ./web
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './web/.nvmrc'
           cache: 'pnpm'
@@ -241,20 +241,20 @@ jobs:
         working-directory: ./web
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './web/.nvmrc'
           cache: 'pnpm'
@@ -279,20 +279,20 @@ jobs:
       contents: read
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './web/.nvmrc'
           cache: 'pnpm'
@@ -327,20 +327,20 @@ jobs:
         working-directory: ./e2e
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './e2e/.nvmrc'
           cache: 'pnpm'
@@ -373,13 +373,13 @@ jobs:
         working-directory: ./server
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           submodules: 'recursive'
@@ -387,7 +387,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './server/.nvmrc'
           cache: 'pnpm'
@@ -412,13 +412,13 @@ jobs:
         runner: [ubuntu-latest, ubuntu-24.04-arm]
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           submodules: 'recursive'
@@ -426,7 +426,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './e2e/.nvmrc'
           cache: 'pnpm'
@@ -446,12 +446,29 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
         if: ${{ !cancelled() }}
-      - name: Docker build
-        run: docker compose build
+      - name: Start Docker Compose
+        run: docker compose up -d --build --renew-anon-volumes --force-recreate --remove-orphans --wait --wait-timeout 300
         if: ${{ !cancelled() }}
       - name: Run e2e tests (api & cli)
+        env:
+          VITEST_DISABLE_DOCKER_SETUP: true
         run: pnpm test
         if: ${{ !cancelled() }}
+      - name: Run e2e tests (maintenance)
+        env:
+          VITEST_DISABLE_DOCKER_SETUP: true
+        run: pnpm test:maintenance
+        if: ${{ !cancelled() }}
+      - name: Capture Docker logs
+        if: always()
+        run: docker compose logs --no-color > docker-compose-logs.txt
+        working-directory: ./e2e
+      - name: Archive Docker logs
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        if: always()
+        with:
+          name: e2e-server-docker-logs-${{ matrix.runner }}
+          path: e2e/docker-compose-logs.txt
   e2e-tests-web:
     name: End-to-End Tests (Web)
     needs: pre-job
@@ -467,13 +484,13 @@ jobs:
         runner: [ubuntu-latest, ubuntu-24.04-arm]
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           submodules: 'recursive'
@@ -481,7 +498,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './e2e/.nvmrc'
           cache: 'pnpm'
@@ -494,17 +511,17 @@ jobs:
         run: pnpm install --frozen-lockfile
         if: ${{ !cancelled() }}
       - name: Install Playwright Browsers
-        run: npx playwright install chromium --only-shell
+        run: pnpm exec playwright install chromium --only-shell
         if: ${{ !cancelled() }}
       - name: Docker build
-        run: docker compose build
+        run: docker compose up -d --build --renew-anon-volumes --force-recreate --remove-orphans --wait --wait-timeout 300
         if: ${{ !cancelled() }}
       - name: Run e2e tests (web)
         env:
-          CI: true
-        run: npx playwright test --project=chromium
+          PLAYWRIGHT_DISABLE_WEBSERVER: true
+        run: pnpm test:web
         if: ${{ !cancelled() }}
-      - name: Archive web results
+      - name: Archive e2e test (web) results
         uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
         if: success() || failure()
         with:
@@ -512,15 +529,36 @@ jobs:
           path: e2e/playwright-report/
       - name: Run ui tests (web)
         env:
-          CI: true
-        run: npx playwright test --project=ui
+          PLAYWRIGHT_DISABLE_WEBSERVER: true
+        run: pnpm test:web:ui
         if: ${{ !cancelled() }}
-      - name: Archive ui results
+      - name: Archive ui test (web) results
         uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
         if: success() || failure()
         with:
           name: e2e-ui-test-results-${{ matrix.runner }}
           path: e2e/playwright-report/
+      - name: Run maintenance tests
+        env:
+          PLAYWRIGHT_DISABLE_WEBSERVER: true
+        run: pnpm test:web:maintenance
+        if: ${{ !cancelled() }}
+      - name: Archive maintenance tests (web) results
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        if: success() || failure()
+        with:
+          name: e2e-maintenance-isolated-test-results-${{ matrix.runner }}
+          path: e2e/playwright-report/
+      - name: Capture Docker logs
+        if: always()
+        run: docker compose logs --no-color > docker-compose-logs.txt
+        working-directory: ./e2e
+      - name: Archive Docker logs
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        if: always()
+        with:
+          name: e2e-web-docker-logs-${{ matrix.runner }}
+          path: e2e/docker-compose-logs.txt
   success-check-e2e:
     name: End-to-End Tests Success
     needs: [e2e-tests-server-cli, e2e-tests-web]
@@ -540,12 +578,12 @@ jobs:
       contents: read
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
@@ -572,17 +610,17 @@ jobs:
         working-directory: ./machine-learning
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
       - name: Install uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
         with:
           python-version: 3.11
       - name: Install dependencies
@@ -591,9 +629,9 @@ jobs:
       - name: Lint with ruff
         run: |
           uv run ruff check --output-format=github immich_ml
-      - name: Check black formatting
+      - name: Format with ruff
         run: |
-          uv run black --check immich_ml
+          uv run ruff format --check immich_ml
       - name: Run mypy type checking
         run: |
           uv run mypy --strict immich_ml/
@@ -612,20 +650,20 @@ jobs:
         working-directory: ./.github
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './.github/.nvmrc'
           cache: 'pnpm'
@@ -642,12 +680,12 @@ jobs:
       contents: read
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
@@ -663,20 +701,20 @@ jobs:
       contents: read
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './server/.nvmrc'
           cache: 'pnpm'
@@ -725,20 +763,20 @@ jobs:
         working-directory: ./server
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Checkout code
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
           token: ${{ steps.token.outputs.token }}
       - name: Setup pnpm
         uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - name: Setup Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
           node-version-file: './server/.nvmrc'
           cache: 'pnpm'

.github/workflows/visual-review.yml

@@ -0,0 +1,379 @@
+name: Visual Review
+
+on:
+  pull_request:
+    types: [labeled, synchronize]
+
+permissions: {}
+
+jobs:
+  visual-diff:
+    name: Visual Diff Screenshots
+    runs-on: ubuntu-latest
+    if: >-
+      (github.event.action == 'labeled' && github.event.label.name == 'visual-review') ||
+      (github.event.action == 'synchronize' && contains(github.event.pull_request.labels.*.name, 'visual-review'))
+    permissions:
+      contents: write
+      pull-requests: write
+    defaults:
+      run:
+        working-directory: ./e2e
+    steps:
+      - id: token
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
+        with:
+          app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
+          private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
+
+      - name: Checkout PR branch
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+          token: ${{ steps.token.outputs.token }}
+          fetch-depth: 0
+
+      - name: Determine changed web files
+        id: changed-files
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          github-token: ${{ steps.token.outputs.token }}
+          script: |
+            const files = [];
+            const perPage = 100;
+            let page = 1;
+            while (true) {
+              const { data } = await github.rest.pulls.listFiles({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.issue.number,
+                per_page: perPage,
+                page,
+              });
+              files.push(...data);
+              if (data.length < perPage) break;
+              page++;
+            }
+
+            const webPrefixes = ['web/', 'i18n/', 'open-api/typescript-sdk/'];
+            const webFiles = files
+              .map(f => f.filename)
+              .filter(f => webPrefixes.some(p => f.startsWith(p)));
+
+            console.log(`Total PR files: ${files.length}`);
+            console.log(`Web-related files: ${webFiles.length}`);
+            for (const f of webFiles) {
+              console.log(`  ${f}`);
+            }
+
+            core.setOutput('files', webFiles.join('\n'));
+            core.setOutput('has_changes', webFiles.length > 0 ? 'true' : 'false');
+
+      - name: Setup pnpm
+        if: steps.changed-files.outputs.has_changes == 'true'
+        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+
+      - name: Setup Node
+        if: steps.changed-files.outputs.has_changes == 'true'
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version-file: './e2e/.nvmrc'
+          cache: 'pnpm'
+          cache-dependency-path: '**/pnpm-lock.yaml'
+
+      - name: Install e2e dependencies
+        if: steps.changed-files.outputs.has_changes == 'true'
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Playwright
+        if: steps.changed-files.outputs.has_changes == 'true'
+        run: pnpm exec playwright install chromium --only-shell
+
+      - name: Analyze affected routes
+        if: steps.changed-files.outputs.has_changes == 'true'
+        id: routes
+        env:
+          CHANGED_FILES: ${{ steps.changed-files.outputs.files }}
+        run: |
+          echo "Changed files:"
+          echo "$CHANGED_FILES"
+          echo "---"
+
+          ROUTES=$(echo "$CHANGED_FILES" | xargs pnpm exec tsx src/screenshots/analyze-deps.ts 2>&1 | tee /dev/stderr | grep "^  /" | sed 's/^  //' || true)
+
+          echo "routes<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$ROUTES" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+          if [ -z "$ROUTES" ]; then
+            echo "has_routes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_routes=true" >> "$GITHUB_OUTPUT"
+
+            # Build the scenario filter JSON array
+            SCENARIO_NAMES=$(pnpm exec tsx -e "
+              import { getScenariosForRoutes } from './src/screenshots/page-map.ts';
+              const routes = process.argv.slice(1);
+              const scenarios = getScenariosForRoutes(routes);
+              console.log(JSON.stringify(scenarios.map(s => s.name)));
+            " $ROUTES)
+            echo "scenarios=$SCENARIO_NAMES" >> "$GITHUB_OUTPUT"
+            echo "Scenarios: $SCENARIO_NAMES"
+          fi
+
+      - name: Post initial comment
+        if: steps.changed-files.outputs.has_changes == 'true' && steps.routes.outputs.has_routes == 'true'
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        env:
+          AFFECTED_ROUTES: ${{ steps.routes.outputs.routes }}
+        with:
+          github-token: ${{ steps.token.outputs.token }}
+          script: |
+            const routes = process.env.AFFECTED_ROUTES || '';
+            const body = `## Visual Review\n\nGenerating screenshots for affected pages...\n\nAffected routes:\n\`\`\`\n${routes}\n\`\`\``;
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.data.find(c => c.body && c.body.includes('## Visual Review'));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+
+      # === Screenshot PR version ===
+      - name: Build SDK (PR)
+        if: steps.routes.outputs.has_routes == 'true'
+        run: pnpm install --frozen-lockfile && pnpm build
+        working-directory: ./open-api/typescript-sdk
+
+      - name: Build web (PR)
+        if: steps.routes.outputs.has_routes == 'true'
+        run: pnpm install --frozen-lockfile && pnpm build
+        working-directory: ./web
+
+      - name: Take screenshots (PR)
+        if: steps.routes.outputs.has_routes == 'true'
+        env:
+          PW_EXPERIMENTAL_SERVICE_WORKER_NETWORK_EVENTS: '1'
+          SCREENSHOT_OUTPUT_DIR: ${{ github.workspace }}/screenshots/pr
+          SCREENSHOT_SCENARIOS: ${{ steps.routes.outputs.scenarios }}
+          SCREENSHOT_BASE_URL: http://127.0.0.1:4173
+        run: |
+          # Start the preview server in background
+          cd ../web && pnpm preview --port 4173 --host 127.0.0.1 &
+          SERVER_PID=$!
+
+          # Wait for server to be ready
+          for i in $(seq 1 30); do
+            if curl -s http://127.0.0.1:4173 > /dev/null 2>&1; then
+              echo "Server ready after ${i}s"
+              break
+            fi
+            sleep 1
+          done
+
+          # Run screenshot tests
+          pnpm exec playwright test --config playwright.screenshot.config.ts || true
+
+          # Stop the preview server
+          kill $SERVER_PID 2>/dev/null || true
+
+      # === Screenshot base version ===
+      - name: Checkout base web directory
+        if: steps.routes.outputs.has_routes == 'true'
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          # Restore web directory from base branch
+          git checkout "$BASE_SHA" -- web/ open-api/typescript-sdk/ i18n/ || true
+        working-directory: .
+
+      - name: Build SDK (base)
+        if: steps.routes.outputs.has_routes == 'true'
+        run: pnpm install --frozen-lockfile && pnpm build
+        working-directory: ./open-api/typescript-sdk
+
+      - name: Build web (base)
+        if: steps.routes.outputs.has_routes == 'true'
+        run: pnpm install --frozen-lockfile && pnpm build
+        working-directory: ./web
+
+      - name: Take screenshots (base)
+        if: steps.routes.outputs.has_routes == 'true'
+        env:
+          PW_EXPERIMENTAL_SERVICE_WORKER_NETWORK_EVENTS: '1'
+          SCREENSHOT_OUTPUT_DIR: ${{ github.workspace }}/screenshots/base
+          SCREENSHOT_SCENARIOS: ${{ steps.routes.outputs.scenarios }}
+          SCREENSHOT_BASE_URL: http://127.0.0.1:4173
+        run: |
+          # Start the preview server in background
+          cd ../web && pnpm preview --port 4173 --host 127.0.0.1 &
+          SERVER_PID=$!
+
+          # Wait for server to be ready
+          for i in $(seq 1 30); do
+            if curl -s http://127.0.0.1:4173 > /dev/null 2>&1; then
+              echo "Server ready after ${i}s"
+              break
+            fi
+            sleep 1
+          done
+
+          # Run screenshot tests
+          pnpm exec playwright test --config playwright.screenshot.config.ts || true
+
+          # Stop the preview server
+          kill $SERVER_PID 2>/dev/null || true
+
+      # === Compare and report ===
+      - name: Compare screenshots
+        if: steps.routes.outputs.has_routes == 'true'
+        id: compare
+        env:
+          WORKSPACE_DIR: ${{ github.workspace }}
+          IMAGE_BASE_URL: https://raw.githubusercontent.com/${{ github.repository }}/visual-review/pr-${{ github.event.pull_request.number }}
+        run: |
+          pnpm exec tsx src/screenshots/compare.ts \
+            "$WORKSPACE_DIR/screenshots/base" \
+            "$WORKSPACE_DIR/screenshots/pr" \
+            "$WORKSPACE_DIR/screenshots/diff" \
+            "$IMAGE_BASE_URL"
+
+      - name: Upload screenshot artifacts
+        if: steps.routes.outputs.has_routes == 'true'
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: visual-review-screenshots
+          path: screenshots/
+          retention-days: 14
+
+      - name: Push screenshots to review branch
+        if: steps.routes.outputs.has_routes == 'true'
+        env:
+          REVIEW_BRANCH: visual-review/pr-${{ github.event.pull_request.number }}
+          GH_TOKEN: ${{ steps.token.outputs.token }}
+        run: |
+          cd "$GITHUB_WORKSPACE"
+          # Save screenshots before git operations
+          cp -r screenshots /tmp/vr-screenshots
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout --orphan "$REVIEW_BRANCH"
+          git rm -rf . 2>/dev/null || true
+          cp -r /tmp/vr-screenshots/base . 2>/dev/null || true
+          cp -r /tmp/vr-screenshots/pr . 2>/dev/null || true
+          cp -r /tmp/vr-screenshots/diff . 2>/dev/null || true
+          git add base/ pr/ diff/ 2>/dev/null || true
+          git commit -m "Visual review screenshots for PR #${{ github.event.pull_request.number }}" --allow-empty
+          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"
+          git push -f origin "$REVIEW_BRANCH"
+        working-directory: .
+
+      - name: Post comparison results
+        if: steps.routes.outputs.has_routes == 'true'
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          github-token: ${{ steps.token.outputs.token }}
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            // Read from /tmp copy since git push step may have cleared the workspace
+            const reportPath = path.join('/tmp', 'vr-screenshots', 'diff', 'report.md');
+
+            let body;
+            try {
+              body = fs.readFileSync(reportPath, 'utf8');
+            } catch {
+              body = '## Visual Review\n\nScreenshot comparison failed. Check the workflow artifacts for details.';
+            }
+
+            // Find and update existing comment or create new one
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.data.find(c =>
+              c.body && c.body.includes('## Visual Review')
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+
+      - name: No web changes
+        if: steps.changed-files.outputs.has_changes != 'true'
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          github-token: ${{ steps.token.outputs.token }}
+          script: |
+            const body = '## Visual Review\n\nNo web-related file changes detected in this PR. Visual review not needed.';
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.data.find(c => c.body && c.body.includes('## Visual Review'));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner, repo: context.repo.repo,
+                comment_id: existing.id, body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner, repo: context.repo.repo,
+                issue_number: context.issue.number, body,
+              });
+            }
+
+      - name: No affected routes
+        if: steps.changed-files.outputs.has_changes == 'true' && steps.routes.outputs.has_routes != 'true'
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          github-token: ${{ steps.token.outputs.token }}
+          script: |
+            const body = '## Visual Review\n\nChanged files don\'t affect any pages with screenshot scenarios configured.\nTo add coverage, define new scenarios in `e2e/src/screenshots/page-map.ts`.';
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.data.find(c => c.body && c.body.includes('## Visual Review'));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner, repo: context.repo.repo,
+                comment_id: existing.id, body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner, repo: context.repo.repo,
+                issue_number: context.issue.number, body,
+              });
+            }

.github/workflows/weblate-lock.yml

@@ -24,14 +24,14 @@ jobs:
       should_run: ${{ steps.check.outputs.should_run }}
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}
 
       - name: Check what should run
         id: check
-        uses: immich-app/devtools/actions/pre-job@08bac802a312fc89808e0dd589271ca0974087b5 # pre-job-action-v2.0.0
+        uses: immich-app/devtools/actions/pre-job@eed0f8b8165ffcb951f2ba854b2dd031935e1d73 # pre-job-action-v2.0.2
         with:
           github-token: ${{ steps.token.outputs.token }}
           filters: |
@@ -47,7 +47,7 @@ jobs:
     if: ${{ fromJSON(needs.pre-job.outputs.should_run).i18n == true }}
     steps:
       - id: token
-        uses: immich-app/devtools/actions/create-workflow-token@da177fa133657503ddb7503f8ba53dccefec5da1 # create-workflow-token-action-v1.0.0
+        uses: immich-app/devtools/actions/create-workflow-token@05e16407c0a5492138bb38139c9d9bf067b40886 # create-workflow-token-action-v1.0.1
         with:
           app-id: ${{ secrets.PUSH_O_MATIC_APP_ID }}
           private-key: ${{ secrets.PUSH_O_MATIC_APP_KEY }}

.gitignore

@@ -24,6 +24,7 @@ open-api/typescript-sdk/build
 mobile/android/fastlane/report.xml
 mobile/ios/fastlane/report.xml
 
+screenshots-output
 vite.config.js.timestamp-*
 .pnpm-store
 .devcontainer/library

.pnpmfile.cjs

@@ -4,12 +4,18 @@ module.exports = {
       if (!pkg.name) {
         return pkg;
       }
+      // make exiftool-vendored.pl a regular dependency since Docker prod
+      // images build with --no-optional to reduce image size
       if (pkg.name === "exiftool-vendored") {
-        if (pkg.optionalDependencies["exiftool-vendored.pl"]) {
-          // make exiftool-vendored.pl a regular dependency
-          pkg.dependencies["exiftool-vendored.pl"] =
-            pkg.optionalDependencies["exiftool-vendored.pl"];
-          delete pkg.optionalDependencies["exiftool-vendored.pl"];
+        const binaryPackage =
+          process.platform === "win32"
+            ? "exiftool-vendored.exe"
+            : "exiftool-vendored.pl";
+
+        if (pkg.optionalDependencies[binaryPackage]) {
+          pkg.dependencies[binaryPackage] =
+            pkg.optionalDependencies[binaryPackage];
+          delete pkg.optionalDependencies[binaryPackage];
         }
       }
       return pkg;

.vscode/tasks.json

@@ -1,80 +0,0 @@
-{
-  "version": "2.0.0",
-  "tasks": [
-    {
-      "label": "Fix Permissions, Install Dependencies",
-      "type": "shell",
-      "command": "[ -f /immich-devcontainer/container-start.sh ] && /immich-devcontainer/container-start.sh || exit 0",
-      "isBackground": true,
-      "presentation": {
-        "echo": true,
-        "reveal": "always",
-        "focus": false,
-        "panel": "dedicated",
-        "showReuseMessage": true,
-        "clear": false,
-        "group": "Devcontainer tasks",
-        "close": true
-      },
-      "runOptions": {
-        "runOn": "default"
-      },
-      "problemMatcher": []
-    },
-    {
-      "label": "Immich API Server (Nest)",
-      "dependsOn": ["Fix Permissions, Install Dependencies"],
-      "type": "shell",
-      "command": "[ -f /immich-devcontainer/container-start-backend.sh ] && /immich-devcontainer/container-start-backend.sh || exit 0",
-      "isBackground": true,
-      "presentation": {
-        "echo": true,
-        "reveal": "always",
-        "focus": false,
-        "panel": "dedicated",
-        "showReuseMessage": true,
-        "clear": false,
-        "group": "Devcontainer tasks",
-        "close": true
-      },
-      "runOptions": {
-        "runOn": "default"
-      },
-      "problemMatcher": []
-    },
-    {
-      "label": "Immich Web Server (Vite)",
-      "dependsOn": ["Fix Permissions, Install Dependencies"],
-      "type": "shell",
-      "command": "[ -f /immich-devcontainer/container-start-frontend.sh ] && /immich-devcontainer/container-start-frontend.sh || exit 0",
-      "isBackground": true,
-      "presentation": {
-        "echo": true,
-        "reveal": "always",
-        "focus": false,
-        "panel": "dedicated",
-        "showReuseMessage": true,
-        "clear": false,
-        "group": "Devcontainer tasks",
-        "close": true
-      },
-      "runOptions": {
-        "runOn": "default"
-      },
-      "problemMatcher": []
-    },
-    {
-      "label": "Immich Server and Web",
-      "dependsOn": ["Immich Web Server (Vite)", "Immich API Server (Nest)"],
-      "runOptions": {
-        "runOn": "folderOpen"
-      },
-      "problemMatcher": []
-    },
-    {
-      "label": "Build Immich CLI",
-      "type": "shell",
-      "command": "pnpm --filter cli build:dev"
-    }
-  ]
-}

CONTRIBUTING.md

@@ -17,15 +17,27 @@ If you are looking for something to work on, there are discussions and issues wi
 
 ## Use of generative AI
 
-We generally discourage PRs entirely generated by an LLM. For any part generated by an LLM, please put extra effort into your self-review. By using generative AI without proper self-review, the time you save ends up being more work we need to put in for proper reviews and code cleanup. Please keep that in mind when submitting code by an LLM. Clearly state the use of LLMs/(generative) AI in your pull request as requested by the template.
+We ask you not to open PRs generated with an LLM. We find that code generated like this tends to need a large amount of back-and-forth, which is a very inefficient use of our time. If we want LLM-generated code, it's much faster for us to use an LLM ourselves than to go through an intermediary via a pull request.
 
 ## Feature freezes
 
 From time to time, we put a feature freeze on parts of the codebase. For us, this means we won't accept most PRs that make changes in that area. Exempted from this are simple bug fixes that require only minor changes. We will close feature PRs that target a feature-frozen area, even if that feature is highly requested and you put a lot of work into it. Please keep that in mind, and if you're ever uncertain if a PR would be accepted, reach out to us first (e.g., in the aforementioned `#contributing` channel). We hate to throw away work. Currently, we have feature freezes on:
 
-* Sharing/Asset ownership
-* (External) libraries
+- Sharing/Asset ownership
+- (External) libraries
 
 ## Non-code contributions
 
-If you want to contribute to Immich but you don't feel comfortable programming in our tech stack, there are other ways you can help the team. All our translations are done through [Weblate](https://hosted.weblate.org/projects/immich). These rely entirely on the community; if you speak a language that isn't fully translated yet, submitting translations there is greatly appreciated! If you like helping others, answering Q&A discussions here on GitHub and replying to people on our Discord is also always appreciated.
+If you want to contribute to Immich but you don't feel comfortable programming in our tech stack, there are other ways you can help the team.
+
+### Translations
+
+All our translations are done through [Weblate](https://hosted.weblate.org/projects/immich). These rely entirely on the community; if you speak a language that isn't fully translated yet, submitting translations there is greatly appreciated!
+
+### Datasets
+
+Help us improve our [Immich Datasets](https://datasets.immich.app) by submitting photos and videos taken from a variety of devices, including smartphones, DSLRs, and action cameras, as well as photos with unique features, such as panoramas, burst photos, and photo spheres. These datasets will be publically available for anyone to use, do not submit private/sensitive photos.
+
+### Community support
+
+If you like helping others, answering Q&A discussions here on GitHub and replying to people on our Discord is also always appreciated.

Makefile

@@ -52,7 +52,7 @@ attach-server:
 	docker exec -it docker_immich-server_1 sh
 
 renovate:
-  LOG_LEVEL=debug npx renovate --platform=local --repository-cache=reset
+  LOG_LEVEL=debug pnpm exec renovate --platform=local --repository-cache=reset
 
 # Directories that need to be created for volumes or build output
 VOLUME_DIRS = \

cli/.nvmrc

@@ -1 +1 @@
-24.13.0
+24.13.1

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immich/cli",
-  "version": "2.5.2",
+  "version": "2.5.6",
   "description": "Command Line Interface (CLI) for Immich",
   "type": "module",
   "exports": "./dist/index.js",
@@ -13,23 +13,23 @@
     "cli"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.8.0",
-    "@immich/sdk": "file:../open-api/typescript-sdk",
+    "@eslint/js": "^10.0.0",
+    "@immich/sdk": "workspace:*",
     "@types/byte-size": "^8.1.0",
     "@types/cli-progress": "^3.11.0",
     "@types/lodash-es": "^4.17.12",
     "@types/micromatch": "^4.0.9",
     "@types/mock-fs": "^4.13.1",
-    "@types/node": "^24.10.9",
+    "@types/node": "^24.10.13",
     "@vitest/coverage-v8": "^3.0.0",
     "byte-size": "^9.0.0",
     "cli-progress": "^3.12.0",
     "commander": "^12.0.0",
-    "eslint": "^9.14.0",
+    "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.1.3",
-    "eslint-plugin-unicorn": "^62.0.0",
-    "globals": "^16.0.0",
+    "eslint-plugin-unicorn": "^63.0.0",
+    "globals": "^17.0.0",
     "mock-fs": "^5.2.0",
     "prettier": "^3.7.4",
     "prettier-plugin-organize-imports": "^4.0.0",
@@ -45,8 +45,8 @@
     "build": "vite build",
     "build:dev": "vite build --sourcemap true",
     "lint": "eslint \"src/**/*.ts\" --max-warnings 0",
-    "lint:fix": "npm run lint -- --fix",
-    "prepack": "npm run build",
+    "lint:fix": "pnpm run lint --fix",
+    "prepack": "pnpm run build",
     "test": "vitest",
     "test:cov": "vitest --coverage",
     "format": "prettier --check .",
@@ -69,6 +69,6 @@
     "micromatch": "^4.0.8"
   },
   "volta": {
-    "node": "24.13.0"
+    "node": "24.13.1"
   }
 }

cli/src/commands/asset.spec.ts

@@ -7,7 +7,15 @@ import { describe, expect, it, MockedFunction, vi } from 'vitest';
 import { Action, checkBulkUpload, defaults, getSupportedMediaTypes, Reason } from '@immich/sdk';
 import createFetchMock from 'vitest-fetch-mock';
 
-import { checkForDuplicates, getAlbumName, startWatch, uploadFiles, UploadOptionsDto } from 'src/commands/asset';
+import {
+  checkForDuplicates,
+  deleteFiles,
+  findSidecar,
+  getAlbumName,
+  startWatch,
+  uploadFiles,
+  UploadOptionsDto,
+} from 'src/commands/asset';
 
 vi.mock('@immich/sdk');
 
@@ -309,3 +317,85 @@ describe('startWatch', () => {
     await fs.promises.rm(testFolder, { recursive: true, force: true });
   });
 });
+
+describe('findSidecar', () => {
+  let testDir: string;
+  let testFilePath: string;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-sidecar-'));
+    testFilePath = path.join(testDir, 'test.jpg');
+    fs.writeFileSync(testFilePath, 'test');
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('should find sidecar file with photo.xmp naming convention', () => {
+    const sidecarPath = path.join(testDir, 'test.xmp');
+    fs.writeFileSync(sidecarPath, 'xmp data');
+
+    const result = findSidecar(testFilePath);
+    expect(result).toBe(sidecarPath);
+  });
+
+  it('should find sidecar file with photo.ext.xmp naming convention', () => {
+    const sidecarPath = path.join(testDir, 'test.jpg.xmp');
+    fs.writeFileSync(sidecarPath, 'xmp data');
+
+    const result = findSidecar(testFilePath);
+    expect(result).toBe(sidecarPath);
+  });
+
+  it('should prefer photo.ext.xmp over photo.xmp when both exist', () => {
+    const sidecarPath1 = path.join(testDir, 'test.xmp');
+    const sidecarPath2 = path.join(testDir, 'test.jpg.xmp');
+    fs.writeFileSync(sidecarPath1, 'xmp data 1');
+    fs.writeFileSync(sidecarPath2, 'xmp data 2');
+
+    const result = findSidecar(testFilePath);
+    // Should return the first one found (photo.xmp) based on the order in the code
+    expect(result).toBe(sidecarPath1);
+  });
+
+  it('should return undefined when no sidecar file exists', () => {
+    const result = findSidecar(testFilePath);
+    expect(result).toBeUndefined();
+  });
+});
+
+describe('deleteFiles', () => {
+  let testDir: string;
+  let testFilePath: string;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-delete-'));
+    testFilePath = path.join(testDir, 'test.jpg');
+    fs.writeFileSync(testFilePath, 'test');
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('should delete asset and sidecar file when main file is deleted', async () => {
+    const sidecarPath = path.join(testDir, 'test.xmp');
+    fs.writeFileSync(sidecarPath, 'xmp data');
+
+    await deleteFiles([{ id: 'test-id', filepath: testFilePath }], [], { delete: true, concurrency: 1 });
+
+    expect(fs.existsSync(testFilePath)).toBe(false);
+    expect(fs.existsSync(sidecarPath)).toBe(false);
+  });
+
+  it('should not delete sidecar file when delete option is false', async () => {
+    const sidecarPath = path.join(testDir, 'test.xmp');
+    fs.writeFileSync(sidecarPath, 'xmp data');
+
+    await deleteFiles([{ id: 'test-id', filepath: testFilePath }], [], { delete: false, concurrency: 1 });
+
+    expect(fs.existsSync(testFilePath)).toBe(true);
+    expect(fs.existsSync(sidecarPath)).toBe(true);
+  });
+});

cli/src/commands/asset.ts

@@ -4,6 +4,7 @@ import {
   AssetBulkUploadCheckResult,
   AssetMediaResponseDto,
   AssetMediaStatus,
+  Permission,
   addAssetsToAlbum,
   checkBulkUpload,
   createAlbum,
@@ -16,17 +17,15 @@ import { Matcher, watch as watchFs } from 'chokidar';
 import { MultiBar, Presets, SingleBar } from 'cli-progress';
 import { chunk } from 'lodash-es';
 import micromatch from 'micromatch';
-import { Stats, createReadStream } from 'node:fs';
+import { Stats, createReadStream, existsSync } from 'node:fs';
 import { stat, unlink } from 'node:fs/promises';
 import path, { basename } from 'node:path';
 import { Queue } from 'src/queue';
-import { BaseOptions, Batcher, authenticate, crawl, sha1 } from 'src/utils';
+import { BaseOptions, Batcher, authenticate, crawl, requirePermissions, s, sha1 } from 'src/utils';
 
 const UPLOAD_WATCH_BATCH_SIZE = 100;
 const UPLOAD_WATCH_DEBOUNCE_TIME_MS = 10_000;
 
-const s = (count: number) => (count === 1 ? '' : 's');
-
 // TODO figure out why `id` is missing
 type AssetBulkUploadCheckResults = Array<AssetBulkUploadCheckResult & { id: string }>;
 type Asset = { id: string; filepath: string };
@@ -136,6 +135,7 @@ export const startWatch = async (
 
 export const upload = async (paths: string[], baseOptions: BaseOptions, options: UploadOptionsDto) => {
   await authenticate(baseOptions);
+  await requirePermissions([Permission.AssetUpload]);
 
   const scanFiles = await scan(paths, options);
 
@@ -180,18 +180,49 @@ export const checkForDuplicates = async (files: string[], { concurrency, skipHas
   }
 
   let multiBar: MultiBar | undefined;
+  let totalSize = 0;
+  const statsMap = new Map<string, Stats>();
+
+  // Calculate total size first
+  for (const filepath of files) {
+    const stats = await stat(filepath);
+    statsMap.set(filepath, stats);
+    totalSize += stats.size;
+  }
 
   if (progress) {
     multiBar = new MultiBar(
-      { format: '{message} | {bar} | {percentage}% | ETA: {eta}s | {value}/{total} assets' },
+      {
+        format: '{message} | {bar} | {percentage}% | ETA: {eta_formatted} | {value}/{total}',
+        formatValue: (v: number, options, type) => {
+          // Don't format percentage
+          if (type === 'percentage') {
+            return v.toString();
+          }
+          return byteSize(v).toString();
+        },
+        etaBuffer: 100, // Increase samples for ETA calculation
+      },
       Presets.shades_classic,
     );
+
+    // Ensure we restore cursor on interrupt
+    process.on('SIGINT', () => {
+      if (multiBar) {
+        multiBar.stop();
+      }
+      process.exit(0);
+    });
   } else {
-    console.log(`Received ${files.length} files, hashing...`);
+    console.log(`Received ${files.length} files (${byteSize(totalSize)}), hashing...`);
   }
 
-  const hashProgressBar = multiBar?.create(files.length, 0, { message: 'Hashing files          ' });
-  const checkProgressBar = multiBar?.create(files.length, 0, { message: 'Checking for duplicates' });
+  const hashProgressBar = multiBar?.create(totalSize, 0, {
+    message: 'Hashing files          ',
+  });
+  const checkProgressBar = multiBar?.create(totalSize, 0, {
+    message: 'Checking for duplicates',
+  });
 
   const newFiles: string[] = [];
   const duplicates: Asset[] = [];
@@ -211,7 +242,13 @@ export const checkForDuplicates = async (files: string[], { concurrency, skipHas
         }
       }
 
-      checkProgressBar?.increment(assets.length);
+      // Update progress based on total size of processed files
+      let processedSize = 0;
+      for (const asset of assets) {
+        const stats = statsMap.get(asset.id);
+        processedSize += stats?.size || 0;
+      }
+      checkProgressBar?.increment(processedSize);
     },
     { concurrency, retry: 3 },
   );
@@ -221,6 +258,10 @@ export const checkForDuplicates = async (files: string[], { concurrency, skipHas
 
   const queue = new Queue<string, AssetBulkUploadCheckItem[]>(
     async (filepath: string): Promise<AssetBulkUploadCheckItem[]> => {
+      const stats = statsMap.get(filepath);
+      if (!stats) {
+        throw new Error(`Stats not found for ${filepath}`);
+      }
       const dto = { id: filepath, checksum: await sha1(filepath) };
 
       results.push(dto);
@@ -231,7 +272,7 @@ export const checkForDuplicates = async (files: string[], { concurrency, skipHas
         void checkBulkUploadQueue.push(batch);
       }
 
-      hashProgressBar?.increment();
+      hashProgressBar?.increment(stats.size);
       return results;
     },
     { concurrency, retry: 3 },
@@ -362,23 +403,6 @@ export const uploadFiles = async (
 const uploadFile = async (input: string, stats: Stats): Promise<AssetMediaResponseDto> => {
   const { baseUrl, headers } = defaults;
 
-  const assetPath = path.parse(input);
-  const noExtension = path.join(assetPath.dir, assetPath.name);
-
-  const sidecarsFiles = await Promise.all(
-    // XMP sidecars can come in two filename formats. For a photo named photo.ext, the filenames are photo.ext.xmp and photo.xmp
-    [`${noExtension}.xmp`, `${input}.xmp`].map(async (sidecarPath) => {
-      try {
-        const stats = await stat(sidecarPath);
-        return new UploadFile(sidecarPath, stats.size);
-      } catch {
-        return false;
-      }
-    }),
-  );
-
-  const sidecarData = sidecarsFiles.find((file): file is UploadFile => file !== false);
-
   const formData = new FormData();
   formData.append('deviceAssetId', `${basename(input)}-${stats.size}`.replaceAll(/\s+/g, ''));
   formData.append('deviceId', 'CLI');
@@ -388,8 +412,15 @@ const uploadFile = async (input: string, stats: Stats): Promise<AssetMediaRespon
   formData.append('isFavorite', 'false');
   formData.append('assetData', new UploadFile(input, stats.size));
 
-  if (sidecarData) {
-    formData.append('sidecarData', sidecarData);
+  const sidecarPath = findSidecar(input);
+  if (sidecarPath) {
+    try {
+      const stats = await stat(sidecarPath);
+      const sidecarData = new UploadFile(sidecarPath, stats.size);
+      formData.append('sidecarData', sidecarData);
+    } catch {
+      // noop
+    }
   }
 
   const response = await fetch(`${baseUrl}/assets`, {
@@ -405,7 +436,19 @@ const uploadFile = async (input: string, stats: Stats): Promise<AssetMediaRespon
   return response.json();
 };
 
-const deleteFiles = async (uploaded: Asset[], duplicates: Asset[], options: UploadOptionsDto): Promise<void> => {
+export const findSidecar = (filepath: string): string | undefined => {
+  const assetPath = path.parse(filepath);
+  const noExtension = path.join(assetPath.dir, assetPath.name);
+
+  // XMP sidecars can come in two filename formats. For a photo named photo.ext, the filenames are photo.ext.xmp and photo.xmp
+  for (const sidecarPath of [`${noExtension}.xmp`, `${filepath}.xmp`]) {
+    if (existsSync(sidecarPath)) {
+      return sidecarPath;
+    }
+  }
+};
+
+export const deleteFiles = async (uploaded: Asset[], duplicates: Asset[], options: UploadOptionsDto): Promise<void> => {
   let fileCount = 0;
   if (options.delete) {
     fileCount += uploaded.length;
@@ -433,7 +476,15 @@ const deleteFiles = async (uploaded: Asset[], duplicates: Asset[], options: Uplo
 
   const chunkDelete = async (files: Asset[]) => {
     for (const assetBatch of chunk(files, options.concurrency)) {
-      await Promise.all(assetBatch.map((input: Asset) => unlink(input.filepath)));
+      await Promise.all(
+        assetBatch.map(async (input: Asset) => {
+          await unlink(input.filepath);
+          const sidecarPath = findSidecar(input.filepath);
+          if (sidecarPath) {
+            await unlink(sidecarPath);
+          }
+        }),
+      );
       deletionProgress.update(assetBatch.length);
     }
   };

cli/src/commands/auth.ts

@@ -1,7 +1,15 @@
-import { getMyUser } from '@immich/sdk';
+import { getMyUser, Permission } from '@immich/sdk';
 import { existsSync } from 'node:fs';
 import { mkdir, unlink } from 'node:fs/promises';
-import { BaseOptions, connect, getAuthFilePath, logError, withError, writeAuthFile } from 'src/utils';
+import {
+  BaseOptions,
+  connect,
+  getAuthFilePath,
+  logError,
+  requirePermissions,
+  withError,
+  writeAuthFile,
+} from 'src/utils';
 
 export const login = async (url: string, key: string, options: BaseOptions) => {
   console.log(`Logging in to ${url}`);
@@ -9,6 +17,7 @@ export const login = async (url: string, key: string, options: BaseOptions) => {
   const { configDirectory: configDir } = options;
 
   await connect(url, key);
+  await requirePermissions([Permission.UserRead]);
 
   const [error, user] = await withError(getMyUser());
   if (error) {

cli/src/commands/server-info.ts

@@ -1,8 +1,9 @@
-import { getAssetStatistics, getMyUser, getServerVersion, getSupportedMediaTypes } from '@immich/sdk';
-import { BaseOptions, authenticate } from 'src/utils';
+import { getAssetStatistics, getMyUser, getServerVersion, getSupportedMediaTypes, Permission } from '@immich/sdk';
+import { authenticate, BaseOptions, requirePermissions } from 'src/utils';
 
 export const serverInfo = async (options: BaseOptions) => {
   const { url } = await authenticate(options);
+  await requirePermissions([Permission.ServerAbout, Permission.AssetStatistics, Permission.UserRead]);
 
   const [versionInfo, mediaTypes, stats, userInfo] = await Promise.all([
     getServerVersion(),

cli/src/utils.ts

@@ -1,4 +1,4 @@
-import { getMyUser, init, isHttpError } from '@immich/sdk';
+import { ApiKeyResponseDto, getMyApiKey, getMyUser, init, isHttpError, Permission } from '@immich/sdk';
 import { convertPathToPattern, glob } from 'fast-glob';
 import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
@@ -34,6 +34,36 @@ export const authenticate = async (options: BaseOptions): Promise<AuthDto> => {
   return auth;
 };
 
+export const s = (count: number) => (count === 1 ? '' : 's');
+
+let _apiKey: ApiKeyResponseDto;
+export const requirePermissions = async (permissions: Permission[]) => {
+  if (!_apiKey) {
+    _apiKey = await getMyApiKey();
+  }
+
+  if (_apiKey.permissions.includes(Permission.All)) {
+    return;
+  }
+
+  const missing: Permission[] = [];
+
+  for (const permission of permissions) {
+    if (!_apiKey.permissions.includes(permission)) {
+      missing.push(permission);
+    }
+  }
+
+  if (missing.length > 0) {
+    const combined = missing.map((permission) => `"${permission}"`).join(', ');
+    console.log(
+      `Missing required permission${s(missing.length)}: ${combined}.
+Please make sure your API key has the correct permissions.`,
+    );
+    process.exit(1);
+  }
+};
+
 export const connect = async (url: string, key: string) => {
   const wellKnownUrl = new URL('.well-known/immich', url);
   try {

docker/docker-compose.dev.yml

@@ -14,33 +14,65 @@
 name: immich-dev
 
 services:
+  immich-app-base:
+    profiles: ['_base']
+    tmpfs:
+      - /tmp
+    volumes:
+      - ..:/usr/src/app
+      - pnpm_cache:/buildcache/pnpm_cache
+      - server_node_modules:/usr/src/app/server/node_modules
+      - web_node_modules:/usr/src/app/web/node_modules
+      - github_node_modules:/usr/src/app/.github/node_modules
+      - cli_node_modules:/usr/src/app/cli/node_modules
+      - docs_node_modules:/usr/src/app/docs/node_modules
+      - e2e_node_modules:/usr/src/app/e2e/node_modules
+      - sdk_node_modules:/usr/src/app/open-api/typescript-sdk/node_modules
+      - app_node_modules:/usr/src/app/node_modules
+      - sveltekit:/usr/src/app/web/.svelte-kit
+      - coverage:/usr/src/app/web/coverage
+
+  immich-init:
+    extends:
+      service: immich-app-base
+    profiles: !reset []
+    container_name: immich_init
+    image: immich-server-dev:latest
+    build:
+      context: ../
+      dockerfile: server/Dockerfile.dev
+      target: dev
+    command:
+      - |
+        pnpm install
+        touch /tmp/init-complete
+        exec tail -f /dev/null
+    volumes:
+      - pnpm_store_server:/buildcache/pnpm-store
+    restart: 'no'
+    healthcheck:
+      test: ['CMD', 'test', '-f', '/tmp/init-complete']
+      interval: 2s
+      timeout: 3s
+      retries: 300
+      start_period: 300s
+
   immich-server:
+    extends:
+      service: immich-app-base
+    profiles: !reset []
     container_name: immich_server
     command: ['immich-dev']
     image: immich-server-dev:latest
-    # extends:
-    #   file: hwaccel.transcoding.yml
-    #   service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
     build:
       context: ../
       dockerfile: server/Dockerfile.dev
       target: dev
     restart: unless-stopped
     volumes:
-      - ..:/usr/src/app
       - ${UPLOAD_LOCATION}/photos:/data
       - /etc/localtime:/etc/localtime:ro
-      - pnpm-store:/usr/src/app/.pnpm-store
-      - server-node_modules:/usr/src/app/server/node_modules
-      - web-node_modules:/usr/src/app/web/node_modules
-      - github-node_modules:/usr/src/app/.github/node_modules
-      - cli-node_modules:/usr/src/app/cli/node_modules
-      - docs-node_modules:/usr/src/app/docs/node_modules
-      - e2e-node_modules:/usr/src/app/e2e/node_modules
-      - sdk-node_modules:/usr/src/app/open-api/typescript-sdk/node_modules
-      - app-node_modules:/usr/src/app/node_modules
-      - sveltekit:/usr/src/app/web/.svelte-kit
-      - coverage:/usr/src/app/web/coverage
+      - pnpm_store_server:/buildcache/pnpm-store
       - ../plugins:/build/corePlugin
     env_file:
       - .env
@@ -63,6 +95,8 @@ services:
       - 9231:9231
       - 2283:2283
     depends_on:
+      immich-init:
+        condition: service_healthy
       redis:
         condition: service_started
       database:
@@ -71,6 +105,9 @@ services:
       disable: false
 
   immich-web:
+    extends:
+      service: immich-app-base
+    profiles: !reset []
     container_name: immich_web
     image: immich-web-dev:latest
     build:
@@ -84,20 +121,11 @@ services:
       - 3000:3000
       - 24678:24678
     volumes:
-      - ..:/usr/src/app
-      - pnpm-store:/usr/src/app/.pnpm-store
-      - server-node_modules:/usr/src/app/server/node_modules
-      - web-node_modules:/usr/src/app/web/node_modules
-      - github-node_modules:/usr/src/app/.github/node_modules
-      - cli-node_modules:/usr/src/app/cli/node_modules
-      - docs-node_modules:/usr/src/app/docs/node_modules
-      - e2e-node_modules:/usr/src/app/e2e/node_modules
-      - sdk-node_modules:/usr/src/app/open-api/typescript-sdk/node_modules
-      - app-node_modules:/usr/src/app/node_modules
-      - sveltekit:/usr/src/app/web/.svelte-kit
-      - coverage:/usr/src/app/web/coverage
+      - pnpm_store_web:/buildcache/pnpm-store
     restart: unless-stopped
     depends_on:
+      immich-init:
+        condition: service_healthy
       immich-server:
         condition: service_started
 
@@ -116,7 +144,7 @@ services:
       - 3003:3003
     volumes:
       - ../machine-learning/immich_ml:/usr/src/immich_ml
-      - model-cache:/cache
+      - model_cache:/cache
     env_file:
       - .env
     depends_on:
@@ -127,7 +155,7 @@ services:
 
   redis:
     container_name: immich_redis
-    image: docker.io/valkey/valkey:9@sha256:546304417feac0874c3dd576e0952c6bb8f06bb4093ea0c9ca303c73cf458f63
+    image: docker.io/valkey/valkey:9@sha256:930b41430fb727f533c5982fe509b6f04233e26d0f7354e04de4b0d5c706e44e
     healthcheck:
       test: redis-cli ping || exit 1
 
@@ -156,7 +184,7 @@ services:
   #   image: prom/prometheus
   #   volumes:
   #     - ./prometheus.yml:/etc/prometheus/prometheus.yml
-  #     - prometheus-data:/prometheus
+  #     - prometheus_data:/prometheus
 
   # first login uses admin/admin
   # add data source for http://immich-prometheus:9090 to get started
@@ -167,20 +195,22 @@ services:
   #     - 3000:3000
   #   image: grafana/grafana:10.3.3-ubuntu
   #   volumes:
-  #     - grafana-data:/var/lib/grafana
+  #     - grafana_data:/var/lib/grafana
 
 volumes:
-  model-cache:
-  prometheus-data:
-  grafana-data:
-  pnpm-store:
-  server-node_modules:
-  web-node_modules:
-  github-node_modules:
-  cli-node_modules:
-  docs-node_modules:
-  e2e-node_modules:
-  sdk-node_modules:
-  app-node_modules:
+  model_cache:
+  prometheus_data:
+  grafana_data:
+  pnpm_cache:
+  pnpm_store_server:
+  pnpm_store_web:
+  server_node_modules:
+  web_node_modules:
+  github_node_modules:
+  cli_node_modules:
+  docs_node_modules:
+  e2e_node_modules:
+  sdk_node_modules:
+  app_node_modules:
   sveltekit:
   coverage:

docker/docker-compose.prod.yml

@@ -56,7 +56,7 @@ services:
 
   redis:
     container_name: immich_redis
-    image: docker.io/valkey/valkey:9@sha256:546304417feac0874c3dd576e0952c6bb8f06bb4093ea0c9ca303c73cf458f63
+    image: docker.io/valkey/valkey:9@sha256:930b41430fb727f533c5982fe509b6f04233e26d0f7354e04de4b0d5c706e44e
     healthcheck:
       test: redis-cli ping || exit 1
     restart: always
@@ -97,7 +97,7 @@ services:
     command: ['./run.sh', '-disable-reporting']
     ports:
       - 3000:3000
-    image: grafana/grafana:12.3.1-ubuntu@sha256:d57f1365197aec34c4d80869d8ca45bb7787c7663904950dab214dfb40c1c2fd
+    image: grafana/grafana:12.3.2-ubuntu@sha256:6cca4b429a1dc0d37d401dee54825c12d40056c3c6f3f56e3f0d6318ce77749b
     volumes:
       - grafana-data:/var/lib/grafana
 

docker/docker-compose.rootless.yml

@@ -0,0 +1,100 @@
+#
+# WARNING: To install Immich, follow our guide: https://docs.immich.app/install/docker-compose
+#
+# Make sure to use the docker-compose.yml of the current release:
+#
+# https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
+#
+# The compose file on main may not be compatible with the latest release.
+
+name: immich
+
+services:
+  immich-server:
+    container_name: immich_server
+    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
+    # extends:
+    #   file: hwaccel.transcoding.yml
+    #   service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
+    user: '1000:1000'
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - NET_RAW
+    volumes:
+      # Do not edit the next line. If you want to change the media storage location on your system, edit the value of UPLOAD_LOCATION in the .env file
+      - ${UPLOAD_LOCATION}:/data
+      - /etc/localtime:/etc/localtime:ro
+    env_file:
+      - .env
+    ports:
+      - '2283:2283'
+    depends_on:
+      - redis
+      - database
+    restart: always
+    healthcheck:
+      disable: false
+
+  immich-machine-learning:
+    container_name: immich_machine_learning
+    # For hardware acceleration, add one of -[armnn, cuda, rocm, openvino, rknn] to the image tag.
+    # Example tag: ${IMMICH_VERSION:-release}-cuda
+    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
+    # extends: # uncomment this section for hardware acceleration - see https://docs.immich.app/features/ml-hardware-acceleration
+    #   file: hwaccel.ml.yml
+    #   service: cpu # set to one of [armnn, cuda, rocm, openvino, openvino-wsl, rknn] for accelerated inference - use the `-wsl` version for WSL2 where applicable
+    user: '1000:1000'
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - NET_RAW
+    volumes:
+      - ./ml-model-cache:/cache
+      - ./ml-dotcache:/.cache
+      - ./ml-config:/.config
+    env_file:
+      - .env
+    restart: always
+    healthcheck:
+      disable: false
+
+  redis:
+    container_name: immich_redis
+    image: docker.io/valkey/valkey:9@sha256:930b41430fb727f533c5982fe509b6f04233e26d0f7354e04de4b0d5c706e44e
+    user: '1000:1000'
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - NET_RAW
+    volumes:
+      - ./redis:/data
+    healthcheck:
+      test: redis-cli ping || exit 1
+    restart: always
+
+  database:
+    container_name: immich_postgres
+    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
+    user: '1000:1000'
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - NET_RAW
+    environment:
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+      POSTGRES_USER: ${DB_USERNAME}
+      POSTGRES_DB: ${DB_DATABASE_NAME}
+      POSTGRES_INITDB_ARGS: '--data-checksums'
+      # Uncomment the DB_STORAGE_TYPE: 'HDD' var if your database isn't stored on SSDs
+      # DB_STORAGE_TYPE: 'HDD'
+    volumes:
+      # Do not edit the next line. If you want to change the database storage location on your system, edit the value of DB_DATA_LOCATION in the .env file
+      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
+    shm_size: 128mb
+    restart: always
+    healthcheck:
+      disable: false
+
+volumes:
+  model-cache:

docker/docker-compose.yml

@@ -49,7 +49,7 @@ services:
 
   redis:
     container_name: immich_redis
-    image: docker.io/valkey/valkey:9@sha256:546304417feac0874c3dd576e0952c6bb8f06bb4093ea0c9ca303c73cf458f63
+    image: docker.io/valkey/valkey:9@sha256:930b41430fb727f533c5982fe509b6f04233e26d0f7354e04de4b0d5c706e44e
     healthcheck:
       test: redis-cli ping || exit 1
     restart: always

docs/.nvmrc

@@ -1 +1 @@
-24.13.0
+24.13.1

docs/docs/FAQ.mdx

@@ -402,6 +402,9 @@ To decrease Redis logs, you can add the following line to the `redis:` section o
 ### How can I run Immich as a non-root user?
 
 You can change the user in the container by setting the `user` argument in `docker-compose.yml` for each service.
+
+[Example docker-compose.yml file](https://github.com/immich-app/immich/blob/main/docker/docker-compose.rootless.yml)
+
 You may need to add mount points or docker volumes for the following internal container paths:
 
 - `immich-machine-learning:/.config`

docs/docs/administration/backup-and-restore.md

@@ -140,7 +140,8 @@ For advanced users or automated recovery scenarios, you can restore a database b
 
 ```bash title='Backup'
 # Replace <DB_USERNAME> with the database username - usually postgres unless you have changed it.
-docker exec -t immich_postgres pg_dumpall --clean --if-exists --username=<DB_USERNAME> | gzip > "/path/to/backup/dump.sql.gz"
+# Replace <DB_DATABASE_NAME> with the database name - usually immich unless you have changed it.
+docker exec -t immich_postgres pg_dump --clean --if-exists --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME> | gzip > "/path/to/backup/dump.sql.gz"
 ```
 
 ```bash title='Restore'
@@ -153,9 +154,10 @@ 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 <DB_USERNAME> with the database username - usually postgres unless you have changed it.
+# Replace <DB_DATABASE_NAME> 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=postgres --username=<DB_USERNAME>  # Restore Backup
+| docker exec -i immich_postgres psql --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME> --single-transaction --set ON_ERROR_STOP=on  # Restore Backup
 docker compose up -d            # Start remainder of Immich apps
 ```
 
@@ -164,7 +166,8 @@ docker compose up -d            # Start remainder of Immich apps
 
 ```powershell title='Backup'
 # Replace <DB_USERNAME> with the database username - usually postgres unless you have changed it.
-[System.IO.File]::WriteAllLines("C:\absolute\path\to\backup\dump.sql", (docker exec -t immich_postgres pg_dumpall --clean --if-exists --username=<DB_USERNAME>))
+# Replace <DB_DATABASE_NAME> with the database name - usually immich unless you have changed it.
+[System.IO.File]::WriteAllLines("C:\absolute\path\to\backup\dump.sql", (docker exec -t immich_postgres pg_dump --clean --if-exists --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME>))
 ```
 
 ```powershell title='Restore'
@@ -179,8 +182,9 @@ sleep 10                                          # Wait for Postgres server to
 docker exec -it immich_postgres bash              # Enter the Docker shell and run the following command
 # If your backup ends in `.gz`, replace `cat` with `gunzip --stdout`
 # Replace <DB_USERNAME> with the database username - usually postgres unless you have changed it.
+# Replace <DB_DATABASE_NAME> with the database name - usually immich unless you have changed it.
 
-cat "/dump.sql" | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" | psql --dbname=postgres --username=<DB_USERNAME>
+cat "/dump.sql" | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" | psql --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME>  --single-transaction --set ON_ERROR_STOP=on
 exit                                              # Exit the Docker shell
 docker compose up -d                              # Start remainder of Immich apps
 ```
@@ -188,6 +192,10 @@ docker compose up -d                              # Start remainder of Immich ap
   </TabItem>
 </Tabs>
 
+:::warning
+The backup and restore process changed in v2.5.0, if you have a backup created with an older version of Immich, use the documentation version selector to find manual restore instructions for your backup.
+:::
+
 :::note
 For the database restore to proceed properly, it requires a completely fresh install (i.e., the Immich server has never run since creating the Docker containers). If the Immich app has run, you may encounter Postgres conflicts (relation already exists, violated foreign key constraints, etc.). In this case, delete the `DB_DATA_LOCATION` folder to reset the database.
 :::
@@ -196,6 +204,10 @@ For the database restore to proceed properly, it requires a completely fresh ins
 Some deployment methods make it difficult to start the database without also starting the server. In these cases, set the environment variable `DB_SKIP_MIGRATIONS=true` before starting the services. This prevents the server from running migrations that interfere with the restore process. Remove this variable and restart services after the database is restored.
 :::
 
+:::tip
+The provided restore process ensures your database is never in a broken state by committing all changes in one transaction. This may be undesirable behaviour in some circumstances, you can disable it by removing `--single-transaction --set ON_ERROR_STOP=on` from the command.
+:::
+
 ## Filesystem
 
 Immich stores two types of content in the filesystem: (a) original, unmodified assets (photos and videos), and (b) generated content. We recommend backing up the entire contents of `UPLOAD_LOCATION`, but only the original content is critical, which is stored in the following folders:

docs/docs/administration/oauth.md

@@ -56,11 +56,13 @@ Once you have a new OAuth client application configured, Immich can be configure
 | Setting                                              | Type    | Default              | Description                                                                         |
 | ---------------------------------------------------- | ------- | -------------------- | ----------------------------------------------------------------------------------- |
 | Enabled                                              | boolean | false                | Enable/disable OAuth                                                                |
-| Issuer URL                                           | URL     | (required)           | Required. Self-discovery URL for client (from previous step)                        |
-| Client ID                                            | string  | (required)           | Required. Client ID (from previous step)                                            |
-| Client Secret                                        | string  | (required)           | Required. Client Secret (previous step)                                             |
-| Scope                                                | string  | openid email profile | Full list of scopes to send with the request (space delimited)                      |
-| Signing Algorithm                                    | string  | RS256                | The algorithm used to sign the id token (examples: RS256, HS256)                    |
+| `issuer_url`                                         | URL     | (required)           | Required. Self-discovery URL for client (from previous step)                        |
+| `client_id`                                          | string  | (required)           | Required. Client ID (from previous step)                                            |
+| `client_secret`                                      | string  | (required)           | Required. Client Secret (previous step)                                             |
+| `scope`                                              | string  | openid email profile | Full list of scopes to send with the request (space delimited)                      |
+| `id_token_signed_response_alg`                       | string  | RS256                | The algorithm used to sign the id token (examples: RS256, HS256)                    |
+| `userinfo_signed_response_alg`                       | string  | none                 | The algorithm used to sign the userinfo response (examples: RS256, HS256)           |
+| Request timeout                                      | string  | 30,000 (30 seconds)  | Number of milliseconds to wait for http requests to complete before giving up       |
 | Storage Label Claim                                  | string  | preferred_username   | Claim mapping for the user's storage label**¹**                                     |
 | Role Claim                                           | string  | immich_role          | Claim mapping for the user's role. (should return "user" or "admin")**¹**           |
 | Storage Quota Claim                                  | string  | immich_quota         | Claim mapping for the user's storage**¹**                                           |

docs/docs/administration/reverse-proxy.md

@@ -98,7 +98,6 @@ entryPoints:
       respondingTimeouts:
         readTimeout: 600s
         idleTimeout: 600s
-        writeTimeout: 600s
 ```
 
 The second part is in the `docker-compose.yml` file where immich is in. Add the Traefik specific labels like in the example.

docs/docs/developer/devcontainers.md

@@ -44,7 +44,7 @@ While this guide focuses on VS Code, you have many options for Dev Container dev
 **Self-Hostable Options:**
 
 - [Coder](https://coder.com) - Enterprise-focused, requires Terraform knowledge, self-managed
-- [DevPod](https://devpod.sh) - Client-only tool with excellent devcontainer.json support, works with any provider (local, cloud, or on-premise)
+- [DevPod](https://devpod.sh) - Client-only tool with excellent devcontainer.json support, works with any provider (local, cloud, or on-premise). Check [quick-start guide](#quick-start-guide-for-devpod-with-docker)
   :::
 
 ## Dev Container Services
@@ -408,7 +408,27 @@ If you encounter issues:
 1. Check container logs: View → Output → Select "Dev Containers"
 2. Rebuild without cache: "Dev Containers: Rebuild Container Without Cache"
 3. Review [common Docker issues](https://docs.docker.com/desktop/troubleshoot/)
-4. Ask in [Discord](https://discord.immich.app) `#help-desk-support` channel
+4. Ask in [Discord](https://discord.immich.app) `#contributing` channel
+
+### Quick-start guide for DevPod with docker
+
+You will need DevPod CLI (check [DevPod CLI installation guide](https://devpod.sh/docs/getting-started/install)) and Docker Desktop.
+
+```sh
+# 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 .
+```
 
 ## Mobile Development
 

docs/docs/developer/setup.md

@@ -90,10 +90,13 @@ To see local changes to `@immich/ui` in Immich, do the following:
 
 #### Setup
 
-1. Setup Flutter toolchain using FVM.
-2. Run `flutter pub get` to install the dependencies.
-3. Run `make translation` to generate the translation file.
-4. Run `fvm flutter run` to start the app.
+1. [Install mise](https://mise.jdx.dev/installing-mise.html).
+2. Change to the immich (root) directory and trust the mise config with `mise trust`.
+3. Install tools with mise: `mise install`.
+4. Change to the `mobile/` directory.
+5. Run `flutter pub get` to install the dependencies.
+6. Run `make translation` to generate the translation file.
+7. Run `flutter run` to start the app.
 
 #### Translation
 

docs/docs/features/command-line-interface.md

@@ -183,7 +183,7 @@ For example to get a list of files that would be uploaded for further
 processing:
 
 ```bash
-immich upload --dry-run . | tail -n +6 | jq .newFiles[]
+immich upload --dry-run --json-output . | tail -n +6 | jq .newFiles[]
 ```
 
 ### Obtain the API Key

docs/docs/features/libraries.md

@@ -80,6 +80,10 @@ There is an automatic scan job that is scheduled to run once a day. Its schedule
 
 This job also cleans up any libraries stuck in deletion. It is possible to trigger the cleanup by clicking "Scan all libraries" in the library management page.
 
+### Deleting a Library
+
+When deleting an external library, all assets inside are immediately deleted along with the library. Note that while a library can take a long time to fully delete in the background, it is immediately removed from the library list. If the deletion process is interrupted (for example, due to server restart), it will be cleaned up in the next nightly cron job. The cleanup process can also be manually initiated by clicking the "Scan All Libraries" button in the library list.
+
 ## Usage
 
 Let's show a concrete example where we add an existing gallery to Immich. Here, we have the following folders we want to add:

docs/docs/features/ml-hardware-acceleration.md

@@ -86,8 +86,8 @@ You do not need to redo any machine learning jobs after enabling hardware accele
 ## Setup
 
 1. If you do not already have it, download the latest [`hwaccel.ml.yml`][hw-file] file and ensure it's in the same folder as the `docker-compose.yml`.
-2. In the `docker-compose.yml` under `immich-machine-learning`, uncomment the `extends` section and change `cpu` to the appropriate backend.
-3. Still in `immich-machine-learning`, add one of -[armnn, cuda, rocm, openvino, rknn] to the `image` section's tag at the end of the line.
+2. In `immich-machine-learning`, add one of -[armnn, cuda, rocm, openvino, rknn] to the `image` section's tag at the end of the line.
+3. Still in the `docker-compose.yml` under `immich-machine-learning`, uncomment the `extends` section and change `cpu` to the appropriate backend.
 4. Redeploy the `immich-machine-learning` container with these updated settings.
 
 ### Confirming Device Usage

docs/docs/features/mobile-app.mdx

@@ -66,7 +66,7 @@ Now make sure that the local album is selected in the backup screen (steps 1-2 a
     - **Keep on device:** You can choose to restrict removal to `Always keep` **All photos** or **All videos**, regardless of other settings. This setting can hamper freeing up space significantly — with 80 GB of videos and 40 GB photos, selecting `Always keep photos` retains thousands of photos on your device.
 
 2.  **Scan & Review:** Before any files are removed, you are presented with a review screen to verify which items will be deleted and how much storage is reclamable.
-3.  **Deletion:** Confirmed items are moved to your device's native Trash/Recycle Bin.
+3.  **Deletion:** Confirmed items are moved to your device's native Trash/Recycle Bin. For large queues, Immich processes deletion in batches for stability (`2000` assets per batch on Android, `10000` per batch on iOS).
 
 :::info reclaim storage
 To use the reclaimed space right away, you must empty the system/gallery trash manually outside of Immich.

docs/docs/features/supported-formats.md

@@ -38,6 +38,7 @@ For the full list, refer to the [Immich source code](https://github.com/immich-a
 | `MP2T`      | `.mts` `.m2ts` `.m2t` | :white_check_mark: |       |
 | `MP4`       | `.mp4` `.insv`        | :white_check_mark: |       |
 | `MPEG`      | `.mpg` `.mpe` `.mpeg` | :white_check_mark: |       |
+| `MXF`       | `.mxf`                | :white_check_mark: |       |
 | `QUICKTIME` | `.mov`                | :white_check_mark: |       |
 | `WEBM`      | `.webm`               | :white_check_mark: |       |
 | `WMV`       | `.wmv`                | :white_check_mark: |       |

docs/docs/install/config-file.md

@@ -8,7 +8,8 @@ A config file can be provided as an alternative to the UI configuration.
 
 ### Step 1 - Create a new config file
 
-In JSON format, create a new config file (e.g. `immich.json`) and put it in a location that can be accessed by Immich.
+In JSON format, create a new config file (e.g. `immich.json`) and put it in a location mounted in the container that can be accessed by Immich.
+YAML-formatted config files are also supported.
 The default configuration looks like this:
 
 <details>
@@ -251,6 +252,15 @@ So you can just grab it from there, paste it into a file and you're pretty much
 In your `.env` file, set the variable `IMMICH_CONFIG_FILE` to the path of your config.
 For more information, refer to the [Environment Variables](/install/environment-variables.md) section.
 
-:::tip
-YAML-formatted config files are also supported.
-:::
+:::info Docker Compose
+In your `.env` file, the variables `UPLOAD_LOCATION` and `DB_DATA_LOCATION` concern the location on the host.
+However, the variable `IMMICH_CONFIG_FILE` concerns the location inside the container, and informs the `immich-server` container that a configuration file is present.
+
+It is recommended to reuse this variable in your `docker-compose.yml`:
+
+```yaml
+volumes:
+  - ./configuration.yml:${IMMICH_CONFIG_FILE}
+```
+
+::

docs/docs/install/synology.md

@@ -8,8 +8,6 @@ sidebar_position: 85
 This is a community contribution and not officially supported by the Immich team, but included here for convenience.
 
 Community support can be found in the dedicated channel on the [Discord Server](https://discord.immich.app/).
-
-**Please report app issues to the corresponding [Github Repository](https://github.com/truenas/charts/tree/master/community/immich).**
 :::
 
 Immich can easily be installed on a Synology NAS using Container Manager within DSM. If you have not installed Container Manager already, you can install it in the Packages Center. Refer to the [Container Manager docs](https://kb.synology.com/en-us/DSM/help/ContainerManager/docker_desc?version=7) for more information on using Container Manager.

docs/docs/install/upgrading.md

@@ -26,6 +26,16 @@ docker image prune
 [breaking]: https://github.com/immich-app/immich/discussions?discussions_q=label%3Achangelog%3Abreaking-change+sort%3Adate_created
 [releases]: https://github.com/immich-app/immich/releases
 
+## Versioning Policy
+
+Immich follows [semantic versioning][semver], which tags releases in the format `<major>.<minor>.<patch>`. We intend for breaking changes to be limited to major version releases.
+You can configure your Docker image to point to the current major version by using a metatag, such as `:v2`.
+
+Currently, we have no plans to backport patches to earlier versions. We encourage all users to run the most recent release of Immich.
+Switching back to an earlier version, even within the same minor release tag, is not supported.
+
+[semver]: https://semver.org/
+
 ## Migrating to VectorChord
 
 :::info

docs/mise.toml

@@ -23,3 +23,9 @@ run = "prettier --check ."
 [tasks."format-fix"]
 env._.path = "./node_modules/.bin"
 run = "prettier --write ."
+
+[tasks.deploy]
+run = "wrangler pages deploy build --project-name=${PROJECT_NAME} --branch=${BRANCH_NAME}"
+
+[tools]
+wrangler = "4.66.0"

docs/package.json

@@ -8,7 +8,7 @@
     "format:fix": "prettier --write .",
     "start": "docusaurus start --port 3005",
     "copy:openapi": "jq -c < ../open-api/immich-openapi-specs.json > ./static/openapi.json || exit 0",
-    "build": "npm run copy:openapi && docusaurus build",
+    "build": "pnpm run copy:openapi && docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
@@ -58,6 +58,6 @@
     "node": ">=20"
   },
   "volta": {
-    "node": "24.13.0"
+    "node": "24.13.1"
   }
 }

docs/src/pages/errors.md

@@ -32,3 +32,7 @@ If you would like to migrate from one media location to another, simply successf
 4. Start up Immich
 
 After version `1.136.0`, Immich can detect when a media location has moved and will automatically update the database paths to keep them in sync.
+
+## Schema drift
+
+Schema drift is when the database schema is out of sync with the code. This could be the result of manual database tinkering, issues during a database restore, or something else. Schema drift can lead to data corruption, application bugs, and other unpredictable behavior. Please reconcile the differences as soon as possible. Specifically, missing `CONSTRAINT`s can result in duplicate assets being uploaded, since the server relies on a checksum `CONSTRAINT` to prevent duplicates.

docs/static/archived-versions.json

@@ -1,7 +1,7 @@
 [
   {
-    "label": "v2.5.2",
-    "url": "https://docs.v2.5.2.archive.immich.app"
+    "label": "v2.5.6",
+    "url": "https://docs.v2.5.6.archive.immich.app"
   },
   {
     "label": "v2.4.1",

e2e/.nvmrc

@@ -1 +1 @@
-24.13.0
+24.13.1

e2e/docker-compose.dev.yml

@@ -1,86 +1,77 @@
 name: immich-e2e
 
 services:
+  immich-app-base:
+    extends:
+      file: ../docker/docker-compose.dev.yml
+      service: immich-app-base
+
+  immich-init:
+    extends:
+      file: ../docker/docker-compose.dev.yml
+      service: immich-init
+    container_name: immich-e2e-init
+
   immich-server:
+    extends:
+      file: ../docker/docker-compose.dev.yml
+      service: immich-server
     container_name: immich-e2e-server
-    command: ['immich-dev']
-    image: immich-server-dev:latest
-    build:
-      context: ../
-      dockerfile: server/Dockerfile.dev
-      target: dev
+    ports: !reset []
+    env_file: !reset []
     environment:
-      - DB_HOSTNAME=database
-      - DB_USERNAME=postgres
-      - DB_PASSWORD=postgres
-      - DB_DATABASE_NAME=immich
-      - IMMICH_MACHINE_LEARNING_ENABLED=false
-      - IMMICH_TELEMETRY_INCLUDE=all
-      - IMMICH_ENV=testing
-      - IMMICH_PORT=2285
-      - IMMICH_IGNORE_MOUNT_CHECK_ERRORS=true
+      DB_HOSTNAME: database
+      DB_USERNAME: postgres
+      DB_PASSWORD: postgres
+      DB_DATABASE_NAME: immich
+      IMMICH_MACHINE_LEARNING_ENABLED: 'false'
+      IMMICH_TELEMETRY_INCLUDE: all
+      IMMICH_ENV: testing
+      IMMICH_PORT: '2285'
+      IMMICH_IGNORE_MOUNT_CHECK_ERRORS: 'true'
     volumes:
       - ./test-assets:/test-assets
-      - ..:/usr/src/app
-      - ${UPLOAD_LOCATION}/photos:/data
-      - /etc/localtime:/etc/localtime:ro
-      - pnpm-store:/usr/src/app/.pnpm-store
-      - server-node_modules:/usr/src/app/server/node_modules
-      - web-node_modules:/usr/src/app/web/node_modules
-      - github-node_modules:/usr/src/app/.github/node_modules
-      - cli-node_modules:/usr/src/app/cli/node_modules
-      - docs-node_modules:/usr/src/app/docs/node_modules
-      - e2e-node_modules:/usr/src/app/e2e/node_modules
-      - sdk-node_modules:/usr/src/app/open-api/typescript-sdk/node_modules
-      - app-node_modules:/usr/src/app/node_modules
-      - sveltekit:/usr/src/app/web/.svelte-kit
-      - coverage:/usr/src/app/web/coverage
-      - ../plugins:/build/corePlugin
     depends_on:
+      immich-init:
+        condition: service_healthy
       redis:
         condition: service_started
       database:
         condition: service_healthy
 
   immich-web:
+    extends:
+      file: ../docker/docker-compose.dev.yml
+      service: immich-web
     container_name: immich-e2e-web
-    image: immich-web-dev:latest
-    build:
-      context: ../
-      dockerfile: server/Dockerfile.dev
-      target: dev
-    command: ['immich-web']
-    ports:
+    ports: !override
       - 2285:3000
     environment:
-      - IMMICH_SERVER_URL=http://immich-server:2285/
-    volumes:
-      - ..:/usr/src/app
-      - pnpm-store:/usr/src/app/.pnpm-store
-      - server-node_modules:/usr/src/app/server/node_modules
-      - web-node_modules:/usr/src/app/web/node_modules
-      - github-node_modules:/usr/src/app/.github/node_modules
-      - cli-node_modules:/usr/src/app/cli/node_modules
-      - docs-node_modules:/usr/src/app/docs/node_modules
-      - e2e-node_modules:/usr/src/app/e2e/node_modules
-      - sdk-node_modules:/usr/src/app/open-api/typescript-sdk/node_modules
-      - app-node_modules:/usr/src/app/node_modules
-      - sveltekit:/usr/src/app/web/.svelte-kit
-      - coverage:/usr/src/app/web/coverage
+      IMMICH_SERVER_URL: http://immich-server:2285/
+    depends_on:
+      immich-init:
+        condition: service_healthy
     restart: unless-stopped
 
   redis:
-    image: redis:6.2-alpine@sha256:37e002448575b32a599109664107e374c8709546905c372a34d64919043b9ceb
+    extends:
+      file: ../docker/docker-compose.dev.yml
+      service: redis
+    container_name: immich-e2e-redis
 
   database:
-    image: ghcr.io/immich-app/postgres:14-vectorchord0.3.0@sha256:6f3e9d2c2177af16c2988ff71425d79d89ca630ec2f9c8db03209ab716542338
+    extends:
+      file: ../docker/docker-compose.dev.yml
+      service: database
+    container_name: immich-e2e-postgres
     command: -c fsync=off -c shared_preload_libraries=vchord.so -c config_file=/var/lib/postgresql/data/postgresql.conf
+    env_file: !reset []
+    ports: !override
+      - 5435:5432
     environment:
       POSTGRES_PASSWORD: postgres
       POSTGRES_USER: postgres
       POSTGRES_DB: immich
-    ports:
-      - 5435:5432
     healthcheck:
       test: ['CMD-SHELL', 'pg_isready -U postgres -d immich']
       interval: 1s
@@ -89,17 +80,19 @@ services:
       start_period: 10s
 
 volumes:
-  model-cache:
-  prometheus-data:
-  grafana-data:
-  pnpm-store:
-  server-node_modules:
-  web-node_modules:
-  github-node_modules:
-  cli-node_modules:
-  docs-node_modules:
-  e2e-node_modules:
-  sdk-node_modules:
-  app-node_modules:
+  model_cache:
+  prometheus_data:
+  grafana_data:
+  pnpm_cache:
+  pnpm_store_server:
+  pnpm_store_web:
+  server_node_modules:
+  web_node_modules:
+  github_node_modules:
+  cli_node_modules:
+  docs_node_modules:
+  e2e_node_modules:
+  sdk_node_modules:
+  app_node_modules:
   sveltekit:
   coverage:

e2e/docker-compose.yml

@@ -2,6 +2,7 @@ name: immich-e2e
 
 services:
   e2e-auth-server:
+    container_name: immich-e2e-auth-server
     build:
       context: ../e2e-auth-server
     ports:
@@ -22,15 +23,15 @@ services:
         - BUILD_SOURCE_REF=e2e
         - BUILD_SOURCE_COMMIT=e2eeeeeeeeeeeeeeeeee
     environment:
-      - DB_HOSTNAME=database
-      - DB_USERNAME=postgres
-      - DB_PASSWORD=postgres
-      - DB_DATABASE_NAME=immich
-      - IMMICH_MACHINE_LEARNING_ENABLED=false
-      - IMMICH_TELEMETRY_INCLUDE=all
-      - IMMICH_ENV=testing
-      - IMMICH_PORT=2285
-      - IMMICH_IGNORE_MOUNT_CHECK_ERRORS=true
+      DB_HOSTNAME: database
+      DB_USERNAME: postgres
+      DB_PASSWORD: postgres
+      DB_DATABASE_NAME: immich
+      IMMICH_MACHINE_LEARNING_ENABLED: 'false'
+      IMMICH_TELEMETRY_INCLUDE: all
+      IMMICH_ENV: testing
+      IMMICH_PORT: '2285'
+      IMMICH_IGNORE_MOUNT_CHECK_ERRORS: 'true'
     volumes:
       - ./test-assets:/test-assets
     depends_on:
@@ -42,10 +43,14 @@ services:
       - 2285:2285
 
   redis:
-    image: redis:6.2-alpine@sha256:37e002448575b32a599109664107e374c8709546905c372a34d64919043b9ceb
+    container_name: immich-e2e-redis
+    image: docker.io/valkey/valkey:9@sha256:930b41430fb727f533c5982fe509b6f04233e26d0f7354e04de4b0d5c706e44e
+    healthcheck:
+      test: redis-cli ping || exit 1
 
   database:
-    image: ghcr.io/immich-app/postgres:14-vectorchord0.3.0@sha256:6f3e9d2c2177af16c2988ff71425d79d89ca630ec2f9c8db03209ab716542338
+    container_name: immich-e2e-postgres
+    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:bcf63357191b76a916ae5eb93464d65c07511da41e3bf7a8416db519b40b1c23
     command: -c fsync=off -c shared_preload_libraries=vchord.so -c config_file=/var/lib/postgresql/data/postgresql.conf
     environment:
       POSTGRES_PASSWORD: postgres
@@ -53,6 +58,7 @@ services:
       POSTGRES_DB: immich
     ports:
       - 5435:5432
+    shm_size: 128mb
     healthcheck:
       test: ['CMD-SHELL', 'pg_isready -U postgres -d immich']
       interval: 1s

e2e/package.json

@@ -1,43 +1,51 @@
 {
   "name": "immich-e2e",
-  "version": "2.5.2",
+  "version": "2.5.6",
   "description": "",
   "main": "index.js",
   "type": "module",
   "scripts": {
     "test": "vitest --run",
     "test:watch": "vitest",
-    "test:web": "npx playwright test",
-    "start:web": "npx playwright test --ui",
+    "test:maintenance": "vitest --run --config vitest.maintenance.config.ts",
+    "test:web": "pnpm exec playwright test --project=web",
+    "test:web:maintenance": "pnpm exec playwright test --project=maintenance",
+    "test:web:ui": "pnpm exec playwright test --project=ui",
+    "start:web": "pnpm exec playwright test --ui --project=web",
+    "start:web:maintenance": "pnpm exec playwright test --ui --project=maintenance",
+    "start:web:ui": "pnpm exec playwright test --ui --project=ui",
     "format": "prettier --check .",
     "format:fix": "prettier --write .",
     "lint": "eslint \"src/**/*.ts\" --max-warnings 0",
-    "lint:fix": "npm run lint -- --fix",
-    "check": "tsc --noEmit"
+    "lint:fix": "pnpm run lint --fix",
+    "check": "tsc --noEmit",
+    "screenshots": "pnpm exec playwright test --config playwright.screenshot.config.ts",
+    "screenshots:compare": "pnpm exec tsx src/screenshots/compare.ts",
+    "screenshots:analyze": "pnpm exec tsx src/screenshots/analyze-deps.ts"
   },
   "keywords": [],
   "author": "",
   "license": "GNU Affero General Public License version 3",
   "devDependencies": {
-    "@eslint/js": "^9.8.0",
+    "@eslint/js": "^10.0.0",
     "@faker-js/faker": "^10.1.0",
-    "@immich/cli": "file:../cli",
-    "@immich/e2e-auth-server": "file:../e2e-auth-server",
-    "@immich/sdk": "file:../open-api/typescript-sdk",
+    "@immich/cli": "workspace:*",
+    "@immich/e2e-auth-server":  "workspace:*",
+    "@immich/sdk": "workspace:*",
     "@playwright/test": "^1.44.1",
     "@socket.io/component-emitter": "^3.1.2",
     "@types/luxon": "^3.4.2",
-    "@types/node": "^24.10.9",
+    "@types/node": "^24.10.13",
     "@types/pg": "^8.15.1",
     "@types/pngjs": "^6.0.4",
     "@types/supertest": "^6.0.2",
     "dotenv": "^17.2.3",
-    "eslint": "^9.14.0",
+    "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.1.3",
-    "eslint-plugin-unicorn": "^62.0.0",
-    "exiftool-vendored": "^34.3.0",
-    "globals": "^16.0.0",
+    "eslint-plugin-unicorn": "^63.0.0",
+    "exiftool-vendored": "^35.0.0",
+    "globals": "^17.0.0",
     "luxon": "^3.4.4",
     "pg": "^8.11.3",
     "pngjs": "^7.0.0",
@@ -46,12 +54,13 @@
     "sharp": "^0.34.5",
     "socket.io-client": "^4.7.4",
     "supertest": "^7.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "typescript-eslint": "^8.28.0",
     "utimes": "^5.2.1",
     "vitest": "^3.0.0"
   },
   "volta": {
-    "node": "24.13.0"
+    "node": "24.13.1"
   }
 }

e2e/playwright.config.ts

@@ -3,7 +3,7 @@ import dotenv from 'dotenv';
 import { cpus } from 'node:os';
 import { resolve } from 'node:path';
 
-dotenv.config({ path: resolve(import.meta.dirname, '.env') });
+dotenv.config({ quiet: true, path: resolve(import.meta.dirname, '.env') });
 
 export const playwrightHost = process.env.PLAYWRIGHT_HOST ?? '127.0.0.1';
 export const playwrightDbHost = process.env.PLAYWRIGHT_DB_HOST ?? '127.0.0.1';
@@ -14,7 +14,8 @@ export const playwrightDisableWebserver = process.env.PLAYWRIGHT_DISABLE_WEBSERV
 process.env.PW_EXPERIMENTAL_SERVICE_WORKER_NETWORK_EVENTS = '1';
 
 const config: PlaywrightTestConfig = {
-  testDir: './src/web/specs',
+  testDir: './src/specs/server',
+  testMatch: /.*\.e2e-spec\.ts/,
   fullyParallel: false,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 4 : 0,
@@ -28,54 +29,28 @@ const config: PlaywrightTestConfig = {
     },
   },
 
-  testMatch: /.*\.e2e-spec\.ts/,
-
   workers: process.env.CI ? 4 : Math.round(cpus().length * 0.75),
 
   projects: [
     {
-      name: 'chromium',
+      name: 'web',
       use: { ...devices['Desktop Chrome'] },
-      testMatch: /.*\.e2e-spec\.ts/,
+      testDir: './src/specs/web',
       workers: 1,
     },
     {
       name: 'ui',
       use: { ...devices['Desktop Chrome'] },
-      testMatch: /.*\.ui-spec\.ts/,
+      testDir: './src/ui/specs',
       fullyParallel: true,
       workers: process.env.CI ? 3 : Math.max(1, Math.round(cpus().length * 0.75) - 1),
     },
-
-    // {
-    //   name: 'firefox',
-    //   use: { ...devices['Desktop Firefox'] },
-    // },
-
-    // {
-    //   name: 'webkit',
-    //   use: { ...devices['Desktop Safari'] },
-    // },
-
-    /* Test against mobile viewports. */
-    // {
-    //   name: 'Mobile Chrome',
-    //   use: { ...devices['Pixel 5'] },
-    // },
-    // {
-    //   name: 'Mobile Safari',
-    //   use: { ...devices['iPhone 12'] },
-    // },
-
-    /* Test against branded browsers. */
-    // {
-    //   name: 'Microsoft Edge',
-    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
-    // },
-    // {
-    //   name: 'Google Chrome',
-    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
-    // },
+    {
+      name: 'maintenance',
+      use: { ...devices['Desktop Chrome'] },
+      testDir: './src/specs/maintenance/web',
+      workers: 1,
+    },
   ],
 
   /* Run your local dev server before starting the tests */

e2e/playwright.screenshot.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig, devices } from '@playwright/test';
+
+const baseUrl = process.env.SCREENSHOT_BASE_URL ?? 'http://127.0.0.1:4173';
+
+export default defineConfig({
+  testDir: './src/screenshots',
+  testMatch: /run-scenarios\.ts/,
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: 0,
+  reporter: 'list',
+  use: {
+    baseURL: baseUrl,
+    screenshot: 'off',
+    trace: 'off',
+  },
+  workers: 1,
+  projects: [
+    {
+      name: 'screenshots',
+      use: {
+        ...devices['Desktop Chrome'],
+        viewport: { width: 1920, height: 1080 },
+      },
+    },
+  ],
+});

e2e/src/responses.ts

@@ -43,10 +43,10 @@ export const errorDto = {
     message: 'Invalid share key',
     correlationId: expect.any(String),
   },
-  invalidSharePassword: {
+  passwordRequired: {
     error: 'Unauthorized',
     statusCode: 401,
-    message: 'Invalid password',
+    message: 'Password required',
     correlationId: expect.any(String),
   },
   badRequest: (message: any = null) => ({

e2e/src/screenshots/analyze-deps.ts

@@ -0,0 +1,249 @@
+/**
+ * Reverse dependency analyzer for the Immich web app.
+ *
+ * Given a list of changed files, traces upward through the import graph
+ * to find which +page.svelte routes are affected, then maps those to URL paths.
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+const WEB_SRC = resolve(import.meta.dirname, '../../../web/src');
+const LIB_ALIAS = resolve(WEB_SRC, 'lib');
+
+/** Collect all .svelte, .ts, .js files under web/src/ */
+function collectFiles(dir: string): string[] {
+  const results: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry === 'node_modules' || entry === '.svelte-kit') {
+        continue;
+      }
+      results.push(...collectFiles(full));
+    } else if (/\.(svelte|ts|js)$/.test(entry)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/** Extract import specifiers from a file's source text. */
+function extractImports(source: string): string[] {
+  const specifiers: string[] = [];
+
+  // Match: import ... from '...'  /  import '...'  /  export ... from '...'
+  const importRegex = /(?:import|export)\s+(?:[\s\S]*?\s+from\s+)?['"]([^'"]+)['"]/g;
+  let match;
+  while ((match = importRegex.exec(source)) !== null) {
+    specifiers.push(match[1]);
+  }
+
+  // Match dynamic imports: import('...')
+  const dynamicRegex = /import\(\s*['"]([^'"]+)['"]\s*\)/g;
+  while ((match = dynamicRegex.exec(source)) !== null) {
+    specifiers.push(match[1]);
+  }
+
+  return specifiers;
+}
+
+/** Resolve an import specifier to an absolute file path (or null if external). */
+function resolveImport(specifier: string, fromFile: string, allFiles: Set<string>): string | null {
+  // Handle $lib alias
+  let resolved: string;
+  if (specifier.startsWith('$lib/') || specifier === '$lib') {
+    resolved = specifier.replace('$lib', LIB_ALIAS);
+  } else if (specifier.startsWith('./') || specifier.startsWith('../')) {
+    resolved = resolve(dirname(fromFile), specifier);
+  } else {
+    // External package import — not relevant
+    return null;
+  }
+
+  // Try exact match, then common extensions
+  const extensions = ['', '.ts', '.js', '.svelte', '/index.ts', '/index.js', '/index.svelte'];
+  for (const ext of extensions) {
+    const candidate = resolved + ext;
+    if (allFiles.has(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/** Build the forward dependency graph: file → set of files it imports. */
+function buildDependencyGraph(files: string[]): Map<string, Set<string>> {
+  const fileSet = new Set(files);
+  const graph = new Map<string, Set<string>>();
+
+  for (const file of files) {
+    const deps = new Set<string>();
+    graph.set(file, deps);
+
+    try {
+      const source = readFileSync(file, 'utf8');
+      for (const specifier of extractImports(source)) {
+        const resolved = resolveImport(specifier, file, fileSet);
+        if (resolved) {
+          deps.add(resolved);
+        }
+      }
+    } catch {
+      // Skip files that can't be read
+    }
+  }
+
+  return graph;
+}
+
+/** Invert the dependency graph: file → set of files that import it. */
+function buildReverseDependencyGraph(forwardGraph: Map<string, Set<string>>): Map<string, Set<string>> {
+  const reverse = new Map<string, Set<string>>();
+
+  for (const [file, deps] of forwardGraph) {
+    for (const dep of deps) {
+      let importers = reverse.get(dep);
+      if (!importers) {
+        importers = new Set();
+        reverse.set(dep, importers);
+      }
+      importers.add(file);
+    }
+  }
+
+  return reverse;
+}
+
+/** BFS from changed files upward through reverse deps to find +page.svelte files. */
+function findAffectedPages(changedFiles: string[], reverseGraph: Map<string, Set<string>>): Set<string> {
+  const visited = new Set<string>();
+  const pages = new Set<string>();
+  const queue = [...changedFiles];
+
+  while (queue.length > 0) {
+    const file = queue.shift()!;
+    if (visited.has(file)) {
+      continue;
+    }
+    visited.add(file);
+
+    if (file.endsWith('+page.svelte') || file.endsWith('+layout.svelte')) {
+      pages.add(file);
+      // If it's a layout, keep tracing upward because the layout itself
+      // isn't a page — but the pages under it are affected.
+      // If it's a +page.svelte, we still want to continue in case
+      // this page is imported by others.
+    }
+
+    const importers = reverseGraph.get(file);
+    if (importers) {
+      for (const importer of importers) {
+        if (!visited.has(importer)) {
+          queue.push(importer);
+        }
+      }
+    }
+  }
+
+  // For +layout.svelte hits, also find all +page.svelte under the same directory tree
+  const layoutDirs: string[] = [];
+  for (const page of pages) {
+    if (page.endsWith('+layout.svelte')) {
+      layoutDirs.push(dirname(page));
+      pages.delete(page);
+    }
+  }
+
+  if (layoutDirs.length > 0) {
+    for (const file of reverseGraph.keys()) {
+      if (file.endsWith('+page.svelte')) {
+        for (const layoutDir of layoutDirs) {
+          if (file.startsWith(layoutDir)) {
+            pages.add(file);
+          }
+        }
+      }
+    }
+    // Also check the forward graph keys for page files under layout dirs
+    for (const layoutDir of layoutDirs) {
+      const allFiles = collectFiles(layoutDir);
+      for (const f of allFiles) {
+        if (f.endsWith('+page.svelte')) {
+          pages.add(f);
+        }
+      }
+    }
+  }
+
+  return pages;
+}
+
+/** Convert a +page.svelte file path to its URL route. */
+export function pageFileToRoute(pageFile: string): string {
+  const routesDir = resolve(WEB_SRC, 'routes');
+  let rel = relative(routesDir, dirname(pageFile));
+
+  // Remove SvelteKit group markers: (user), (list), etc.
+  rel = rel.replaceAll(/\([^)]+\)\/?/g, '');
+
+  // Remove parameter segments: [albumId=id], [[photos=photos]], [[assetId=id]]
+  rel = rel.replaceAll(/\[\[?[^\]]+\]\]?\/?/g, '');
+
+  // Clean up trailing slashes and normalize
+  rel = rel.replaceAll(/\/+/g, '/').replace(/\/$/, '');
+
+  return '/' + rel;
+}
+
+export interface AnalysisResult {
+  affectedPages: string[];
+  affectedRoutes: string[];
+}
+
+/** Main entry: analyze which routes are affected by the given changed files. */
+export function analyzeAffectedRoutes(changedFiles: string[]): AnalysisResult {
+  // Resolve changed files to absolute paths relative to web/src
+  const webRoot = resolve(WEB_SRC, '..');
+  const resolvedChanged = changedFiles
+    .filter((f) => f.startsWith('web/'))
+    .map((f) => resolve(webRoot, '..', f))
+    .filter((f) => statSync(f, { throwIfNoEntry: false })?.isFile());
+
+  if (resolvedChanged.length === 0) {
+    return { affectedPages: [], affectedRoutes: [] };
+  }
+
+  const allFiles = collectFiles(WEB_SRC);
+  const forwardGraph = buildDependencyGraph(allFiles);
+  const reverseGraph = buildReverseDependencyGraph(forwardGraph);
+
+  const pages = findAffectedPages(resolvedChanged, reverseGraph);
+
+  const affectedPages = [...pages].sort();
+  const affectedRoutes = [...new Set(affectedPages.map(pageFileToRoute))].sort();
+
+  return { affectedPages, affectedRoutes };
+}
+
+// CLI usage: node --import tsx analyze-deps.ts file1 file2 ...
+if (process.argv[1]?.endsWith('analyze-deps.ts') || process.argv[1]?.endsWith('analyze-deps.js')) {
+  const files = process.argv.slice(2);
+  if (files.length === 0) {
+    console.log('Usage: analyze-deps.ts <changed-file1> <changed-file2> ...');
+    console.log('Files should be relative to the repo root (e.g. web/src/lib/components/Button.svelte)');
+    process.exit(1);
+  }
+
+  const result = analyzeAffectedRoutes(files);
+  console.log('Affected pages:');
+  for (const page of result.affectedPages) {
+    console.log(`  ${page}`);
+  }
+  console.log('\nAffected routes:');
+  for (const route of result.affectedRoutes) {
+    console.log(`  ${route}`);
+  }
+}

e2e/src/screenshots/compare.ts

@@ -0,0 +1,257 @@
+/**
+ * Pixel-level comparison of base vs PR screenshots.
+ *
+ * Uses pixelmatch to generate diff images and calculate change percentages.
+ *
+ * Usage:
+ *   npx tsx e2e/src/screenshots/compare.ts <base-dir> <pr-dir> <output-dir>
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { PNG } from 'pngjs';
+
+// pixelmatch is a lightweight dependency — use a simple inline implementation
+// based on the approach from the pixelmatch library to avoid adding a new dependency.
+// The e2e package already has pngjs.
+
+function pixelMatch(
+  img1Data: Uint8Array,
+  img2Data: Uint8Array,
+  diffData: Uint8Array,
+  width: number,
+  height: number,
+): number {
+  let diffCount = 0;
+
+  for (let i = 0; i < img1Data.length; i += 4) {
+    const r1 = img1Data[i];
+    const g1 = img1Data[i + 1];
+    const b1 = img1Data[i + 2];
+
+    const r2 = img2Data[i];
+    const g2 = img2Data[i + 1];
+    const b2 = img2Data[i + 2];
+
+    const dr = Math.abs(r1 - r2);
+    const dg = Math.abs(g1 - g2);
+    const db = Math.abs(b1 - b2);
+
+    // Threshold: if any channel differs by more than 25, mark as different
+    const isDiff = dr > 25 || dg > 25 || db > 25;
+
+    if (isDiff) {
+      // Red highlight for diff pixels
+      diffData[i] = 255;
+      diffData[i + 1] = 0;
+      diffData[i + 2] = 0;
+      diffData[i + 3] = 255;
+      diffCount++;
+    } else {
+      // Dimmed original for unchanged pixels
+      const gray = Math.round(0.299 * r1 + 0.587 * g1 + 0.114 * b1);
+      diffData[i] = gray;
+      diffData[i + 1] = gray;
+      diffData[i + 2] = gray;
+      diffData[i + 3] = 128;
+    }
+  }
+
+  return diffCount;
+}
+
+export interface ComparisonResult {
+  name: string;
+  baseExists: boolean;
+  prExists: boolean;
+  diffPixels: number;
+  totalPixels: number;
+  changePercent: number;
+  diffImagePath: string | null;
+  baseImagePath: string | null;
+  prImagePath: string | null;
+}
+
+export function compareScreenshots(baseDir: string, prDir: string, outputDir: string): ComparisonResult[] {
+  mkdirSync(outputDir, { recursive: true });
+
+  // Collect all screenshot names from both directories
+  const baseFiles = existsSync(baseDir)
+    ? new Set(readdirSync(baseDir).filter((f) => f.endsWith('.png')))
+    : new Set<string>();
+  const prFiles = existsSync(prDir)
+    ? new Set(readdirSync(prDir).filter((f) => f.endsWith('.png')))
+    : new Set<string>();
+
+  const allNames = new Set([...baseFiles, ...prFiles]);
+  const results: ComparisonResult[] = [];
+
+  for (const fileName of [...allNames].sort()) {
+    const name = basename(fileName, '.png');
+    const basePath = join(baseDir, fileName);
+    const prPath = join(prDir, fileName);
+    const baseExists = baseFiles.has(fileName);
+    const prExists = prFiles.has(fileName);
+
+    if (!baseExists || !prExists) {
+      // New or removed page
+      results.push({
+        name,
+        baseExists,
+        prExists,
+        diffPixels: -1,
+        totalPixels: -1,
+        changePercent: 100,
+        diffImagePath: null,
+        baseImagePath: baseExists ? basePath : null,
+        prImagePath: prExists ? prPath : null,
+      });
+      continue;
+    }
+
+    // Load both PNGs
+    const basePng = PNG.sync.read(readFileSync(basePath));
+    const prPng = PNG.sync.read(readFileSync(prPath));
+
+    // Handle size mismatches by comparing the overlapping region
+    const width = Math.max(basePng.width, prPng.width);
+    const height = Math.max(basePng.height, prPng.height);
+
+    // Resize images to the same dimensions (pad with transparent)
+    const normalizedBase = normalizeImage(basePng, width, height);
+    const normalizedPr = normalizeImage(prPng, width, height);
+
+    const diffPng = new PNG({ width, height });
+    const totalPixels = width * height;
+    const diffPixels = pixelMatch(
+      normalizedBase,
+      normalizedPr,
+      diffPng.data as unknown as Uint8Array,
+      width,
+      height,
+    );
+
+    const diffImagePath = join(outputDir, `${name}-diff.png`);
+    writeFileSync(diffImagePath, PNG.sync.write(diffPng));
+
+    results.push({
+      name,
+      baseExists,
+      prExists,
+      diffPixels,
+      totalPixels,
+      changePercent: totalPixels > 0 ? (diffPixels / totalPixels) * 100 : 0,
+      diffImagePath,
+      baseImagePath: basePath,
+      prImagePath: prPath,
+    });
+  }
+
+  return results;
+}
+
+function normalizeImage(png: PNG, targetWidth: number, targetHeight: number): Uint8Array {
+  if (png.width === targetWidth && png.height === targetHeight) {
+    return png.data as unknown as Uint8Array;
+  }
+
+  const data = new Uint8Array(targetWidth * targetHeight * 4);
+  for (let y = 0; y < targetHeight; y++) {
+    for (let x = 0; x < targetWidth; x++) {
+      const targetIdx = (y * targetWidth + x) * 4;
+      if (x < png.width && y < png.height) {
+        const sourceIdx = (y * png.width + x) * 4;
+        data[targetIdx] = png.data[sourceIdx];
+        data[targetIdx + 1] = png.data[sourceIdx + 1];
+        data[targetIdx + 2] = png.data[sourceIdx + 2];
+        data[targetIdx + 3] = png.data[sourceIdx + 3];
+      } else {
+        // Transparent padding
+        data[targetIdx + 3] = 0;
+      }
+    }
+  }
+  return data;
+}
+
+/** Generate a markdown report for PR comment. */
+export function generateMarkdownReport(results: ComparisonResult[], artifactUrl: string): string {
+  const changed = results.filter((r) => r.changePercent > 0.1);
+  const unchanged = results.filter((r) => r.changePercent <= 0.1);
+
+  if (changed.length === 0) {
+    return '## Visual Review\n\nNo visual changes detected in the affected pages.';
+  }
+
+  let md = '## Visual Review\n\n';
+  md += `Found **${changed.length}** page(s) with visual changes`;
+  if (unchanged.length > 0) {
+    md += ` (${unchanged.length} unchanged)`;
+  }
+  md += '.\n\n';
+
+  for (const result of changed) {
+    md += `### ${result.name}\n\n`;
+
+    if (!result.baseExists) {
+      md += '**New page** (no base screenshot to compare)\n\n';
+      md += `| PR |\n|---|\n| ![${result.name} PR](${artifactUrl}/${result.name}.png) |\n\n`;
+      continue;
+    }
+
+    if (!result.prExists) {
+      md += '**Removed page** (no PR screenshot)\n\n';
+      continue;
+    }
+
+    md += `Change: **${result.changePercent.toFixed(1)}%** (${result.diffPixels.toLocaleString()} pixels)\n\n`;
+    md += '| Base | PR | Diff |\n';
+    md += '|------|-------|------|\n';
+    md += `| ![base](${artifactUrl}/base/${result.name}.png) `;
+    md += `| ![pr](${artifactUrl}/pr/${result.name}.png) `;
+    md += `| ![diff](${artifactUrl}/diff/${result.name}-diff.png) |\n\n`;
+  }
+
+  if (unchanged.length > 0) {
+    md += '<details>\n<summary>Unchanged pages</summary>\n\n';
+    for (const result of unchanged) {
+      md += `- ${result.name}\n`;
+    }
+    md += '\n</details>\n';
+  }
+
+  return md;
+}
+
+// CLI usage
+if (process.argv[1]?.endsWith('compare.ts') || process.argv[1]?.endsWith('compare.js')) {
+  const [baseDir, prDir, outputDir, imageBaseUrl] = process.argv.slice(2);
+
+  if (!baseDir || !prDir || !outputDir) {
+    console.log('Usage: compare.ts <base-dir> <pr-dir> <output-dir> [image-base-url]');
+    process.exit(1);
+  }
+
+  const results = compareScreenshots(
+    resolve(baseDir),
+    resolve(prDir),
+    resolve(outputDir),
+  );
+
+  console.log('\nComparison Results:');
+  console.log('==================');
+  for (const r of results) {
+    const status = r.changePercent > 0.1 ? 'CHANGED' : 'unchanged';
+    console.log(`  ${r.name}: ${status} (${r.changePercent.toFixed(1)}%)`);
+  }
+
+  const report = generateMarkdownReport(results, imageBaseUrl || '.');
+  const reportPath = join(resolve(outputDir), 'report.md');
+  writeFileSync(reportPath, report);
+  console.log(`\nReport written to: ${reportPath}`);
+
+  // Also output results as JSON for CI
+  const jsonPath = join(resolve(outputDir), 'results.json');
+  writeFileSync(jsonPath, JSON.stringify(results, null, 2));
+  console.log(`Results JSON written to: ${jsonPath}`);
+}

e2e/src/screenshots/page-map.ts

@@ -0,0 +1,187 @@
+/**
+ * Maps URL routes to screenshot scenario keys.
+ *
+ * Routes discovered by the dependency analyzer are matched against this map
+ * to determine which screenshot scenarios to run. Routes not in this map
+ * are skipped (they don't have a scenario defined yet).
+ */
+
+export interface ScenarioDefinition {
+  /** The URL path to navigate to */
+  url: string;
+  /** Human-readable name for the screenshot file */
+  name: string;
+  /** Which mock networks this scenario needs */
+  mocks: ('base' | 'timeline' | 'memory')[];
+  /** Optional: selector to wait for before screenshotting */
+  waitForSelector?: string;
+  /** Optional: time to wait after page load (ms) for animations to settle */
+  settleTime?: number;
+}
+
+/**
+ * Map from route paths (as output by analyze-deps) to scenario definitions.
+ * A single route might map to multiple scenarios (e.g., different states).
+ */
+export const PAGE_SCENARIOS: Record<string, ScenarioDefinition[]> = {
+  '/photos': [
+    {
+      url: '/photos',
+      name: 'photos-timeline',
+      mocks: ['base', 'timeline'],
+      waitForSelector: '[data-thumbnail-focus-container]',
+      settleTime: 500,
+    },
+  ],
+  '/albums': [
+    {
+      url: '/albums',
+      name: 'albums-list',
+      mocks: ['base'],
+      settleTime: 300,
+    },
+  ],
+  '/explore': [
+    {
+      url: '/explore',
+      name: 'explore',
+      mocks: ['base'],
+      settleTime: 300,
+    },
+  ],
+  '/favorites': [
+    {
+      url: '/favorites',
+      name: 'favorites',
+      mocks: ['base', 'timeline'],
+      waitForSelector: '#asset-grid',
+      settleTime: 300,
+    },
+  ],
+  '/archive': [
+    {
+      url: '/archive',
+      name: 'archive',
+      mocks: ['base', 'timeline'],
+      waitForSelector: '#asset-grid',
+      settleTime: 300,
+    },
+  ],
+  '/trash': [
+    {
+      url: '/trash',
+      name: 'trash',
+      mocks: ['base', 'timeline'],
+      waitForSelector: '#asset-grid',
+      settleTime: 300,
+    },
+  ],
+  '/people': [
+    {
+      url: '/people',
+      name: 'people',
+      mocks: ['base'],
+      settleTime: 300,
+    },
+  ],
+  '/sharing': [
+    {
+      url: '/sharing',
+      name: 'sharing',
+      mocks: ['base'],
+      settleTime: 300,
+    },
+  ],
+  '/search': [
+    {
+      url: '/search',
+      name: 'search',
+      mocks: ['base'],
+      settleTime: 300,
+    },
+  ],
+  '/memory': [
+    {
+      url: '/memory',
+      name: 'memory',
+      mocks: ['base', 'memory'],
+      settleTime: 500,
+    },
+  ],
+  '/user-settings': [
+    {
+      url: '/user-settings',
+      name: 'user-settings',
+      mocks: ['base'],
+      settleTime: 300,
+    },
+  ],
+  '/map': [
+    {
+      url: '/map',
+      name: 'map',
+      mocks: ['base'],
+      settleTime: 500,
+    },
+  ],
+  '/admin': [
+    {
+      url: '/admin',
+      name: 'admin-dashboard',
+      mocks: ['base'],
+      settleTime: 300,
+    },
+  ],
+  '/admin/system-settings': [
+    {
+      url: '/admin/system-settings',
+      name: 'admin-system-settings',
+      mocks: ['base'],
+      settleTime: 300,
+    },
+  ],
+  '/admin/users': [
+    {
+      url: '/admin/users',
+      name: 'admin-users',
+      mocks: ['base'],
+      settleTime: 300,
+    },
+  ],
+  '/auth/login': [
+    {
+      url: '/auth/login',
+      name: 'login',
+      mocks: [],
+      settleTime: 300,
+    },
+  ],
+  '/': [
+    {
+      url: '/',
+      name: 'landing',
+      mocks: [],
+      settleTime: 300,
+    },
+  ],
+};
+
+/** Given a list of routes from the analyzer, return the matching scenarios. */
+export function getScenariosForRoutes(routes: string[]): ScenarioDefinition[] {
+  const scenarios: ScenarioDefinition[] = [];
+  const seen = new Set<string>();
+
+  for (const route of routes) {
+    const defs = PAGE_SCENARIOS[route];
+    if (defs) {
+      for (const def of defs) {
+        if (!seen.has(def.name)) {
+          seen.add(def.name);
+          scenarios.push(def);
+        }
+      }
+    }
+  }
+
+  return scenarios;
+}

e2e/src/screenshots/run-scenarios.ts

@@ -0,0 +1,129 @@
+/**
+ * Playwright script to capture screenshots for visual diff scenarios.
+ *
+ * Usage:
+ *   npx playwright test --config e2e/playwright.screenshot.config.ts
+ *
+ * Environment variables:
+ *   SCREENSHOT_SCENARIOS - JSON array of scenario names to run (from page-map.ts)
+ *                          If not set, runs all scenarios.
+ *   SCREENSHOT_OUTPUT_DIR - Directory to save screenshots to. Defaults to e2e/screenshots-output.
+ */
+
+import { faker } from '@faker-js/faker';
+import type { MemoryResponseDto } from '@immich/sdk';
+import { test } from '@playwright/test';
+import { mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { generateMemoriesFromTimeline } from 'src/ui/generators/memory';
+import {
+  createDefaultTimelineConfig,
+  generateTimelineData,
+  type TimelineAssetConfig,
+  type TimelineData,
+} from 'src/ui/generators/timeline';
+import { setupBaseMockApiRoutes } from 'src/ui/mock-network/base-network';
+import { setupMemoryMockApiRoutes } from 'src/ui/mock-network/memory-network';
+import { setupTimelineMockApiRoutes, TimelineTestContext } from 'src/ui/mock-network/timeline-network';
+import { PAGE_SCENARIOS, type ScenarioDefinition } from './page-map';
+
+const OUTPUT_DIR = process.env.SCREENSHOT_OUTPUT_DIR || resolve(import.meta.dirname, '../../../screenshots-output');
+const SCENARIO_FILTER: string[] | null = process.env.SCREENSHOT_SCENARIOS
+  ? JSON.parse(process.env.SCREENSHOT_SCENARIOS)
+  : null;
+
+// Collect scenarios to run
+const allScenarios: ScenarioDefinition[] = [];
+for (const defs of Object.values(PAGE_SCENARIOS)) {
+  for (const def of defs) {
+    if (!SCENARIO_FILTER || SCENARIO_FILTER.includes(def.name)) {
+      allScenarios.push(def);
+    }
+  }
+}
+
+// Use a fixed seed so screenshots are deterministic across runs
+faker.seed(42);
+
+let adminUserId: string;
+let timelineData: TimelineData;
+let timelineAssets: TimelineAssetConfig[];
+let memories: MemoryResponseDto[];
+
+test.beforeAll(async () => {
+  adminUserId = faker.string.uuid();
+  timelineData = generateTimelineData({ ...createDefaultTimelineConfig(), ownerId: adminUserId });
+
+  timelineAssets = [];
+  for (const timeBucket of timelineData.buckets.values()) {
+    timelineAssets.push(...timeBucket);
+  }
+
+  memories = generateMemoriesFromTimeline(
+    timelineAssets,
+    adminUserId,
+    [
+      { year: 2024, assetCount: 3 },
+      { year: 2023, assetCount: 2 },
+    ],
+    42,
+  );
+
+  mkdirSync(OUTPUT_DIR, { recursive: true });
+});
+
+for (const scenario of allScenarios) {
+  test(`Screenshot: ${scenario.name}`, async ({ context, page }) => {
+    // Set up mocks based on scenario requirements
+    if (scenario.mocks.includes('base')) {
+      await setupBaseMockApiRoutes(context, adminUserId);
+    }
+
+    if (scenario.mocks.includes('timeline')) {
+      const testContext = new TimelineTestContext();
+      testContext.adminId = adminUserId;
+      await setupTimelineMockApiRoutes(context, timelineData, {
+        albumAdditions: [],
+        assetDeletions: [],
+        assetArchivals: [],
+        assetFavorites: [],
+      }, testContext);
+    }
+
+    if (scenario.mocks.includes('memory')) {
+      await setupMemoryMockApiRoutes(context, memories, {
+        memoryDeletions: [],
+        assetRemovals: new Map(),
+      });
+    }
+
+    // Navigate to the page
+    await page.goto(scenario.url, { waitUntil: 'networkidle' });
+
+    // Wait for specific selector if specified
+    if (scenario.waitForSelector) {
+      try {
+        await page.waitForSelector(scenario.waitForSelector, { timeout: 15_000 });
+      } catch {
+        console.warn(`Selector ${scenario.waitForSelector} not found for ${scenario.name}, continuing...`);
+      }
+    }
+
+    // Wait for loading spinners to disappear
+    await page
+      .waitForFunction(
+        () => document.querySelectorAll('[data-testid="loading-spinner"]').length === 0,
+        { timeout: 10_000 },
+      )
+      .catch(() => {});
+
+    // Wait for animations/transitions to settle
+    await page.waitForTimeout(scenario.settleTime ?? 500);
+
+    // Take the screenshot
+    await page.screenshot({
+      path: resolve(OUTPUT_DIR, `${scenario.name}.png`),
+      fullPage: false,
+    });
+  });
+}

e2e/src/specs/server/api/asset.e2e-spec.ts

@@ -253,7 +253,8 @@ describe('/asset', () => {
 
         expect(status).toBe(200);
         expect(body.id).toEqual(facesAsset.id);
-        expect(body.people).toMatchObject(expectedFaces);
+        const sortedPeople = body.people.toSorted((a: any, b: any) => a.name.localeCompare(b.name));
+        expect(sortedPeople).toMatchObject(expectedFaces);
       });
     });
 
@@ -473,6 +474,7 @@ describe('/asset', () => {
         id: user1Assets[0].id,
         exifInfo: expect.objectContaining({
           dateTimeOriginal: '2023-11-20T01:11:00+00:00',
+          timeZone: 'UTC-7',
         }),
       });
       expect(status).toEqual(200);

e2e/src/specs/server/api/shared-link.e2e-spec.ts

@@ -239,7 +239,7 @@ describe('/shared-links', () => {
       const { status, body } = await request(app).get('/shared-links/me').query({ key: linkWithPassword.key });
 
       expect(status).toBe(401);
-      expect(body).toEqual(errorDto.invalidSharePassword);
+      expect(body).toEqual(errorDto.passwordRequired);
     });
 
     it('should get data for correct password protected link', async () => {