feat(docs): reorganize

README.md

@@ -53,13 +53,13 @@
 ## Links
 
 - [Documentation](https://docs.immich.app/)
-- [About](https://docs.immich.app/overview/introduction)
-- [Installation](https://docs.immich.app/install/requirements)
+- [About](https://docs.immich.app/introduction/getting-started)
+- [Installation](https://docs.immich.app/reference/requirements)
 - [Roadmap](https://immich.app/roadmap)
 - [Demo](#demo)
 - [Features](#features)
 - [Translations](https://docs.immich.app/developer/translations)
-- [Contributing](https://docs.immich.app/overview/support-the-project)
+- [Contributing](https://docs.immich.app/support-the-project)
 
 ## Demo
 

docker/docker-compose.rootless.yml

@@ -41,7 +41,7 @@ services:
     # 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
+    # extends: # uncomment this section for hardware acceleration - see https://docs.immich.app/administration/set-up-hardware-accelerated-machine-learning
     #   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'

docker/docker-compose.yml

@@ -36,7 +36,7 @@ services:
     # 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
+    # extends: # uncomment this section for hardware acceleration - see https://docs.immich.app/administration/set-up-hardware-accelerated-machine-learning
     #   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
     volumes:

docker/example.env

@@ -1,4 +1,4 @@
-# You can find documentation for all the supported env variables at https://docs.immich.app/install/environment-variables
+# You can find documentation for all the supported env variables at https://docs.immich.app/reference/environment-variables
 
 # The location where your uploaded files are stored
 UPLOAD_LOCATION=./library

docker/hwaccel.ml.yml

@@ -4,7 +4,7 @@
 # you can inline the config for a backend by copying its contents
 # into the immich-machine-learning service in the docker-compose.yml file.
 
-# See https://docs.immich.app/features/ml-hardware-acceleration for info on usage.
+# See https://docs.immich.app/administration/set-up-hardware-accelerated-machine-learning for info on usage.
 
 services:
   armnn:

docker/hwaccel.transcoding.yml

@@ -4,7 +4,7 @@
 # you can inline the config for a backend by copying its contents
 # into the immich-microservices service in the docker-compose.yml file.
 
-# See https://docs.immich.app/features/hardware-transcoding for more info on using hardware transcoding.
+# See https://docs.immich.app/administration/set-up-hardware-transcoding for more info on using hardware transcoding.
 
 services:
   cpu: {}

docs/docs/FAQ.mdx

@@ -1,3 +1,7 @@
+---
+sidebar_position: 8
+---
+
 # FAQ
 
 ## Commercial Guidelines
@@ -32,11 +36,11 @@ When in doubt or if you have an edge case scenario, we encourage you to contact
 
 ### How can I reset the admin password?
 
-The admin password can be reset by running the [reset-admin-password](/administration/server-commands.md) command on the immich-server.
+The admin password can be reset by running the [reset-admin-password](/administration/run-a-server-command) command on the immich-server.
 
 ### How can I see a list of all users in Immich?
 
-You can see the list of all users by running [list-users](/administration/server-commands.md) Command on the Immich-server.
+You can see the list of all users by running [list-users](/administration/run-a-server-command) Command on the Immich-server.
 
 ### How can I change my profile picture?
 
@@ -112,20 +116,20 @@ However, Immich will delete original files that have been trashed when the trash
 
 When Storage Template is off (default) Immich saves the file names in a random string (also known as random UUIDs) to prevent duplicate file names.
 To retrieve the original file names, you must enable the Storage Template and then run the STORAGE TEMPLATE MIGRATION job.
-It is recommended to read about [Storage Template](/administration/storage-template) before activation.
+It is recommended to read about [Storage Template](/administration/use-the-storage-template) before activation.
 
 ### Can I add my existing photo library?
 
-Yes, with an [External Library](/features/libraries.md).
+Yes, with an [External Library](/administration/add-an-external-library).
 
-### What happens to existing files after I choose a new [Storage Template](/administration/storage-template.mdx)?
+### What happens to existing files after I choose a new [Storage Template](/administration/use-the-storage-template)?
 
-Template changes will only apply to _new_ assets. To retroactively apply the template to previously uploaded assets, run the Storage Migration Job, available on the [Jobs](/administration/jobs-workers/#jobs) page.
+Template changes will only apply to _new_ assets. To retroactively apply the template to previously uploaded assets, run the Storage Migration Job, available on the [Jobs](/reference/jobs) page.
 
 ### Why are only photos and not videos being uploaded to Immich?
 
 This often happens when using a reverse proxy in front of Immich.
-Make sure to [set your reverse proxy](/administration/reverse-proxy/) to allow large requests.
+Make sure to [set your reverse proxy](/administration/set-up-a-reverse-proxy) to allow large requests.
 Also, check the disk space of your reverse proxy.
 In some cases, proxies cache requests to disk before passing them on, and if disk space runs out, the request fails.
 
@@ -145,7 +149,7 @@ You can _archive_ them. This will hide the asset from the main timeline and fold
 
 ### How can I backup data from Immich?
 
-See [Backup and Restore](/administration/backup-and-restore.md).
+See [Backup and Restore](/administration/back-up-and-restore).
 
 ### Does Immich support reading existing face tag metadata?
 
@@ -231,7 +235,7 @@ volumes:
 
 ### Can I keep my existing album structure while importing assets into Immich?
 
-Yes, by using the [Immich CLI](/features/command-line-interface) along with the `--album` flag.
+Yes, by using the [Immich CLI](/user-guide/upload-media-with-the-cli) along with the `--album` flag.
 
 ### Is there a way to reorder photos within an album?
 
@@ -272,7 +276,7 @@ Immich uses CLIP models. An ML model converts each image to an "embedding", whic
 
 ### How does facial recognition work?
 
-See [How Facial Recognition Works](/features/facial-recognition#how-facial-recognition-works) for details.
+See [How Facial Recognition Works](/concepts/facial-recognition#how-facial-recognition-works) for details.
 
 ### How can I disable machine learning?
 
@@ -294,7 +298,7 @@ No, this is not supported. Only models listed in the [Hugging Face][huggingface]
 
 ### I want to be able to search in other languages besides English. How can I do that?
 
-You can change to a multilingual CLIP model. See [here](/features/searching#clip-models) for instructions.
+You can change to a multilingual CLIP model. See [here](/reference/clip-models) for instructions.
 
 ### Does Immich support Facial Recognition for videos?
 
@@ -305,7 +309,7 @@ Scanning the entire video for faces may be implemented in the future.
 
 No.
 :::tip
-You can use [Smart Search](/features/searching.md) for this to some extent. For example, if you have a Golden Retriever and a Chihuahua, type these words in the smart search and watch the results.
+You can use [Smart Search](/user-guide/search-your-library) for this to some extent. For example, if you have a Golden Retriever and a Chihuahua, type these words in the smart search and watch the results.
 :::
 
 ### I'm getting a lot of "faces" that aren't faces, what can I do?
@@ -335,7 +339,7 @@ ls clip/ facial-recognition/
 
 ### Why is Immich slow on low-memory systems like the Raspberry Pi?
 
-Immich optionally uses transcoding and machine learning for several features. However, it can be too heavy to run on a Raspberry Pi. You can [mitigate](/FAQ#can-i-lower-cpu-and-ram-usage) this or host Immich's machine-learning container on a [more powerful system](/guides/remote-machine-learning), or [disable](/FAQ#how-can-i-disable-machine-learning) machine learning entirely.
+Immich optionally uses transcoding and machine learning for several features. However, it can be too heavy to run on a Raspberry Pi. You can [mitigate](/FAQ#can-i-lower-cpu-and-ram-usage) this or host Immich's machine-learning container on a [more powerful system](/administration/run-machine-learning-remotely), or [disable](/FAQ#how-can-i-disable-machine-learning) machine learning entirely.
 
 ### Can I lower CPU and RAM usage?
 
@@ -389,7 +393,7 @@ Do not exaggerate with the job concurrency because you're probably thoroughly ov
 
 ### My server shows Server Status Offline | Version Unknown. What can I do?
 
-You need to [enable WebSockets](/administration/reverse-proxy/) on your reverse proxy.
+You need to [enable WebSockets](/administration/set-up-a-reverse-proxy) on your reverse proxy.
 
 ---
 
@@ -397,7 +401,7 @@ You need to [enable WebSockets](/administration/reverse-proxy/) on your reverse
 
 ### How can I see Immich logs?
 
-Immich components are typically deployed using docker. To see logs for deployed docker containers, you can use the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/), specifically the `docker logs` command. For examples, see [Docker Help](/guides/docker-help.md).
+Immich components are typically deployed using docker. To see logs for deployed docker containers, you can use the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/), specifically the `docker logs` command. For examples, see [Docker Help](/administration/inspect-containers-and-logs).
 
 ### How can I reduce the log verbosity of Redis?
 
@@ -442,7 +446,7 @@ cap_drop:
 Data for Immich comes in two forms:
 
 1. **Metadata** stored in a Postgres database, stored in the `DB_DATA_LOCATION` folder (previously `pg_data` Docker volume).
-2. **Files** (originals, thumbs, profile, etc.), stored in the `UPLOAD_LOCATION` folder, more [info](/administration/backup-and-restore#asset-types-and-storage-locations).
+2. **Files** (originals, thumbs, profile, etc.), stored in the `UPLOAD_LOCATION` folder, more [info](/reference/storage-locations).
 
 :::warning
 This will destroy your database and reset your instance, meaning that you start from scratch.
@@ -480,7 +484,7 @@ If it mentions SIGILL (note the lack of a K) or error code 132, it most likely m
 ### Why am I getting database ownership errors?
 
 If you get database errors such as `FATAL:  data directory "/var/lib/postgresql/data" has wrong ownership` upon database startup, this is likely due to an issue with your filesystem.
-NTFS and ex/FAT/32 filesystems are not supported. See [here](/install/requirements#special-requirements-for-windows-users) for more details.
+NTFS and ex/FAT/32 filesystems are not supported. See [here](/reference/requirements#special-requirements-for-windows-users) for more details.
 
 ### How can I verify the integrity of my database?
 

docs/docs/administration/add-an-external-library.md

@@ -0,0 +1,126 @@
+# Add an external library
+
+This guide walks you through adding an [external library](/concepts/external-libraries) so Immich can show photos and videos that stay where they already are on disk. It assumes you are running Immich in Docker and that the files you want to access are stored on the same machine.
+
+We'll use a concrete example throughout. Say you want to add these folders:
+
+- `/home/user/old-pics`: a folder containing childhood photos.
+- `/mnt/nas/christmas-trip`: photos from a christmas trip. The subfolder `/mnt/nas/christmas-trip/Raw` contains the raw files directly from the DSLR. We don't want to import the raw files to Immich.
+- `/mnt/media/videos`: videos from the same christmas trip.
+
+First, plan how to organize the libraries. The christmas trip photos should belong to their own library since we want to exclude the raw files. The videos and old photos can be in the same library since we want to import all files. We could also add all three folders to the same library if there were no files matching the Raw exclusion pattern in the other folders.
+
+## Step 1 - Mount the directories into the containers
+
+The `immich-server` container needs access to the gallery. Edit `docker-compose.yml` to add one or more mount points in the `immich-server:` section under `volumes:`:
+
+```diff title="docker-compose.yml"
+  immich-server:
+    volumes:
+      - ${UPLOAD_LOCATION}:/data
++     - /mnt/nas/christmas-trip:/mnt/media/christmas-trip:ro
++     - /home/user/old-pics:/mnt/media/old-pics:ro
++     - /mnt/media/videos:/mnt/media/videos:ro
++     - /mnt/media/videos2:/mnt/media/videos2 # WARNING: Immich will be able to delete the files in this folder, as it does not end with :ro
++     - "C:/Users/user_name/Desktop/my media:/mnt/media/my-media:ro" # import path in Windows system.
+```
+
+:::tip
+The `ro` flag at the end only gives read-only access to the volumes.
+This will disallow the images from being deleted in the web UI, or adding metadata to the library ([XMP sidecars](/reference/xmp-sidecars)).
+:::
+
+Restart Immich by running `docker compose up -d` to register the changes, and make sure you can see the mounted path inside the container.
+
+## Step 2 - Create the library
+
+:::info
+External library management requires administrator access and the steps below assume you are using an admin account.
+:::
+
+In the Immich web UI:
+
+- Click the **Administration** link in the upper right corner.
+  <img src={require('./img/administration-link.webp').default} width="50%" title="Administration link" />
+
+- Select the **External Libraries** tab and click the **Create Library** button.
+  <img src={require('./img/create-external-library.webp').default} width="80%" title="Create Library button" />
+
+- In the dialog, select which user should own the new library. This **can not** be changed later.
+  <img src={require('./img/library-owner.webp').default} width="50%" title="Library owner dialog" />
+
+- You are now on the library management page.
+  <img src={require('./img/library-management-page.webp').default} width="80%" title="Library management page" />
+
+- Click `Add` in the `Folders` section, enter `/mnt/media/christmas-trip` as the path, and click Add.
+  <img src={require('./img/edit-import-path.webp').default} width="50%" title="Add an import path" />
+
+- Click `Edit` Library and rename it to "Christmas Trip".
+
+:::note
+Use the `/mnt/media/christmas-trip` path and not the `/mnt/nas/christmas-trip` path — all paths have to be what the Docker containers see.
+:::
+
+## Step 3 - Exclude the raw files
+
+Next, add an exclusion pattern to filter out the raw files:
+
+- Click on `Add` in the `Exclusion Patterns` section.
+- Enter `**/Raw/**` and click Add.
+- Click the three-dots menu and select **Scan New Library Files**.
+  <img src={require('./img/scan-new-library-files.webp').default} width="50%" title="Scan New Library Files menu option" />
+
+See [Exclusion patterns](/reference/exclusion-patterns) for the full glob syntax.
+
+The christmas trip library will now be scanned in the background. In the meantime, let's add the videos and old photos to another library.
+
+## Step 4 - Create a second library
+
+- Go back to `Administration -> External Libraries`.
+- Click on `Create Library`.
+- Select which user owns the library.
+- On the library management page, click `Add` in the `Folders` section, enter `/mnt/media/old-pics`, then click Add.
+- Click `Add` in the `Folders` section again, enter `/mnt/media/videos`, then click Add.
+- Click on `Scan`.
+- Click on `Edit` Library and rename it to "Old videos and photos".
+
+Within seconds, the assets from the old-pics and videos folders should show up in the main timeline.
+
+## Step 5 - Confirm the scan is running
+
+- Click **Administration**, then select the **Jobs** tab.
+  <img src={require('./img/jobs-tab.webp').default} width="50%" title="Jobs tab" />
+
+- You should see non-zero Active jobs for Library, Generate Thumbnails, and Extract Metadata.
+
+## Set a custom scan interval
+
+:::note
+Only an admin can do this.
+:::
+
+You can define a custom interval for the external library rescan under Administration -> Settings -> External Library.  
+You can set the scanning interval using the preset or cron format. For more information you can refer to [Crontab Guru](https://crontab.guru/).
+
+<img src={require('./img/library-custom-scan-interval.webp').default} width="75%" title='Set custom scan interval for external library' />
+
+## Browse the library as folders
+
+Folder view provides an additional view besides the timeline that is similar to a file explorer. It allows you to navigate through the folders and files in the library. This feature is handy for a highly curated and customized external library or a nicely configured storage template.
+
+You can enable it under [`Account Settings > Features > Folders`](https://my.immich.app/user-settings?isOpen=feature+folders). See [Folder view](/user-guide/use-folder-view) for details.
+
+<img src={require('./img/folder-view-1.webp').default} width="100%" title='Folder-view' />
+
+## Troubleshooting
+
+Sometimes, an external library will not scan correctly. This can happen if Immich can't access the files. Here are some things to check:
+
+- In the docker-compose file, are the volumes mounted correctly?
+- Are the volumes also mounted to any worker containers?
+- Are the import paths set correctly, and do they match the path set in docker-compose file?
+- Make sure you don't use symlinks in your import libraries, and that you aren't linking across docker mounts.
+- Are the permissions set correctly?
+- Make sure you are using forward slashes (`/`) and not backward slashes.
+
+To validate that Immich can reach your external library, start a shell inside the container. Run `docker exec -it immich_server bash` to a bash shell. If your import path is `/mnt/photos`, check it with `ls /mnt/photos`. If you are using a dedicated microservices container, make sure to add the same mount point and check for availability within the microservices container as well.

docs/docs/administration/back-up-and-restore.md

@@ -1,11 +1,13 @@
-# Backup and Restore
+# Back up and restore
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import { mdiAlertCircle, mdiCheckCircle } from '@mdi/js';
 import Icon from '@mdi/react';
 
-A [3-2-1 backup strategy](https://www.backblaze.com/blog/the-3-2-1-backup-strategy/) is recommended to protect your data. You should keep copies of your uploaded photos/videos as well as the Immich database for a comprehensive backup solution. This page provides an overview on how to backup the database and the location of user-uploaded pictures and videos. A template bash script that can be run as a cron job is provided [here](/guides/template-backup-script.md)
+When it comes to photos and videos, backups are extremely important. To learn what a complete Immich backup consists of, why both the database and the files are required, and how to keep them consistent, see [Backups](/concepts/backups) and the [3-2-1 backup method](/reference/3-2-1-backup-method).
+
+This page covers the mechanics: preparing the database for backup, which files to copy, and how to restore. A template bash script that can be run as a cron job is provided [here](/administration/use-the-backup-script-template).
 
 :::danger
 The instructions on this page show you how to prepare your Immich instance to be backed up, and which files to take a backup of. You still need to take care of using an actual backup tool to make a backup yourself.
@@ -13,8 +15,6 @@ The instructions on this page show you how to prepare your Immich instance to be
 
 ## Database
 
-Immich stores [file paths](https://github.com/immich-app/immich/discussions/3299) and user metadata in the database. It does not scan the library folder, so database backups are essential.
-
 ### Automatic Database Backups
 
 Immich automatically creates database backups for disaster-recovery purposes. These backups are stored in `UPLOAD_LOCATION/backups` and can be managed through the web interface.
@@ -210,7 +210,9 @@ The provided restore process ensures your database is never in a broken state by
 
 ## Filesystem
 
-Immich does not handle filesystem backups for you. You have to arrange these yourself! 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:
+Immich does not handle filesystem backups for you. You have to arrange these yourself!
+
+Back up the entire contents of `UPLOAD_LOCATION`. If you want a smaller backup, the [original content](/concepts/backups#original-versus-generated-content) is the critical part and lives in these folders:
 
 1. `UPLOAD_LOCATION/library`
 2. `UPLOAD_LOCATION/upload`
@@ -218,96 +220,12 @@ Immich does not handle filesystem backups for you. You have to arrange these you
 
 If you choose to back up only those folders, you will need to rerun the transcoding and thumbnail generation jobs for all assets after you restore from a backup.
 
+For what each directory holds, including how the storage template changes the layout, see [Storage locations](/reference/storage-locations).
+
 :::caution
 If you moved some of these folders onto a different storage device, such as `profile/`, make sure to adjust the backup path to match your setup
 :::
 
-### Asset Types and Storage Locations
-
-Some storage locations are impacted by the Storage Template. See below for more details.
-
-<Tabs>
-  <TabItem value="Storage Template Off (Default)." label="Storage Template Off (Default)." default>
-
-:::note
-The `UPLOAD_LOCATION/library` folder is not used by default on new machines running version 1.92.0. It is used only if the system administrator activated the storage template engine,
-for more info read the [release notes](https://github.com/immich-app/immich/releases/tag/v1.92.0#:~:text=the%20partner%E2%80%99s%20assets.-,Hardening%20storage%20template).
-:::
-
-**1. User-Specific Folders:**
-
-- Each user has a unique string representing them.
-- You can find your user ID in Account Account Settings -> Account -> User ID.
-
-**2. Asset Types and Storage Locations:**
-
-- **Source Assets:**
-  - Original assets uploaded through the browser interface & mobile & CLI.
-  - Stored in `UPLOAD_LOCATION/upload/<userID>`.
-- **Avatar Images:**
-  - User profile images.
-  - Stored in `UPLOAD_LOCATION/profile/<userID>`.
-- **Thumbs Images:**
-  - Preview images (small thumbnails and large previews) for each asset and thumbnails for recognized faces.
-  - Stored in `UPLOAD_LOCATION/thumbs/<userID>`.
-- **Encoded Assets:**
-  - Videos that have been re-encoded from the original for wider compatibility. The original is not removed.
-  - Stored in `UPLOAD_LOCATION/encoded-video/<userID>`.
-- **Database Dump Backups:**
-  - Automatic database backups created by Immich for disaster recovery.
-  - Stored in `UPLOAD_LOCATION/backups/`.
-- **Postgres**
-  - The Immich database containing all the information to allow the system to function properly.  
-    **Note:** This folder will only appear to users who have made the changes mentioned in [v1.102.0](https://github.com/immich-app/immich/discussions/8930) (an optional, non-mandatory change) or who started with this version.
-  - Stored in `DB_DATA_LOCATION`.
-
-</TabItem>
-  <TabItem value="Storage Template On" label="Storage Template On">
-
-:::note
-If you choose to activate the storage template engine, it will move all assets to `UPLOAD_LOCATION/library/<userID>`.
-
-When you turn off the storage template engine, it will leave the assets in `UPLOAD_LOCATION/library/<userID>` and will not return them to `UPLOAD_LOCATION/upload`.  
-**New assets** will be saved to `UPLOAD_LOCATION/upload`.
-:::
-
-**1. User-Specific Folders:**
-
-- Each user has a unique string representing them.
-  - The administrator can set a Storage Label for a user, which will be used instead of `<userID>` for the `library/` folder.
-  - The Admin has a default storage label of `admin`.
-- You can find your user ID and Storage Label in Account Account Settings -> Account -> User ID.
-
-**2. Asset Types and Storage Locations:**
-
-- **Source Assets:**
-  - Original assets uploaded through the browser interface, mobile, and CLI.
-  - Stored in `UPLOAD_LOCATION/library/<userID>`.
-- **Avatar Images:**
-  - User profile images.
-  - Stored in `UPLOAD_LOCATION/profile/<userID>`.
-- **Thumbs Images:**
-  - Preview images (blurred, small, large) for each asset and thumbnails for recognized faces.
-  - Stored in `UPLOAD_LOCATION/thumbs/<userID>`.
-- **Encoded Assets:**
-  - Videos that have been re-encoded from the original for wider compatibility. The original is not removed.
-  - Stored in `UPLOAD_LOCATION/encoded-video/<userID>`.
-- **Files in Upload Queue (Mobile):**
-  - Files uploaded through mobile apps.
-  - Temporarily located in `UPLOAD_LOCATION/upload/<userID>`.
-  - Transferred to `UPLOAD_LOCATION/library/<userID>` upon successful upload.
-- **Database Dump Backups:**
-  - Automatic database backups created by Immich for disaster recovery.
-  - Stored in `UPLOAD_LOCATION/backups/`.
-- **Postgres**
-  - The Immich database containing all the information to allow the system to function properly.  
-    **Note:** This folder will only appear to users who have made the changes mentioned in [v1.102.0](https://github.com/immich-app/immich/discussions/8930) (an optional, non-mandatory change) or who started with this version.
-  - Stored in `DB_DATA_LOCATION`.
-
-</TabItem>
-
-</Tabs>
-
 :::danger
 Do not touch the files inside these folders under any circumstances except taking a backup. Changing or removing an asset can cause untracked and missing files.
 You can think of it as App-Which-Must-Not-Be-Named, the only access to viewing, changing and deleting assets is only through the mobile or browser interface.
@@ -315,7 +233,6 @@ You can think of it as App-Which-Must-Not-Be-Named, the only access to viewing,
 
 ## Backup ordering
 
-A backup of Immich should contain both the database and the asset files. When backing these up it's possible for them to get out of sync, potentially resulting in broken assets after you restore.  
-The best way of dealing with this is to stop the immich-server container while you take a backup. If nothing is changing then the backup will always be in sync.
+Stop the `immich-server` container while the backup runs. If nothing is changing, the database and the files cannot drift out of sync.
 
-If stopping the container is not an option, then the recommended order is to back up the database first, and the filesystem second. This way, the worst case scenario is that there are files on the filesystem that the database doesn't know about. If necessary, these can be (re)uploaded manually after a restore. If the backup is done the other way around, with the filesystem first and the database second, it's possible for the restored database to reference files that aren't in the filesystem backup, thus resulting in broken assets.
+If stopping the container is not an option, back up the database **first** and the filesystem **second**. See [consistency between the database and the files](/concepts/backups#consistency-between-the-database-and-the-files) for why the order matters.

docs/docs/administration/change-clip-models.md

@@ -0,0 +1,22 @@
+# Change CLIP models
+
+This guide switches the model that powers contextual (smart) search. To decide _which_ model to switch to, see the [CLIP models reference](/reference/clip-models), which compares every supported model by memory use, speed, and recall per language.
+
+The model is set at `Administration > Settings > Machine Learning Settings > Smart Search`.
+
+## Steps
+
+Once you've chosen a model, follow these steps:
+
+1. Copy the name of the model (e.g. `ViT-B-16-SigLIP__webli`)
+2. Go to the [Smart Search settings][smart-search-settings]
+3. Paste the model name into the Model Name section
+4. Save the settings
+5. Go to the [Job Status page][job-status-page]
+6. Click "All" next to "Smart Search" to begin re-processing your assets with the new model
+7. (Optional) Confirm that the logs for the server and machine learning service don't have relevant errors
+
+In rare instances, changing the model might leave bits of the old model's incompatible data in the database, causing errors when processing Smart Search jobs. If you notice errors like this in the logs, you can change the model back to the previous one and save, then repeat steps 3-7.
+
+[smart-search-settings]: https://my.immich.app/admin/system-settings?isOpen=machine-learning+smart-search
+[job-status-page]: https://my.immich.app/admin/queues

docs/docs/administration/connect-a-database-gui.md

@@ -1,4 +1,4 @@
-# Database GUI
+# Connect a database GUI
 
 A short guide on connecting [pgAdmin](https://www.pgadmin.org/) to Immich.
 

docs/docs/administration/improve-facial-recognition-clusters.md

@@ -1,8 +1,8 @@
-# Better Facial Recognition Clusters
+# Improve facial recognition clusters
 
 ## Purpose
 
-This guide explains how to optimize facial recognition in systems with large image libraries. By following these steps, you'll achieve better clustering of faces, reducing the need for manual merging.
+This guide explains how to optimize [facial recognition](/concepts/facial-recognition) in systems with large image libraries. By following these steps, you'll achieve better clustering of faces, reducing the need for manual merging.
 
 ---
 
@@ -10,7 +10,7 @@ This guide explains how to optimize facial recognition in systems with large ima
 
 - **Best Suited For:** Large image libraries after importing a significant number of images.
 - **Warning:** This method deletes all previously assigned names.
-- **Tip:** **Always take a [backup](/administration/backup-and-restore#database) before proceeding!**
+- **Tip:** **Always take a [backup](/administration/back-up-and-restore#database) before proceeding!**
 
 ---
 

docs/docs/administration/inspect-containers-and-logs.md

@@ -1,4 +1,6 @@
-# Docker Help
+# Inspect containers and logs
+
+Common Docker commands for looking inside a running Immich deployment. If Immich is configured for [JSON logging](/reference/logging#json-format), the output of `docker logs` is one JSON object per line.
 
 ## Containers
 

docs/docs/administration/jobs-workers.md

@@ -1,74 +0,0 @@
-# Jobs and Workers
-
-## Workers
-
-### Architecture
-
-The `immich-server` container contains multiple workers:
-
-- `api`: responds to API requests for data and files for the web and mobile app.
-- `microservices`: handles most other work, such as thumbnail generation and video encoding, in the form of _jobs_. Simply put, a job is a request to process data in the background.
-
-## Split workers
-
-If you prefer to throttle or distribute the workers, you can do this using the [environment variables](/install/environment-variables) to specify which container should pick up which tasks.
-
-For example, for a simple setup with one container for the Web/API and one for all other microservices, you can do the following:
-
-Copy the entire `immich-server` block as a new service and make the following changes to the **copy**:
-
-```diff
-- immich-server:
--   container_name: immich_server
-...
--   ports:
--     - 2283:2283
-+ immich-microservices:
-+   container_name: immich_microservices
-```
-
-Once you have two copies of the immich-server service, make the following changes to each one. This will allow one container to only serve the web UI and API, and the other one to handle all other tasks.
-
-```diff
-services:
-  immich-server:
-    ...
-+   environment:
-+     IMMICH_WORKERS_INCLUDE: 'api'
-
-  immich-microservices:
-    ...
-+   environment:
-+     IMMICH_WORKERS_EXCLUDE: 'api'
-```
-
-## Jobs
-
-When a new asset is uploaded it kicks off a series of jobs, which include metadata extraction, thumbnail generation, machine learning tasks, and storage template migration, if enabled. To view the status of a job navigate to the Administration -> Jobs page.
-
-<img src={require('./img/admin-jobs.webp').default} width="60%" title="Admin jobs" />
-
-Additionally, some jobs (such as memories generation) run on a schedule, which is every night at midnight by default. To change when they run or enable/disable a job navigate to System Settings -> [Nightly Tasks Settings](https://my.immich.app/admin/system-settings?isOpen=nightly-tasks).
-
-<img src={require('./img/admin-nightly-tasks.webp').default} width="80%" title="Admin nightly tasks" />
-
-:::note
-Some jobs ([External Libraries](/features/libraries) scanning, Database Dump) are configured in their own sections in System Settings.
-:::
-
-## Job processing order
-
-The below diagram shows the job run order for newly uploaded files
-
-```mermaid
-graph TD
-    A[Asset Upload] --> B[Metadata Extraction]
-    B --> C[Storage Template Migration]
-    C --> D["Thumbnail Generation (Large, small, blurred and person)"]
-    D --> E[Smart Search]
-    D --> F[Face Detection]
-    D --> G[OCR]
-    D --> H[Video Transcoding]
-    E --> I[Duplicate Detection]
-    F --> J[Facial Recognition]
-```

docs/docs/administration/manage-users.mdx

@@ -1,9 +1,9 @@
 import RegisterAdminUser from '/docs/partials/_register-admin.md';
 import UserCreate from '/docs/partials/_user-create.md';
 
-# User Management
+# Manage users
 
-Immich supports multiple users, each with their own library.
+Immich supports multiple users, each with their own library and [storage directories](/reference/storage-locations).
 
 ## Register the Admin User
 

docs/docs/administration/migrate-to-vectorchord.md

@@ -0,0 +1,182 @@
+# Migrate to VectorChord
+
+VectorChord is the successor to the deprecated pgvecto.rs extension, with better performance, lower memory usage, and higher quality results for smart search and facial recognition. Immich has migrated to it, so instances still on pgvecto.rs need to make this change.
+
+The steps depend on how the database is deployed — pick the matching section below.
+
+:::info
+If you deploy Immich using Docker Compose, see `ghcr.io/immich-app/postgres` in the `docker-compose.yml` file, and have not explicitly set the `DB_VECTOR_EXTENSION` environment variable, your database is already using VectorChord and none of this applies to you.
+:::
+
+:::important
+If you do not deploy Immich using Docker Compose and see a deprecation warning for pgvecto.rs on server startup, refer to the maintainers of your Immich distribution for guidance (if using a turnkey solution) or adapt the instructions for your specific setup.
+:::
+
+Before making any changes, [back up your database](/administration/back-up-and-restore). Every effort has been made to make this migration smooth, but there is always a chance that something goes wrong. See [Backups](/concepts/backups) for what a complete backup includes.
+
+## Docker Compose
+
+Modify your `docker-compose.yml` file as follows.
+
+```diff
+  [...]
+
+  database:
+    container_name: immich_postgres
+-   image: docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0@sha256:739cdd626151ff1f796dc95a6591b55a714f341c737e27f045019ceabf8e8c52
++   image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
+    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
+-   healthcheck:
+-     test: >-
+-       pg_isready --dbname="$${POSTGRES_DB}" --username="$${POSTGRES_USER}" || exit 1;
+-       Chksum="$$(psql --dbname="$${POSTGRES_DB}" --username="$${POSTGRES_USER}" --tuples-only --no-align
+-       --command='SELECT COALESCE(SUM(checksum_failures), 0) FROM pg_stat_database')";
+-       echo "checksum failure count is $$Chksum";
+-       [ "$$Chksum" = '0' ] || exit 1
+-     interval: 5m
+-     start_interval: 30s
+-     start_period: 5m
+-   command: >-
+-     postgres
+-     -c shared_preload_libraries=vectors.so
+-     -c 'search_path="$$user", public, vectors'
+-     -c logging_collector=on
+-     -c max_wal_size=2GB
+-     -c shared_buffers=512MB
+-     -c wal_compression=on
++   shm_size: 128mb
+    restart: always
+
+    [...]
+```
+
+:::important
+If you deviated from the defaults of pg14 or pgvectors0.2.0, you must adjust the pg major version and pgvecto.rs version. If you are still using the default `docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0` image, you can just follow the changes above. For example, if the previous image is `docker.io/tensorchord/pgvecto-rs:pg16-v0.3.0`, the new image should be `ghcr.io/immich-app/postgres:16-vectorchord0.3.0-pgvectors0.3.0` instead of the image specified in the diff.
+:::
+
+After making these changes, you can start Immich as normal. Immich will make some changes to the DB during startup, which can take seconds to minutes to finish, depending on hardware and library size. In particular, it’s normal for the server logs to be seemingly stuck at `Reindexing clip_index` and `Reindexing face_index` for some time if you have over 100k assets in Immich and/or Immich is on a relatively weak server. If you see these logs and there are no errors, just give it time.
+
+:::danger
+After switching to VectorChord, you should not downgrade Immich below 1.133.0.
+:::
+
+Please don’t hesitate to contact us on [GitHub](https://github.com/immich-app/immich/discussions) or [Discord](https://discord.immich.app/) if you encounter migration issues.
+
+## Pre-existing Postgres server
+
+For an instance using a [pre-existing Postgres server](/administration/use-a-pre-existing-postgres-server), the path depends on which extension is installed today.
+
+VectorChord is the successor extension to pgvecto.rs, allowing for higher performance, lower memory usage and higher quality results for smart search and facial recognition.
+
+### From pgvecto.rs
+
+Support for pgvecto.rs has been dropped as of 3.0, hence all users currently using pgvecto.rs should migrate to VectorChord. There are two primary approaches to do so.
+
+The easiest option is to have both extensions installed during the migration:
+
+<details>
+<summary>Migration steps (automatic)</summary>
+1. Ensure you still have pgvecto.rs installed
+2. Install `pgvector` (`>= 0.7, < 0.9`). The easiest way to do this is on Debian/Ubuntu by adding the [PostgreSQL Apt repository][pg-apt] and then running `apt install postgresql-NN-pgvector`, where `NN` is your Postgres version (e.g., `16`)
+3. [Install VectorChord][vchord-install]
+4. Add `shared_preload_libraries= 'vchord.so, vectors.so'` to your `postgresql.conf`, making sure to include _both_ `vchord.so` and `vectors.so`. You may include other libraries here as well if needed
+5. Restart the Postgres database
+6. If Immich does not have superuser permissions, run the SQL command `CREATE EXTENSION vchord CASCADE;` using psql or your choice of database client
+7. Start Immich and wait for the logs `Reindexed face_index` and `Reindexed clip_index` to be output
+8. If Immich does not have superuser permissions, run the SQL command `DROP EXTENSION vectors;`
+9. Drop the old schema by running `DROP SCHEMA vectors;`
+10. Remove the `vectors.so` entry from the `shared_preload_libraries` setting
+11. Restart the Postgres database
+12. Uninstall pgvecto.rs (e.g. `apt-get purge vectors-pg14` on Debian-based environments, replacing `pg14` as appropriate). `pgvector` must remain installed as it provides the data types used by `vchord`
+
+</details>
+
+If it is not possible to have both VectorChord and pgvecto.rs installed at the same time, you can perform the migration with more manual steps:
+
+<details>
+<summary>Migration steps (manual)</summary>
+1. While pgvecto.rs is still installed, run the following SQL command using psql or your choice of database client. Take note of the number outputted by this command as you will need it later
+
+```sql
+SELECT atttypmod as dimsize
+    FROM pg_attribute f
+    JOIN pg_class c ON c.oid = f.attrelid
+    WHERE c.relkind = 'r'::char
+    AND f.attnum > 0
+    AND c.relname = 'smart_search'::text
+    AND f.attname = 'embedding'::text;
+```
+
+2. Remove references to pgvecto.rs using the below SQL commands
+
+```sql
+DROP INDEX IF EXISTS clip_index;
+DROP INDEX IF EXISTS face_index;
+ALTER TABLE smart_search ALTER COLUMN embedding SET DATA TYPE real[];
+ALTER TABLE face_search ALTER COLUMN embedding SET DATA TYPE real[];
+```
+
+3. [Install VectorChord][vchord-install]
+4. Change the columns back to the appropriate vector types, replacing `<number>` with the number from step 1
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vchord CASCADE;
+ALTER TABLE smart_search ALTER COLUMN embedding SET DATA TYPE vector(<number>);
+ALTER TABLE face_search ALTER COLUMN embedding SET DATA TYPE vector(512);
+```
+
+5. Start Immich and let it create new indices using VectorChord
+
+</details>
+
+### From pgvector
+
+<details>
+<summary>Migration steps</summary>
+1. Ensure you have at least `0.7.0` of pgvector installed. If it is below that, please upgrade it and run the SQL command `ALTER EXTENSION vector UPDATE;` using psql or your choice of database client
+2. Follow the Prerequisites to install VectorChord
+3. If Immich does not have superuser permissions, run the SQL command `CREATE EXTENSION vchord CASCADE;`
+4. Remove the `DB_VECTOR_EXTENSION=pgvector` environmental variable as it will make Immich still use pgvector if set
+5. Start Immich and let it create new indices using VectorChord
+
+</details>
+
+Note that VectorChord itself uses pgvector types, so you should not uninstall pgvector after following these steps.
+
+## FAQ
+
+### I have a separate PostgreSQL instance shared with multiple services. How can I switch to VectorChord?
+
+Follow [Pre-existing Postgres server](#pre-existing-postgres-server) below instead of the Docker Compose steps. The path differs depending on whether you are currently using pgvecto.rs or pgvector, and on whether Immich has superuser permissions.
+
+### Why are so many lines removed from the `docker-compose.yml` file? Does this mean the health check is removed?
+
+These lines are now incorporated into the image itself along with some additional tuning.
+
+### What does this change mean for my existing DB backups?
+
+The new DB image includes pgvector and pgvecto.rs in addition to VectorChord, so you can use this image to restore from existing backups that used either of these extensions. However, backups made after switching to VectorChord require an image containing VectorChord to restore successfully.
+
+### Do I still need pgvecto.rs installed after migrating to VectorChord?
+
+pgvecto.rs only needs to be available during the migration, or if you need to restore from a backup that used pgvecto.rs. For a leaner DB and a smaller image, you can optionally switch to an image variant that doesn’t have pgvecto.rs installed after you’ve performed the migration and started Immich: `ghcr.io/immich-app/postgres:14-vectorchord0.4.3`, changing the PostgreSQL version as appropriate.
+
+### Why does it matter whether my database is on an SSD or an HDD?
+
+These storage mediums have different performance characteristics. As a result, the optimal settings for an SSD are not the same as those for an HDD. Either configuration is compatible with SSD and HDD, but using the right configuration will make Immich snappier. As a general tip, we recommend users store the database on an SSD whenever possible.
+
+### Can I use the new database image as a general PostgreSQL image outside of Immich?
+
+It’s a standard PostgreSQL container image that additionally contains the VectorChord, pgvector, and (optionally) pgvecto.rs extensions. If you were using the previous pgvecto.rs image for other purposes, you can similarly do so with this image.
+
+[vchord-install]: https://docs.vectorchord.ai/vectorchord/getting-started/installation.html
+[pg-apt]: https://www.postgresql.org/download/linux/#generic

docs/docs/administration/monitor-immich.md

@@ -1,34 +1,15 @@
-# Monitoring
+# Monitor Immich
 
-## Overview
-
-Immich provides a variety of performance metrics to allow for local monitoring and insights. This integration is primarily in the form of Prometheus metrics. However, exporting traces is also possible due to the use of OpenTelemetry instrumentation.
-
-:::note
-This is an opt-in feature intended for you to monitor immich's performance. This data isn't sent anywhere beyond what you've configured.
-:::
+This guide sets up Prometheus and Grafana against an Immich instance, and switches Immich to JSON logging for a log aggregator. For what Immich exposes and why, see [Monitoring](/concepts/monitoring); for the log fields, see [Logging](/reference/logging).
 
 ## Prometheus
 
-Prometheus is a tool that collects metrics from a number of sources you configure. It operates in a "pull" strategy - that is, it periodically requests metrics from each defined source. This means that the source doesn't send anything until it's requested. It also means that the source -- immich, in this case -- has to expose an endpoint for Prometheus to target when it requests metrics.
-
-### Metrics
-
-These metrics come in a variety of forms:
-
-- Counters, which can only increase. Example: the number of times an endpoint has been called.
-- Gauges, which can increase or decrease within a certain range. Example: CPU utilization.
-- Histograms, where each observation is assigned to a certain number of "buckets". Example: response time, where each bucket is a number of milliseconds. This one is a bit more complicated.
-  - Buckets in this case are _cumulative_; that is, an observation is placed not only into the smallest bucket that contains it, but also to all buckets larger than this. For example, if a histogram has three buckets for 1ms, 5ms and 10ms, an observation of 3ms will be bucketed into both 5ms and 10ms.
-
-The metrics in immich are grouped into API (endpoint calls and response times), host (memory and CPU utilization), and IO (internal database queries, image processing, and so on). Each group of metrics can be enabled or disabled independently.
-
 ### Configuration
 
 Immich will not expose an endpoint for metrics by default. To enable this endpoint, you can add the `IMMICH_TELEMETRY_INCLUDE=all` environmental variable to your `.env` file. Note that only the server container currently use this variable.
 
 :::tip
-`IMMICH_TELEMETRY_INCLUDE=all` enables all metrics. For a more granular configuration you can enumerate the telemetry metrics that should be included as a comma separated list (e.g. `IMMICH_TELEMETRY_INCLUDE=repo,api`). Alternatively, you can also exclude specific metrics with `IMMICH_TELEMETRY_EXCLUDE`. For more information refer to the [environment section](/install/environment-variables.md#prometheus).
+`IMMICH_TELEMETRY_INCLUDE=all` enables all metrics. For a more granular configuration you can enumerate the telemetry metrics that should be included as a comma separated list (e.g. `IMMICH_TELEMETRY_INCLUDE=repo,api`). Alternatively, you can also exclude specific metrics with `IMMICH_TELEMETRY_EXCLUDE`. For more information refer to the [environment section](/reference/environment-variables#prometheus).
 :::
 
 The next step is to configure a new or existing Prometheus instance to scrape this endpoint. The following steps assume that you do not have an existing Prometheus instance, but the steps will be similar either way.
@@ -68,7 +49,7 @@ After bringing down the containers with `docker compose down` and back up with `
 :::note
 To see exactly what metrics are made available, you can additionally add `8081:8081` (API metrics) and `8082:8082` (microservices metrics) to the immich_server container's ports.
 Visiting the `/metrics` endpoint for these services will show the same raw data that Prometheus collects.
-To configure these ports see [`IMMICH_API_METRICS_PORT` & `IMMICH_MICROSERVICES_METRICS_PORT`](/install/environment-variables/#general).
+To configure these ports see [`IMMICH_API_METRICS_PORT` & `IMMICH_MICROSERVICES_METRICS_PORT`](/reference/environment-variables#general).
 :::
 
 ### Usage
@@ -128,24 +109,4 @@ IMMICH_LOG_FORMAT=json
 The default is `IMMICH_LOG_FORMAT=console` for human-readable logs with colors during development. For production deployments using log aggregation, use `IMMICH_LOG_FORMAT=json`.
 :::
 
-### JSON Log Format
-
-When enabled, logs are output in structured JSON format:
-
-```json
-{"level":"log","pid":36,"timestamp":1766533331507,"message":"Initialized websocket server","context":"WebsocketRepository"}
-{"level":"warn","pid":48,"timestamp":1766533331629,"message":"Unable to open /build/www/index.html, skipping SSR.","context":"ApiService"}
-{"level":"error","pid":36,"timestamp":1766533331690,"message":"Failed to load plugin immich-core:","context":"Error"}
-```
-
-This format includes:
-
-- `level`: Log level (log, warn, error, etc.)
-- `pid`: Process ID
-- `timestamp`: Unix timestamp in milliseconds
-- `message`: Log message
-- `context`: Service or component that generated the log
-
-For more information on log formats, see [`IMMICH_LOG_FORMAT`](/install/environment-variables.md#general).
-
 [prom-file]: https://github.com/immich-app/immich/releases/latest/download/prometheus.yml

docs/docs/administration/postgres-standalone.md

@@ -1,158 +0,0 @@
-# Pre-existing Postgres
-
-While not officially recommended, it is possible to run Immich using a pre-existing Postgres server. To use this setup, you should have a baseline level of familiarity with Postgres and the Linux command line. If you do not have these, we recommend using the default setup with a dedicated Postgres container.
-
-By default, Immich expects superuser permission on the Postgres database and requires certain extensions to be installed. This guide outlines the steps required to prepare a pre-existing Postgres server to be used by Immich.
-
-:::tip
-Running with a pre-existing Postgres server can unlock powerful administrative features, including logical replication and streaming write-ahead log backups using programs like pgBackRest or Barman.
-:::
-
-## Prerequisites
-
-You must install pgvector as it is a prerequisite for VectorChord.
-The easiest way to do this on Debian/Ubuntu is by adding the [PostgreSQL Apt repository][pg-apt] and then
-running `apt install postgresql-NN-pgvector`, where `NN` is your Postgres version (e.g., `16`).
-
-You must install VectorChord into your instance of Postgres using their [instructions][vchord-install]. After installation, add `shared_preload_libraries = 'vchord.so'` to your `postgresql.conf`. If you already have some `shared_preload_libraries` set, you can separate each extension with a comma. For example, `shared_preload_libraries = 'pg_stat_statements, vchord.so'`.
-
-:::note Supported versions
-Immich is known to work with Postgres versions `>= 14, < 20`.
-
-VectorChord is known to work with pgvector versions `>= 0.7, < 0.9`.
-
-The Immich server will check the VectorChord version on startup to ensure compatibility, and refuse to start if a compatible version is not found.
-The current accepted range for VectorChord is `>= 0.3, < 2.0`.
-:::
-
-## Specifying the connection URL
-
-You can connect to your pre-existing Postgres server by setting the `DB_URL` environment variable in the `.env` file.
-
-```
-DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename'
-
-# require a SSL connection to Postgres
-# DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename?sslmode=require'
-
-# require a SSL connection, but don't enforce checking the certificate name
-# DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename?sslmode=require&sslmode=no-verify'
-```
-
-## With superuser permission
-
-Typically Immich expects superuser permission in the database, which you can grant by running `ALTER USER <immichdbusername> WITH SUPERUSER;` at the `psql` console. If you prefer not to grant superuser permissions, follow the instructions in the next section.
-
-## Without superuser permission
-
-:::caution
-This method is recommended for **advanced users only** and often requires manual intervention when updating Immich.
-:::
-
-:::danger
-Currently, automated backups require superuser permission due to the usage of `pg_dumpall`.
-:::
-
-Immich can run without superuser permissions by following the below instructions at the `psql` prompt to prepare the database.
-
-```sql title="Set up Postgres for Immich"
-CREATE DATABASE <immichdatabasename>;
-\c <immichdatabasename>
-BEGIN;
-ALTER DATABASE <immichdatabasename> OWNER TO <immichdbusername>;
-CREATE EXTENSION vchord CASCADE;
-CREATE EXTENSION earthdistance CASCADE;
-COMMIT;
-```
-
-### Updating VectorChord
-
-When installing a new version of VectorChord, you will need to manually update the extension and reindex by connecting to the Immich database and running:
-
-```
-ALTER EXTENSION vchord UPDATE;
-REINDEX INDEX face_index;
-REINDEX INDEX clip_index;
-```
-
-## Migrating to VectorChord
-
-VectorChord is the successor extension to pgvecto.rs, allowing for higher performance, lower memory usage and higher quality results for smart search and facial recognition.
-
-### Migrating from pgvecto.rs
-
-Support for pgvecto.rs has been dropped as of 3.0, hence all users currently using pgvecto.rs should migrate to VectorChord. There are two primary approaches to do so.
-
-The easiest option is to have both extensions installed during the migration:
-
-<details>
-<summary>Migration steps (automatic)</summary>
-1. Ensure you still have pgvecto.rs installed
-2. Install `pgvector` (`>= 0.7, < 0.9`). The easiest way to do this is on Debian/Ubuntu by adding the [PostgreSQL Apt repository][pg-apt] and then running `apt install postgresql-NN-pgvector`, where `NN` is your Postgres version (e.g., `16`)
-3. [Install VectorChord][vchord-install]
-4. Add `shared_preload_libraries= 'vchord.so, vectors.so'` to your `postgresql.conf`, making sure to include _both_ `vchord.so` and `vectors.so`. You may include other libraries here as well if needed
-5. Restart the Postgres database
-6. If Immich does not have superuser permissions, run the SQL command `CREATE EXTENSION vchord CASCADE;` using psql or your choice of database client
-7. Start Immich and wait for the logs `Reindexed face_index` and `Reindexed clip_index` to be output
-8. If Immich does not have superuser permissions, run the SQL command `DROP EXTENSION vectors;`
-9. Drop the old schema by running `DROP SCHEMA vectors;`
-10. Remove the `vectors.so` entry from the `shared_preload_libraries` setting
-11. Restart the Postgres database
-12. Uninstall pgvecto.rs (e.g. `apt-get purge vectors-pg14` on Debian-based environments, replacing `pg14` as appropriate). `pgvector` must remain installed as it provides the data types used by `vchord`
-
-</details>
-
-If it is not possible to have both VectorChord and pgvecto.rs installed at the same time, you can perform the migration with more manual steps:
-
-<details>
-<summary>Migration steps (manual)</summary>
-1. While pgvecto.rs is still installed, run the following SQL command using psql or your choice of database client. Take note of the number outputted by this command as you will need it later
-
-```sql
-SELECT atttypmod as dimsize
-    FROM pg_attribute f
-    JOIN pg_class c ON c.oid = f.attrelid
-    WHERE c.relkind = 'r'::char
-    AND f.attnum > 0
-    AND c.relname = 'smart_search'::text
-    AND f.attname = 'embedding'::text;
-```
-
-2. Remove references to pgvecto.rs using the below SQL commands
-
-```sql
-DROP INDEX IF EXISTS clip_index;
-DROP INDEX IF EXISTS face_index;
-ALTER TABLE smart_search ALTER COLUMN embedding SET DATA TYPE real[];
-ALTER TABLE face_search ALTER COLUMN embedding SET DATA TYPE real[];
-```
-
-3. [Install VectorChord][vchord-install]
-4. Change the columns back to the appropriate vector types, replacing `<number>` with the number from step 1
-
-```sql
-CREATE EXTENSION IF NOT EXISTS vchord CASCADE;
-ALTER TABLE smart_search ALTER COLUMN embedding SET DATA TYPE vector(<number>);
-ALTER TABLE face_search ALTER COLUMN embedding SET DATA TYPE vector(512);
-```
-
-5. Start Immich and let it create new indices using VectorChord
-
-</details>
-
-### Migrating from pgvector
-
-<details>
-<summary>Migration steps</summary>
-1. Ensure you have at least `0.7.0` of pgvector installed. If it is below that, please upgrade it and run the SQL command `ALTER EXTENSION vector UPDATE;` using psql or your choice of database client
-2. Follow the Prerequisites to install VectorChord
-3. If Immich does not have superuser permissions, run the SQL command `CREATE EXTENSION vchord CASCADE;`
-4. Remove the `DB_VECTOR_EXTENSION=pgvector` environmental variable as it will make Immich still use pgvector if set
-5. Start Immich and let it create new indices using VectorChord
-
-</details>
-
-Note that VectorChord itself uses pgvector types, so you should not uninstall pgvector after following these steps.
-
-[vchord-install]: https://docs.vectorchord.ai/vectorchord/getting-started/installation.html
-[pg-apt]: https://www.postgresql.org/download/linux/#generic

docs/docs/administration/run-a-server-command.md

@@ -1,27 +1,10 @@
-# Server Commands
+# Run a server command
 
-The `immich-server` docker image comes preinstalled with an administrative CLI (`immich-admin`) that supports the following commands:
+The `immich-server` image ships an administrative CLI called `immich-admin`. Every available command is listed in [Server Commands](/reference/server-commands); this guide covers running them and shows what each one prints.
 
-| Command                    | Description                                                   |
-| -------------------------- | ------------------------------------------------------------- |
-| `help`                     | Display help                                                  |
-| `reset-admin-password`     | Reset the password for the admin user                         |
-| `disable-password-login`   | Disable password login                                        |
-| `enable-password-login`    | Enable password login                                         |
-| `disable-maintenance-mode` | Disable maintenance mode                                      |
-| `enable-maintenance-mode`  | Enable maintenance mode                                       |
-| `enable-oauth-login`       | Enable OAuth login                                            |
-| `disable-oauth-login`      | Disable OAuth login                                           |
-| `list-users`               | List Immich users                                             |
-| `grant-admin`              | Grant admin privileges to a user (by email)                   |
-| `revoke-admin`             | Revoke admin privileges from a user (by email)                |
-| `version`                  | Print Immich version                                          |
-| `change-media-location`    | Change database file paths to align with a new media location |
-| `schema-check`             | Verify database migrations and check for schema drift         |
+## Run a command
 
-## How to run a command
-
-To run a command, [connect](/guides/docker-help.md#attach-to-a-container) to the `immich_server` container and then execute the command via `immich-admin <command>`.
+To run a command, [connect](/administration/inspect-containers-and-logs#attach-to-a-container) to the `immich_server` container and then execute the command via `immich-admin <command>`.
 
 ## Examples
 

docs/docs/administration/run-database-queries.md

@@ -1,13 +1,13 @@
-# Database Queries
+# Run database queries
 
 :::danger
-Keep in mind that mucking around in the database might set the Moon on fire. Avoid modifying the database directly when possible, and always have current backups.
+Keep in mind that mucking around in the database might set the Moon on fire. Avoid modifying the database directly when possible, and always have current [backups](/concepts/backups).
 :::
 
 :::tip
 Run `docker exec -it immich_postgres psql --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME>` to connect to the database via the container directly.
 
-(Replace `<DB_DATABASE_NAME>` and `<DB_USERNAME>` with the values from your [`.env` file](/install/environment-variables#database)).
+(Replace `<DB_DATABASE_NAME>` and `<DB_USERNAME>` with the values from your [`.env` file](/reference/environment-variables#database)).
 :::
 
 ## Assets
@@ -142,7 +142,7 @@ DELETE FROM "person" WHERE "name" = 'PersonNameHere';
 SELECT "key", "value" FROM "system_metadata" WHERE "key" = 'system-config';
 ```
 
-(Only used when not using the [config file](/install/config-file))
+(Only used when not using the [config file](/reference/config-file))
 
 ### File properties
 

docs/docs/administration/run-machine-learning-remotely.md

@@ -1,4 +1,4 @@
-# Remote Machine Learning
+# Run machine learning remotely
 
 To alleviate [performance issues on low-memory systems](/FAQ.mdx#why-is-immich-slow-on-low-memory-systems-like-the-raspberry-pi) like the Raspberry Pi, you may also host Immich's machine learning container on a more powerful system, such as your laptop or desktop computer. The server container will send requests containing the image preview to the remote machine learning container for processing. The machine learning container does not persist this data or associate it with a particular user.
 
@@ -14,7 +14,7 @@ Image previews are sent to the remote machine learning container. Use this optio
 2. Copy the following `docker-compose.yml` to the remote server
 
 :::info
-If using hardware acceleration, the [hwaccel.ml.yml](https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml) file also needs to be added and the `docker-compose.yml` needs to be configured as described in the [hardware acceleration documentation](/features/ml-hardware-acceleration)
+If using hardware acceleration, the [hwaccel.ml.yml](https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml) file also needs to be added and the `docker-compose.yml` needs to be configured as described in the [hardware acceleration documentation](/administration/set-up-hardware-accelerated-machine-learning)
 :::
 
 ```yaml

docs/docs/administration/set-up-a-reverse-proxy.md

@@ -1,16 +1,8 @@
-# Reverse Proxy
+# Set up a reverse proxy
 
-Users can deploy a custom reverse proxy that forwards requests to Immich. This way, the reverse proxy can handle TLS termination, load balancing, or other advanced features. All reverse proxies between Immich and the user must forward all headers and set the `Host`, `X-Real-IP`, `X-Forwarded-Proto` and `X-Forwarded-For` headers to their appropriate values. Additionally, your reverse proxy should allow for big enough uploads. By following these practices, you ensure that all custom reverse proxies are fully compatible with Immich.
+Example configurations for common reverse proxies. Immich has a small set of requirements that any reverse proxy in front of it must meet — headers, upload size, and timeouts — which are listed in [Reverse proxy requirements](/reference/reverse-proxy-requirements). The examples below satisfy them.
 
-:::caution
-Immich does not support being served on a sub-path such as `location /immich {`. It has to be served on the root path of a (sub)domain.
-:::
-
-:::info
-If your reverse proxy uses the [Let's Encrypt](https://letsencrypt.org/) [http-01 challenge](https://letsencrypt.org/docs/challenge-types/#http-01-challenge), you may want to verify that the Immich well-known endpoint (`/.well-known/immich`) gets correctly routed to Immich, otherwise it will likely be routed elsewhere and the mobile app may run into connection issues.
-:::
-
-### Nginx example config
+## Nginx example config
 
 Below is an example config for nginx. Make sure to set `public_url` to the front-facing URL of your instance, and `backend_url` to the path of the Immich server.
 
@@ -55,7 +47,7 @@ server {
 }
 ```
 
-### Caddy example config
+## Caddy example config
 
 As an alternative to nginx, you can also use [Caddy](https://caddyserver.com/) as a reverse proxy (with automatic HTTPS configuration). Below is an example config.
 
@@ -65,7 +57,7 @@ immich.example.org {
 }
 ```
 
-### Apache example config
+## Apache example config
 
 Below is an example config for Apache2 site configuration.
 
@@ -80,7 +72,7 @@ Below is an example config for Apache2 site configuration.
 </VirtualHost>
 ```
 
-### Traefik Proxy example config
+## Traefik Proxy example config
 
 The example below is for Traefik version 3.
 

docs/docs/administration/set-up-an-smtp-provider.md

@@ -0,0 +1,49 @@
+# Set up an SMTP provider
+
+Immich sends [email notifications](/administration/set-up-email-notifications) through an SMTP server that you provide. Any SMTP server works; this guide covers obtaining credentials from common providers and where to enter them.
+
+## Where to enter the settings
+
+All providers are configured in the same place: `Administration > Settings > Notification Settings`, under Email.
+
+<img src={require('./img/email-settings.webp').default} width="80%" title="SMTP settings" />
+
+You will need the host, port, username, password, and whether the connection uses SMTPS. The sections below cover where those values come from for each provider.
+
+## Gmail
+
+Google requires an app password rather than your account password.
+
+1. Add [2-Step Verification](https://support.google.com/accounts/answer/185839) to your Google account. This is required before app passwords can be created.
+2. [Create an app password](https://myaccount.google.com/apppasswords).
+
+At the end of creating your app password, a password is displayed. Save it — this is the value for the password field in Immich.
+
+<img src={require('./img/google-app-password.webp').default} title="Google app password" />
+
+Use your Gmail address as the username. Google documents its current [SMTP server settings](https://support.google.com/mail/answer/7126229) for the host, port, and encryption values.
+
+## Microsoft 365
+
+Microsoft also requires an app password. Which portal you use depends on the type of account:
+
+| Account type | Portal                                          |
+| ------------ | ----------------------------------------------- |
+| Personal     | https://go.microsoft.com/fwlink/?linkid=2274139 |
+| Business     | https://myaccount.microsoft.com/security-info   |
+
+Then enter the following:
+
+| Setting  | Value                        |
+| -------- | ---------------------------- |
+| Host     | `smtp-mail.outlook.com`      |
+| Port     | `587`                        |
+| Username | Your email address           |
+| Password | The app password you created |
+| SMTPS    | Disabled                     |
+
+<img src={require('./img/email-ms-settings.webp').default} width="80%" title="SMTP settings for Microsoft 365" />
+
+## Other providers
+
+Any SMTP server can be used, including a self-hosted one. Consult your provider's documentation for the host, port, and whether to enable SMTPS, and prefer an app password or a dedicated sending credential over your main account password where the provider offers one.

docs/docs/administration/set-up-email-notifications.mdx

@@ -1,6 +1,6 @@
-# Email Notifications
+# Set up email notifications
 
-Immich supports the option to send notifications via Email for the following events:
+Immich supports the option to send notifications via Email for the following events (see [Notification settings](/reference/system-settings#notification-settings) for the server-side options):
 
 - Creating a new user
 - Notifying a user when they get added to a shared album
@@ -12,9 +12,7 @@ You can access the settings panel from the web at `Administration -> Settings ->
 
 Under Email, enter the required details to connect with an SMTP server.
 
-You can use [this guide](/guides/smtp-gmail) to use Gmail's SMTP server.
-
-You can use [this guide](/guides/smtp-microsoft365) to use Microsoft's SMTP server.
+See [Set up an SMTP provider](/administration/set-up-an-smtp-provider) for obtaining credentials from Gmail, Microsoft 365, and other providers.
 
 ## User's notifications settings
 

docs/docs/administration/set-up-hardware-accelerated-machine-learning.md

@@ -1,27 +1,13 @@
-# Hardware-Accelerated Machine Learning
+# Set up hardware-accelerated machine learning
 
-This feature allows you to use a GPU to accelerate machine learning tasks, such as Smart Search and Facial Recognition, while reducing CPU load.
+This feature allows you to use a [GPU](/reference/hardware-acceleration-support#machine-learning) to accelerate machine learning tasks, such as Smart Search and Facial Recognition, while reducing CPU load.
 As this is a new feature, it is still experimental and may not work on all systems.
 
 :::info
 You do not need to redo any machine learning jobs after enabling hardware acceleration. The acceleration device will be used for any jobs that run after enabling it.
 :::
 
-## Supported Backends
-
-- ARM NN (Mali)
-- CUDA (NVIDIA GPUs with [compute capability](https://developer.nvidia.com/cuda-gpus) 5.2 or higher)
-- ROCm (AMD GPUs)
-- OpenVINO (Intel GPUs such as Iris Xe and Arc)
-- RKNN (Rockchip)
-
-## Limitations
-
-- The instructions and configurations here are specific to Docker Compose. Other container engines may require different configuration.
-- Only Linux and Windows (through WSL2) servers are supported.
-- ARM NN is only supported on devices with Mali GPUs. Other Arm devices are not supported.
-- Some models may not be compatible with certain backends. CUDA is the most reliable.
-- Search latency isn't improved by ARM NN due to model compatibility issues preventing its use. However, smart search jobs do make use of ARM NN.
+The backends Immich can use, and what each one cannot do, are listed in [Hardware acceleration support](/reference/hardware-acceleration-support).
 
 ## Prerequisites
 
@@ -35,7 +21,7 @@ You do not need to redo any machine learning jobs after enabling hardware accele
   - Where and how you can get this file depends on device and vendor, but typically, the device vendor also supplies these
   - The `hwaccel.ml.yml` file assumes the path to it is `/usr/lib/libmali.so`, so update accordingly if it is elsewhere
   - The `hwaccel.ml.yml` file assumes an additional file `/lib/firmware/mali_csffw.bin`, so update accordingly if your device's driver does not require this file
-- Optional: Configure your `.env` file, see [environment variables](/install/environment-variables) for ARM NN specific settings
+- Optional: Configure your `.env` file, see [environment variables](/reference/environment-variables) for ARM NN specific settings
   - In particular, the `MACHINE_LEARNING_ANN_FP16_TURBO` can significantly improve performance at the cost of very slightly lower accuracy
 
 #### CUDA
@@ -47,10 +33,10 @@ You do not need to redo any machine learning jobs after enabling hardware accele
 
 #### ROCm
 
-- On Linux, The [AMDGPU driver module](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/docker.html) needs to be installed on the server and, if secure boot is used, the signing key of DKMS [needs to be enrolled in UEFI BIOS](https://wiki.debian.org/SecureBoot)
+- On Linux, The [AMDGPU driver module](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/guides/docker.html) needs to be installed on the server and, if secure boot is used, the signing key of DKMS [needs to be enrolled in UEFI BIOS](https://wiki.debian.org/SecureBoot)
 - The GPU must be supported by ROCm. If it isn't officially supported, you can attempt to use the `HSA_OVERRIDE_GFX_VERSION` environmental variable: `HSA_OVERRIDE_GFX_VERSION=<a supported version, e.g. 10.3.0>`. If this doesn't work, you might need to also set `HSA_USE_SVM=0`.
 - The ROCm image is quite large and requires at least 35GiB of free disk space. However, pulling later updates to the service through Docker will generally only amount to a few hundred megabytes as the rest will be cached.
-- This backend is new and may experience some issues. For example, GPU power consumption can be higher than usual after running inference, even if the machine learning service is idle. In this case, it will only go back to normal after being idle for 5 minutes (configurable with the [MACHINE_LEARNING_MODEL_TTL](/install/environment-variables) setting).
+- This backend is new and may experience some issues. For example, GPU power consumption can be higher than usual after running inference, even if the machine learning service is idle. In this case, it will only go back to normal after being idle for 5 minutes (configurable with the [MACHINE_LEARNING_MODEL_TTL](/reference/environment-variables) setting).
 - MIGraphX is a new backend for AMD cards, which compiles models at runtime. As such, the first few inferences will be slow.
 
 #### OpenVINO
@@ -82,7 +68,7 @@ You do not need to redo any machine learning jobs after enabling hardware accele
   - This is usually pre-installed on the device vendor's Linux images
 - RKNPU driver V0.9.8 or later must be available in the host server
   - You may confirm this by running `cat /sys/kernel/debug/rknpu/version` to check the version
-- Optional: Configure your `.env` file, see [environment variables](/install/environment-variables) for RKNN specific settings
+- Optional: Configure your `.env` file, see [environment variables](/reference/environment-variables) for RKNN specific settings
   - In particular, setting `MACHINE_LEARNING_RKNN_THREADS` to 2 or 3 can _dramatically_ improve performance for RK3576 and RK3588 compared to the default of 1, at the expense of multiplying the amount of RAM each model uses by that amount.
 
 ## Setup

docs/docs/administration/set-up-hardware-transcoding.md

@@ -1,6 +1,6 @@
-# Hardware Transcoding
+# Set up hardware transcoding
 
-This feature allows you to use a GPU to accelerate transcoding and reduce CPU load.
+This feature allows you to use a [GPU](/reference/hardware-acceleration-support#transcoding) to accelerate transcoding and reduce CPU load.
 Note that hardware transcoding produces significantly larger videos than software transcoding with similar settings, typically with lower quality. Using slow presets and preferring more efficient codecs can narrow this gap.
 As this is a new feature, it is still experimental and may not work on all systems.
 
@@ -8,26 +8,7 @@ As this is a new feature, it is still experimental and may not work on all syste
 You do not need to redo any transcoding jobs after enabling hardware acceleration. The acceleration device will be used for any jobs that run after enabling it.
 :::
 
-## Supported APIs
-
-- NVENC (NVIDIA)
-- Quick Sync (Intel)
-- RKMPP (Rockchip)
-- VAAPI (AMD / NVIDIA / Intel)
-
-## Limitations
-
-- The instructions and configurations here are specific to Docker Compose. Other container engines may require different configuration.
-- Only Linux and Windows (through WSL2) servers are supported.
-- WSL2 does not support Quick Sync.
-- Raspberry Pi is currently not supported.
-- Two-pass mode is only supported for NVENC. Other APIs will ignore this setting.
-- By default, only encoding is currently hardware accelerated. This means the CPU is still used for software decoding and tone-mapping.
-  - You can benefit from end-to-end acceleration by enabling hardware decoding in the video transcoding settings.
-- Hardware dependent
-  - Codec support varies, but H.264 and HEVC are usually supported.
-    - Notably, NVIDIA and AMD GPUs do not support VP9 encoding.
-  - Newer devices tend to have higher transcoding quality.
+The APIs and hardware Immich can use, and what each one cannot do, are listed in [Hardware acceleration support](/reference/hardware-acceleration-support).
 
 ## Prerequisites
 
@@ -74,7 +55,7 @@ For RKMPP to work:
 <details>
 <summary>immich.json</summary>
 
-If you use a [configuration file](/install/config-file.md), use the `accel` option to select the hardware (e.g. `qsv` for Intel or `nvenc` for Nvidia). Set `accelDecode` to `true` if you want hardware decoding.
+If you use a [configuration file](/reference/config-file), use the `accel` option to select the hardware (e.g. `qsv` for Intel or `nvenc` for Nvidia). Set `accelDecode` to `true` if you want hardware decoding.
 
 ```json
 {

docs/docs/administration/set-up-oauth-authentication.md

@@ -1,6 +1,6 @@
-# OAuth Authentication
+# Set up OAuth authentication
 
-This page contains details about using OAuth in Immich.
+This page contains details about using [OAuth](/reference/oauth-settings) in Immich.
 
 :::tip
 Unable to set `app.immich:///oauth-callback` as a valid redirect URI? See [Mobile Redirect URI](#mobile-redirect-uri) for an alternative solution.
@@ -29,7 +29,7 @@ Before enabling OAuth in Immich, a new client application needs to be configured
 2. Configure Redirect URIs/Origins
 
    The **Sign-in redirect URIs** should include:
-   - `app.immich:///oauth-callback` - for logging in with OAuth from the [Mobile App](/features/mobile-app.mdx)
+   - `app.immich:///oauth-callback` - for logging in with OAuth from the [Mobile App](/user-guide/use-the-mobile-app)
    - `http://DOMAIN:PORT/auth/login` - for logging in with OAuth from the Web Client
    - `http://DOMAIN:PORT/user-settings` - for manually linking OAuth in the Web Client
 
@@ -58,41 +58,7 @@ Before enabling OAuth in Immich, a new client application needs to be configured
 
 Once you have a new OAuth client application configured, Immich can be configured using the Administration Settings page, available on the web (Administration -> Settings).
 
-| 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)                      |
-| `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)           |
-| `prompt`                                             | string  | (empty)              | Prompt parameter for authorization url (examples: select_account, login, consent)   |
-| `end_session_endpoint`                               | URL     | (empty)              | Http(s) alternative end session endpoint (logout URI)                               |
-| 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**¹**                                           |
-| Default Storage Quota (GiB)                          | number  | 0                    | Default quota for user without storage quota claim (empty for unlimited quota)      |
-| Button Text                                          | string  | Login with OAuth     | Text for the OAuth button on the web                                                |
-| Auto Register                                        | boolean | true                 | When true, will automatically register a user the first time they sign in           |
-| [Auto Launch](#auto-launch)                          | boolean | false                | When true, will skip the login page and automatically start the OAuth login process |
-| [Mobile Redirect URI Override](#mobile-redirect-uri) | URL     | (empty)              | Http(s) alternative mobile redirect URI                                             |
-
-:::note Claim Options [1]
-
-Claim is only used on user creation and not synchronized after that.
-
-:::
-
-:::info
-The Issuer URL should look something like the following, and return a valid json document.
-
-- `https://accounts.google.com/.well-known/openid-configuration`
-- `http://localhost:9000/application/o/immich/.well-known/openid-configuration`
-
-The `.well-known/openid-configuration` part of the url is optional and will be automatically added during discovery.
-:::
+Every available setting is documented in [OAuth settings](/reference/oauth-settings).
 
 ## Auto Launch
 
@@ -107,7 +73,7 @@ The redirect URI for the mobile app is `app.immich:///oauth-callback`, which is
 2. Whitelist the new endpoint as a valid redirect URI with your provider.
 3. Specify the new endpoint as the `Mobile Redirect URI Override`, in the OAuth settings.
 
-With these steps in place, you should be able to use OAuth from the [Mobile App](/features/mobile-app.mdx) without a custom scheme redirect URI.
+With these steps in place, you should be able to use OAuth from the [Mobile App](/user-guide/use-the-mobile-app) without a custom scheme redirect URI.
 
 :::info
 Immich has a route (`/api/oauth/mobile-redirect`) that is already configured to forward requests to `app.immich:///oauth-callback`, and can be used for step 1.

docs/docs/administration/split-workers-across-containers.md

@@ -0,0 +1,32 @@
+# Split workers across containers
+
+The `immich-server` container runs several [workers](/reference/workers) at once. If you prefer to throttle or distribute them, you can do this using the [environment variables](/reference/environment-variables) to specify which container should pick up which tasks.
+
+For example, for a simple setup with one container for the Web/API and one for all other microservices, you can do the following:
+
+Copy the entire `immich-server` block as a new service and make the following changes to the **copy**:
+
+```diff
+- immich-server:
+-   container_name: immich_server
+...
+-   ports:
+-     - 2283:2283
++ immich-microservices:
++   container_name: immich_microservices
+```
+
+Once you have two copies of the immich-server service, make the following changes to each one. This will allow one container to only serve the web UI and API, and the other one to handle all other tasks.
+
+```diff
+services:
+  immich-server:
+    ...
++   environment:
++     IMMICH_WORKERS_INCLUDE: 'api'
+
+  immich-microservices:
+    ...
++   environment:
++     IMMICH_WORKERS_EXCLUDE: 'api'
+```

docs/docs/administration/storage-template.mdx

@@ -1,5 +0,0 @@
-import StorageTemplate from '/docs/partials/_storage-template.md';
-
-# Storage Template
-
-<StorageTemplate />

docs/docs/administration/use-a-config-file.md

@@ -0,0 +1,58 @@
+# Use a config file
+
+This guide sets up a config file so Immich's system settings come from a file you control instead of from the web UI. See the [config file reference](/reference/config-file) for the format, the full list of keys, and exactly how values are resolved.
+
+:::note
+Once a config file is in use, the settings under `Administration > Settings` become read-only. Removing `IMMICH_CONFIG_FILE` restores UI editing.
+:::
+
+## Step 1 - Create the config file
+
+Create a JSON file (e.g. `immich-config.json`) next to your `docker-compose.yml`. YAML is also supported.
+
+The file only needs the keys you want to change — everything else falls back to its default. To start from your current settings instead, use the button in `Administration > Settings` that copies the current configuration to your clipboard, then paste it into the file.
+
+For a minimal example, this enables the storage template and nothing else:
+
+```json title="immich-config.json"
+{
+  "storageTemplate": {
+    "enabled": true,
+    "template": "{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}"
+  }
+}
+```
+
+The [config file reference](/reference/config-file#default-configuration) lists every available key with its default value.
+
+## Step 2 - Point Immich at the file
+
+Set `IMMICH_CONFIG_FILE` in your `.env` file to the path of the config file **inside the container**:
+
+```ini title=".env"
+IMMICH_CONFIG_FILE=/config/immich-config.json
+```
+
+:::info Docker Compose
+In your `.env` file, `UPLOAD_LOCATION` and `DB_DATA_LOCATION` refer to locations on the host, but `IMMICH_CONFIG_FILE` refers to a location inside the container. Reuse the variable in `docker-compose.yml` so the two can't drift apart:
+
+```yaml title="docker-compose.yml"
+volumes:
+  - ./immich-config.json:${IMMICH_CONFIG_FILE}
+```
+
+:::
+
+:::note
+If you run separate `microservices` workers, mount the config file into those containers as well, at the same path.
+:::
+
+## Step 3 - Restart Immich
+
+```bash
+docker compose up -d
+```
+
+Immich reads the config file at startup, so restart the containers after every change to the file.
+
+To confirm it took effect, open `Administration > Settings` — the settings should now be read-only. If the server fails to start, check its logs: an invalid config file is a fatal error, and the log names the key that failed validation.

docs/docs/administration/use-a-custom-map-style.md

@@ -1,7 +1,7 @@
-# Custom Map Styles
+# Use a custom map style
 
 You may decide that you'd like to modify the style document which is used to
-draw the maps in Immich. In addition to visual customization, this also allows
+draw the [maps](/reference/system-settings) in Immich. In addition to visual customization, this also allows
 you to pick your own map tile provider instead of the default one. The default
 `style.json` for [light theme](https://tiles.immich.cloud/v1/style/light.json)
 and [dark theme](https://tiles.immich.cloud/v1/style/dark.json)

docs/docs/administration/use-a-pre-existing-postgres-server.md

@@ -0,0 +1,74 @@
+# Use a pre-existing Postgres server
+
+While not officially recommended, it is possible to run Immich using a pre-existing [Postgres](/reference/requirements#database) server. To use this setup, you should have a baseline level of familiarity with Postgres and the Linux command line. If you do not have these, we recommend using the default setup with a dedicated Postgres container.
+
+By default, Immich expects superuser permission on the Postgres database and requires certain extensions to be installed. This guide outlines the steps required to prepare a pre-existing Postgres server to be used by Immich.
+
+If the server is still using pgvecto.rs or pgvector, see [Migrate to VectorChord](/administration/migrate-to-vectorchord) instead.
+
+:::tip
+Running with a pre-existing Postgres server can unlock powerful administrative features, including logical replication and streaming write-ahead log backups using programs like pgBackRest or Barman.
+:::
+
+## Prerequisites
+
+You must install pgvector as it is a prerequisite for VectorChord.
+The easiest way to do this on Debian/Ubuntu is by adding the [PostgreSQL Apt repository][pg-apt] and then
+running `apt install postgresql-NN-pgvector`, where `NN` is your Postgres version (e.g., `16`).
+
+You must install VectorChord into your instance of Postgres using their [instructions][vchord-install]. After installation, add `shared_preload_libraries = 'vchord.so'` to your `postgresql.conf`. If you already have some `shared_preload_libraries` set, you can separate each extension with a comma. For example, `shared_preload_libraries = 'pg_stat_statements, vchord.so'`.
+
+The versions Immich supports are listed in [Requirements](/reference/requirements#database).
+
+## Specifying the connection URL
+
+You can connect to your pre-existing Postgres server by setting the `DB_URL` environment variable in the `.env` file.
+
+```
+DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename'
+
+# require a SSL connection to Postgres
+# DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename?sslmode=require'
+
+# require a SSL connection, but don't enforce checking the certificate name
+# DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename?sslmode=require&sslmode=no-verify'
+```
+
+## With superuser permission
+
+Typically Immich expects superuser permission in the database, which you can grant by running `ALTER USER <immichdbusername> WITH SUPERUSER;` at the `psql` console. If you prefer not to grant superuser permissions, follow the instructions in the next section.
+
+## Without superuser permission
+
+:::caution
+This method is recommended for **advanced users only** and often requires manual intervention when updating Immich.
+:::
+
+:::danger
+Currently, automated backups require superuser permission due to the usage of `pg_dumpall`.
+:::
+
+Immich can run without superuser permissions by following the below instructions at the `psql` prompt to prepare the database.
+
+```sql title="Set up Postgres for Immich"
+CREATE DATABASE <immichdatabasename>;
+\c <immichdatabasename>
+BEGIN;
+ALTER DATABASE <immichdatabasename> OWNER TO <immichdbusername>;
+CREATE EXTENSION vchord CASCADE;
+CREATE EXTENSION earthdistance CASCADE;
+COMMIT;
+```
+
+### Updating VectorChord
+
+When installing a new version of VectorChord, you will need to manually update the extension and reindex by connecting to the Immich database and running:
+
+```
+ALTER EXTENSION vchord UPDATE;
+REINDEX INDEX face_index;
+REINDEX INDEX clip_index;
+```
+
+[vchord-install]: https://docs.vectorchord.ai/vectorchord/getting-started/installation.html
+[pg-apt]: https://www.postgresql.org/download/linux/#generic

docs/docs/administration/use-custom-file-locations.md

@@ -1,6 +1,6 @@
-# Files Custom Locations
+# Use custom file locations
 
-This guide explains how to store generated and raw files with docker's volume mount in different locations.
+This guide explains how to store [generated and raw files](/reference/storage-locations) with docker's volume mount in different locations.
 
 :::caution Backup
 It is important to remember to update the backup settings after following the guide to back up the new backup paths if using automatic backup tools, especially `profile/`.
@@ -9,7 +9,7 @@ It is important to remember to update the backup settings after following the gu
 In our `.env` file, we will define the paths we want to use. Note that you don't have to define all of these: UPLOAD_LOCATION will be the base folder that files are stored in by default, with the other paths acting as overrides.
 
 ```diff title=".env"
-# You can find documentation for all the supported environment variables [here](/install/environment-variables)
+# You can find documentation for all the supported environment variables [here](/reference/environment-variables)
 
 # Custom location where your uploaded, thumbnails, and transcoded video files are stored
 - UPLOAD_LOCATION=./library
@@ -42,11 +42,4 @@ Then restart Immich to register the changes:
 docker compose up -d
 ```
 
-:::note
-Because of the underlying properties of docker bind mounts, it is not recommended to mount the `upload/` and `library/` folders as separate bind mounts if they are on the same device.
-For this reason, we mount the HDD or the network storage (NAS) to `/data` and then mount the folders we want to access under that folder.
-
-The `thumbs/` folder contains both the small thumbnails displayed in the timeline and the larger previews shown when clicking into an image. These cannot be separated.
-
-The storage metrics of the Immich server will track available storage at `UPLOAD_LOCATION`, so the administrator must set up some sort of monitoring to ensure the storage does not run out of space. The `profile/` folder is much smaller, usually less than 1 MB.
-:::
+See [Storage locations](/reference/storage-locations) for what each directory holds and the constraints on splitting them across devices.

docs/docs/administration/use-maintenance-mode.md

@@ -1,11 +1,11 @@
-# Maintenance Mode
+# Use maintenance mode
 
-Maintenance mode is used to perform administrative tasks such as restoring backups to Immich.
+Maintenance mode is used to perform administrative tasks such as restoring [backups](/concepts/backups) to Immich.
 
 You can enter maintenance mode by either:
 
 - Selecting "Switch to maintenance mode" in `Maintenance` tab in administration.
-- Running the enable maintenance mode [administration command](./server-commands.md).
+- Running the enable maintenance mode [administration command](/administration/run-a-server-command).
 
 ## Logging in during maintenance
 
@@ -14,5 +14,5 @@ Maintenance mode uses a separate login system which is handled automatically beh
 If you find that you've been logged out, you can:
 
 - Open the logs for the Immich server and look for _"🚧 Immich is in maintenance mode, you can log in using the following URL:"_
-- Run the enable maintenance mode [administration command](./server-commands.md) again, this will give you a new URL to login with.
-- Run the disable maintenance mode [administration command](./server-commands.md) then re-enter through system settings.
+- Run the enable maintenance mode [administration command](/administration/run-a-server-command) again, this will give you a new URL to login with.
+- Run the disable maintenance mode [administration command](/administration/run-a-server-command) then re-enter through system settings.

docs/docs/administration/use-the-backup-script-template.md

@@ -1,13 +1,13 @@
-# Backup Script
+# Use the backup script template
 
-[Borg](https://www.borgbackup.org/) is a feature-rich deduplicating archiving software with built-in versioning. We provide a template bash script that can be run daily/weekly as a [cron](https://wiki.archlinux.org/title/cron) job to back up your files and database. We encourage you to read the quick-start guide for Borg before running this script.
+[Borg](https://www.borgbackup.org/) is a feature-rich deduplicating archiving software with built-in versioning. We provide a template bash script that can be run daily/weekly as a [cron](https://wiki.archlinux.org/title/cron) job to back up your files and database — see [Backups](/concepts/backups) for what a complete backup has to include. We encourage you to read the quick-start guide for Borg before running this script.
 
 This script assumes you have a second hard drive connected to your server for on-site backup and ssh access to a remote machine for your third off-site copy. [BorgBase](https://www.borgbase.com/) is an alternative option for off-site backups with a competitive pricing structure. You may choose to skip off-site backups entirely by removing the relevant lines from the template script.
 
 The database is saved to your Immich upload folder in the `database-backup` subdirectory. The database is then backed up and versioned with your assets by Borg. This ensures that the database backup is in sync with your assets in every snapshot.
 
 :::info
-This script makes backups of your database along with your photo/video library. This is redundant with the [automatic database backup tool](/administration/backup-and-restore#automatic-database-dumps) built into Immich. Using this script to backup your database has two advantages over the built-in backup tool:
+This script makes backups of your database along with your photo/video library. This is redundant with the [automatic database backup tool](/administration/back-up-and-restore#automatic-database-backups) built into Immich. Using this script to backup your database has two advantages over the built-in backup tool:
 
 - This script uses storage more efficiently by versioning your backups instead of making multiple copies.
 - The database backups are performed at the same time as the library backup, ensuring that the backups of your database and the library are always in sync.

docs/docs/administration/use-the-storage-template.mdx

@@ -0,0 +1,7 @@
+import StorageTemplate from '/docs/partials/_storage-template.md';
+
+# Use the storage template
+
+The storage template controls the path each original asset is written to. It changes where files live on disk, so see [Storage locations](/reference/storage-locations) for the resulting layout before enabling it.
+
+<StorageTemplate />

docs/docs/administration/view-server-stats.md

@@ -1,6 +1,6 @@
-# Server Stats
+# View server stats
 
-Server statistics to show the total number of videos, photos, usage and quota per user.
+Server statistics to show the total number of videos, photos, usage and quota per user. Note that this counts the [directories Immich manages](/reference/storage-locations); external libraries are excluded.
 
 :::info External library
 External libraries are not included in the storage quota due to custom mount points.

docs/docs/api.md

@@ -1,13 +0,0 @@
-# API
-
-Immich uses the [OpenAPI](https://swagger.io/specification/) standard to generate API documentation. To view the published docs see [here](https://api.immich.app/).
-
-## Generator
-
-OpenAPI is used to generate the client (Typescript, Dart) SDK. `openapi-generator-cli` can be installed [here](https://openapi-generator.tech/docs/installation/). The generated SDK is based on the `immich-openapi-specs.json` file, which is autogenerated by the server **when running in development mode**. The `immich-openapi-specs.json` file can be modified with `@nestjs/swagger` decorators used or referenced by controller endpoints. See the [NestJS OpenAPI docs](https://docs.nestjs.com/openapi/types-and-parameters) for more info. When you add a new endpoint or modify an existing one, you must run the server in development mode and run the command below to update the client SDK.
-
-```bash
-mise open-api
-```
-
-You can find the generated client SDK in the `packages/sdk/client` for Typescript SDK and `mobile/generated/openapi` for Dart SDK.

docs/docs/concepts/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Concepts",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "title": "Concepts",
+    "description": "Background and discussion of how Immich works and why it works that way. Read these to deepen your understanding, not to complete a task."
+  }
+}

docs/docs/concepts/backups.md

@@ -0,0 +1,48 @@
+# Backups
+
+Photos and videos are usually irreplaceable. Unlike most self-hosted data, there is no upstream copy to re-download and no way to recreate a lost photo — which makes backups the single most important part of running Immich.
+
+Immich does not back itself up. It creates database dumps, and it tells you which files matter, but taking, storing, and testing an actual backup is left to you and the backup tool of your choice. A [3-2-1 backup](/reference/3-2-1-backup-method) is the usual target: three copies, on two different kinds of storage, with one copy off-site.
+
+## What a complete backup contains
+
+An Immich backup has two halves, and it is only useful if you have both:
+
+- **The database**, which holds asset metadata, album membership, recognized faces, tags, sharing, and the file path of every asset.
+- **The original files**, which are the photos and videos themselves.
+
+Neither half is sufficient alone. Without the files, the database describes assets that no longer exist. Without the database, the files remain on disk but Immich has no record of them — Immich does not scan its library folder to discover assets, so albums, people, and all other metadata are gone even though the images survive. This is why a copy of `UPLOAD_LOCATION` on its own is not a backup.
+
+## Original versus generated content
+
+Immich stores two kinds of content in the filesystem:
+
+- **Original content** — the assets as uploaded, plus profile images. This is the irreplaceable part.
+- **Generated content** — thumbnails, previews, and transcoded videos. These are derived from the originals and Immich can rebuild them by re-running the corresponding jobs.
+
+Backing up everything is simplest and avoids a lengthy regeneration after a restore. Backing up only the original content produces a smaller backup at the cost of re-running the thumbnail and transcoding jobs when you restore.
+
+## Automatic database backups
+
+Immich periodically dumps its own database and keeps the last several dumps. These exist so that a database can be recovered without any external tooling — a corrupted database, a failed upgrade, a mistaken deletion.
+
+They are not a substitute for a backup, for two reasons:
+
+- They contain **metadata only**, never photos or videos.
+- They are written inside `UPLOAD_LOCATION`, so they are lost along with everything else if that storage fails. An off-site copy is what protects against that.
+
+Treat them as a convenience for recovering the database, and as one of the things your real backup needs to include.
+
+## Consistency between the database and the files
+
+Because a backup covers two moving parts, they can drift out of sync while it runs — an asset uploaded mid-backup may be recorded in one half and missing from the other. The result after a restore is broken assets.
+
+Stopping the `immich-server` container for the duration of the backup removes the problem entirely: if nothing is changing, the two halves always agree.
+
+If stopping the container is not an option, the order matters. Back up the database **first** and the filesystem **second**. The worst case is then a file on disk that the database does not know about, which can be re-uploaded manually. Backing up in the other order risks a restored database that references files absent from the backup, which cannot be recovered.
+
+## Restoring
+
+A restore puts the database back and expects the files to already be in place. Restoring a database taken from a different Immich version may require migrations, which Immich attempts automatically, so keeping backups aligned with the version that produced them makes recovery more predictable.
+
+The mechanics — where the dumps live, how to trigger one, and every way to restore — are in [Backup and restore](/administration/back-up-and-restore).

docs/docs/concepts/comparison.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 3
----
-
 # Comparison
 
 If you're new here and came from other asset self-hosting alternatives you might want to look at a comparison between Immich and your current solution.

docs/docs/concepts/duplicate-detection.md

@@ -1,19 +1,19 @@
-# Duplicates Utility
+# Duplicate detection
 
-Immich comes with a duplicates utility to help you detect assets that look visually similar. The duplicate detection feature relies on machine learning and is enabled by default. For more information about when the duplicate detection job runs, see [Jobs and Workers](/administration/jobs-workers). Once an asset has been processed and added to a duplicate group, it becomes available to review in the "Review duplicates" utility, which can be found [here](https://my.immich.app/utilities/duplicates).
+Duplicate detection relies on machine learning and is enabled by default. It compares the search embeddings Immich already generates for contextual search, which is why it finds assets that _look_ alike rather than only byte-identical files — a resized or re-encoded copy of a photo is still detected.
 
-## Reviewing duplicates
+This is distinct from the checksum-based deduplication that happens at upload time, which only skips files that are byte-for-byte identical to an existing asset.
 
-The review duplicates page allows the user to individually select which assets should be kept and which ones should be trashed. When more than one asset is kept, there is an option to automatically put the kept assets into a stack.
+Detection runs as a job after Smart Search completes for an asset; see [processing order](/reference/jobs#processing-order). Once an asset has been processed and added to a duplicate group, it appears in the review utility.
 
-### Automatic preselection
+## How assets are preselected
 
 When using "Deduplicate All" or viewing suggestions, Immich automatically preselects which assets to keep based on:
 
 1. **Image size in bytes** — larger files are preferred as they typically have higher quality.
 2. **Count of EXIF data** — assets with more metadata are preferred.
 
-### Synchronizing metadata
+## What happens to metadata
 
 When resolving duplicates, metadata from trashed assets is automatically synchronized to the kept asset. This synchronization only happens when **exactly one** asset is kept and at least one asset is trashed. When more than one asset is kept, metadata is not merged — the assets keep their own metadata and are simply removed from the duplicate group. The following metadata is synchronized:
 
@@ -26,3 +26,5 @@ When resolving duplicates, metadata from trashed assets is automatically synchro
 | Visibility  | The most restrictive visibility is applied to the kept asset.                                                                  |
 | Location    | Latitude and longitude are copied if all assets with geolocation data in the group share the same coordinates.                 |
 | Tag         | Tags from all assets in the group are merged and applied to the kept asset.                                                    |
+
+To work through the results, see [Review duplicates](/user-guide/review-duplicates).

docs/docs/concepts/external-libraries.md

@@ -0,0 +1,51 @@
+# External libraries
+
+:::info
+Currently an external library can only belong to a single user which is selected when the library is initially created.
+:::
+
+External libraries track assets stored in the filesystem outside of Immich. When the external library is scanned, Immich will load videos and photos from disk and create the corresponding assets. These assets will then be shown in the main timeline, and they will look and behave like any other asset, including viewing on the map, adding to albums, etc. Later, if a file is modified outside of Immich, you need to scan the library for the changes to show up.
+
+If an external asset is deleted from disk, Immich will move it to trash on rescan. To restore the asset, you need to restore the original file. After 30 days the file will be removed from trash, and any changes to metadata within Immich will be lost.
+
+:::caution
+
+If you add metadata to an external asset in any way (i.e. add it to an album or edit the description), that metadata is only stored inside Immich and will not be persisted to the external asset file. If you move an asset to another location within the library all such metadata will be lost upon rescan. This is because the asset is considered a new asset after the move. This is a known issue and will be fixed in a future release.
+
+:::
+
+:::caution
+
+Due to aggressive caching it can take some time for a refreshed asset to appear correctly in the web view. You need to clear the cache in your browser to see the changes. This is a known issue and will be fixed in a future release. In Chrome, you need to open the developer console with F12, then reload the page with F5, and finally right click on the reload button and select "Empty Cache and Hard Reload".
+
+:::
+
+To set one up, see [Add an external library](/administration/add-an-external-library).
+
+## What a library contains
+
+A library's contents are defined by its **import paths** — the directories it scans — minus its **exclusion patterns**. Both are properties of the library, and both are evaluated on every scan, so changing either one adds or removes assets on the next scan rather than only affecting new files.
+
+That symmetry is the thing to keep in mind: a file that stops matching, because a path was removed or a pattern was added, leaves the library the same way a file deleted from disk would.
+
+See [External Library settings](/reference/system-settings#external-library) for how these are configured, and [Exclusion patterns](/reference/exclusion-patterns) for the pattern syntax.
+
+## Automatic watching (EXPERIMENTAL)
+
+This feature is considered experimental and for advanced users only. If enabled, it will allow automatic watching of the filesystem which means new assets are automatically imported to Immich without needing to rescan.
+
+If your photos are on a network drive, automatic file watching likely won't work. In that case, you will have to rely on a [periodic library refresh](/administration/add-an-external-library#set-a-custom-scan-interval) to pull in your changes.
+
+### Troubleshooting
+
+If you encounter an `ENOSPC` error, you need to increase your file watcher limit. In sysctl, this key is called `fs.inotify.max_user_watches` and has a default value of 8192. Increase this number to a suitable value greater than the number of files you will be watching. Note that Immich has to watch all files in your import paths including any ignored files.
+
+```
+ERROR [LibraryService] Library watcher for library c69faf55-f96d-4aa0-b83b-2d80cbc27d98 encountered error: Error: ENOSPC: System limit for number of file watchers reached, watch '/media/photo.jpg'
+```
+
+In rare cases, the library watcher can hang, preventing Immich from starting up. In this case, disable the library watcher in the configuration file. If the watcher is enabled from within Immich, the app must be started without the microservices. Disable the microservices in the docker compose file, start Immich, disable the library watcher in the admin settings, close Immich, re-enable the microservices, and then Immich can be started normally.
+
+## 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.

docs/docs/concepts/facial-recognition.md

@@ -1,40 +1,12 @@
-# Facial Recognition
+# Facial recognition
 
-## Overview
+Immich detects faces in your photos and videos, then groups the detected faces into people. Two separate machine learning steps are involved, and this page explains what each one does and how the settings that control them interact. For the day-to-day actions — naming, merging, hiding people — see [Browse and manage people](/user-guide/browse-and-manage-people).
 
-Immich recognizes faces in your photos and videos and groups them together into people. You can then assign names to these people and search for them.
-
-The list of people is shown in the Explore page.
-
-<img src={require('./img/facial-recognition-1.webp').default} title='Facial Recognition 1' />
-
-Upon clicking on a person, a list of assets that contain their face will be shown.
-
-<img src={require('./img/facial-recognition-2.webp').default} title='Facial Recognition 2' />
-
-The asset detail view will also show the faces that are recognized in the asset.
-
-<img src={require('./img/facial-recognition-3.webp').default} title='Facial Recognition 3' />
-
-## Actions
-
-Additional actions you can do include:
-
-- Changing the feature photo of the person
-- Hiding the faces of a person from the Explore page and detail view
-- Setting a person's date of birth, so that the age of the person can be shown at the time the photo was taken
-- Merging two or more detected people into one person
-- Favoriting a person to pin them to the top of the list
-
-It can be found from the app bar when you access the detail view of a person.
-
-<img src={require('./img/facial-recognition-4.webp').default} title='Facial Recognition 4' />
-
-## How Face Detection Works
+## How face detection works
 
 Face detection sends the generated preview image to the machine learning service for processing. The service checks if it has the relevant model downloaded and downloads it if not. The image is decoded, pre-processed and passed to the face detection model (with hardware acceleration if configured). The bounding boxes and scores outputted from this model are used to crop and preprocess the image once again to be passed to a facial recognition model (also accelerated if configured). The embeddings from the recognition model, together with the bounding boxes and scores from the face detection model, are then sent back to the server to be added to the database. The embeddings in particular are indexed so they can be searched quickly during facial recognition clustering.
 
-## How Facial Recognition Works
+## How facial recognition works
 
 The facial recognition algorithm we use is derived from [DBSCAN](https://www.youtube.com/watch?v=RDZUdRSDOok), a popular clustering algorithm. It essentially treats each detected face as a point in a graph and aims to group points that are close to each other.
 
@@ -70,7 +42,7 @@ Navigating to Administration > Settings > Machine Learning Settings > Facial Rec
 :::tip
 It's better to only tweak the parameters here than to set them to something very different unless you're ready to test a variety of options. If you do need to set a parameter to a strict setting, relaxing other settings can be a good option to compensate, and vice versa.
 
-You can learn how the tune the result in this [Guide](/guides/better-facial-clusters)
+You can learn how to tune the result in [Better facial recognition clusters](/administration/improve-facial-recognition-clusters)
 :::
 
 ### Facial recognition model
@@ -85,10 +57,10 @@ After changing this setting, it will only apply to new face detection jobs. To a
 
 ### Maximum recognition distance
 
-The distance threshold described in How Facial Recognition Works. The default works well for most people, but it may be worth lowering it if the library has twins or otherwise very similar looking people. A threshold that's too low just means needing to merge duplicate people after facial recognition, whereas a threshold too high can produce unsalvageable results. It is strongly recommended not to go below 0.3 or above 0.7.
+The distance threshold described in [How facial recognition works](#how-facial-recognition-works). The default works well for most people, but it may be worth lowering it if the library has twins or otherwise very similar looking people. A threshold that's too low just means needing to merge duplicate people after facial recognition, whereas a threshold too high can produce unsalvageable results. It is strongly recommended not to go below 0.3 or above 0.7.
 
 ### Minimum recognized faces
 
-The core point threshold described in How Facial Recognition Works. This setting has a few implications. First, it takes effect immediately in that people with fewer faces than this are hidden from view. Secondly, it makes clustering more robust as it prevents loosely-related faces from being linked to each other by requiring a certain level of density.
+The core point threshold described in [How facial recognition works](#how-facial-recognition-works). This setting has a few implications. First, it takes effect immediately in that people with fewer faces than this are hidden from view. Secondly, it makes clustering more robust as it prevents loosely-related faces from being linked to each other by requiring a certain level of density.
 
 Increasing this setting is a good idea if you increase the recognition distance or reduce the minimum detection score. Setting it to 1 effectively disables the concept of core points, but can be an option if you prefer a more hands-on approach.

docs/docs/concepts/mobile-backup.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 1
----
-
 # Mobile Backup
 
 ## Overview
@@ -54,6 +50,20 @@ When enabled, Immich automatically creates albums on the server that mirror the
 
 This is a one-way sync from your device to the server. You can enable this feature at any time and use the **Reorganize into album** button to backfill existing uploads into their corresponding albums.
 
+### Album synchronization semantics
+
+- **One-Way Sync:** Synchronization is one-way, from the device to the server.
+
+- **Name Matching:** If an album on the server has the same name as the album on the device, images from the device will be merged with the existing images in the server album.
+
+- **Shared Albums:** If the matching album on the server is shared, the new photos merged into the album will also be shared.
+
+- **Album Structure:** When an album is created for the first time, its structure is based on the initial state. Future updates made on the phone (such as deleting or repositioning photos) will not be reflected in Immich.
+
+- **User-Specific Sync:** Album synchronization is unique to each server user and does not sync between different users or partners.
+
+- **Mobile-Only Feature:** Album synchronization is currently only available on mobile. For similar options on a computer, refer to [Libraries](/concepts/external-libraries) for further details.
+
 ## Platform Specific Features
 
 ### Android

docs/docs/concepts/monitoring.md

@@ -0,0 +1,24 @@
+# Monitoring
+
+Immich exposes performance metrics so an instance can be observed locally. The integration is primarily Prometheus metrics, though exporting traces is also possible because the instrumentation uses OpenTelemetry.
+
+This is an opt-in feature. Nothing is sent anywhere beyond what you configure — see [Monitor Immich](/administration/monitor-immich) to turn it on.
+
+## How Prometheus collects metrics
+
+Prometheus is a tool that collects metrics from a number of sources you configure. It operates in a "pull" strategy - that is, it periodically requests metrics from each defined source. This means that the source doesn't send anything until it's requested. It also means that the source -- immich, in this case -- has to expose an endpoint for Prometheus to target when it requests metrics.
+
+## Kinds of metric
+
+These metrics come in a variety of forms:
+
+- Counters, which can only increase. Example: the number of times an endpoint has been called.
+- Gauges, which can increase or decrease within a certain range. Example: CPU utilization.
+- Histograms, where each observation is assigned to a certain number of "buckets". Example: response time, where each bucket is a number of milliseconds. This one is a bit more complicated.
+  - Buckets in this case are _cumulative_; that is, an observation is placed not only into the smallest bucket that contains it, but also to all buckets larger than this. For example, if a histogram has three buckets for 1ms, 5ms and 10ms, an observation of 3ms will be bucketed into both 5ms and 10ms.
+
+The metrics in immich are grouped into API (endpoint calls and response times), host (memory and CPU utilization), and IO (internal database queries, image processing, and so on). Each group of metrics can be enabled or disabled independently.
+
+## Structured logging
+
+By default Immich writes human-readable console logs. It can instead emit one JSON object per log line, which is what log aggregation systems such as Grafana Loki, the ELK stack, Datadog, or Splunk expect to ingest. The field names and an example are in [Logging](/reference/logging#log-format).

docs/docs/concepts/open-source.md

@@ -0,0 +1 @@
+# Open Source

docs/docs/concepts/remote-access.md

@@ -46,7 +46,7 @@ You can learn how to set up Tailscale together with Immich with the [tutorial vi
 
 A reverse proxy is a service that sits between web servers and clients. A reverse proxy can either be hosted on the server itself or remotely. Clients can connect to the reverse proxy via https, and the proxy relays data to Immich. This setup makes most sense if you have your own domain and want to access your Immich instance just like any other website, from outside your LAN. You can also use a DDNS provider like DuckDNS or no-ip if you don't have a domain. This configuration allows the Immich Android and iphone apps to connect to your server without a VPN or tailscale app on the client side.
 
-If you're hosting your own reverse proxy, [Nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) is a great option. An example configuration for Nginx is provided [here](/administration/reverse-proxy.md).
+If you're hosting your own reverse proxy, [Nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) is a great option. An example configuration for Nginx is provided [here](/administration/set-up-a-reverse-proxy).
 
 You'll also need your own certificate to authenticate https connections. If you're making Immich publicly accessible, [Let's Encrypt](https://letsencrypt.org/) can provide a free certificate for your domain and is the recommended option. Alternatively, a [self-signed certificate](https://en.wikipedia.org/wiki/Self-signed_certificate) allows you to encrypt your connection to Immich, but it raises a security warning on the client's browser.
 

docs/docs/concepts/reverse-geocoding.md

@@ -0,0 +1,41 @@
+# Reverse Geocoding
+
+Reverse geocoding turns the coordinates stored in a photo into place names — city, state, and country. Immich does this [locally](https://en.wikipedia.org/wiki/Reverse_geocoding) using a copy of the [GeoNames](https://www.geonames.org/) geographical database that lives in your own Postgres database, so no coordinates are ever sent to a third-party service.
+
+## How it works
+
+1. The [Metadata Extraction](/reference/jobs#extract-metadata) job reads `GPSLatitude` and `GPSLongitude` from the asset. Coordinates of exactly `0,0` are treated as no location, since that is what many devices write when there is no GPS fix.
+2. If reverse geocoding is enabled, those coordinates are looked up against the GeoNames data already loaded into Postgres.
+3. Immich searches for populated places within roughly 25 km of the coordinates and takes the **nearest** one.
+4. That place supplies the city name and the state (its first-level administrative division); the country comes from the place's ISO country code.
+5. The resulting city, state, and country are stored on the asset alongside the coordinates.
+
+Because the result is stored rather than computed on demand, it is only recalculated when metadata extraction runs again for that asset.
+
+## When no place is nearby
+
+The GeoNames data Immich uses covers populated places with a population of 500 or more. Coordinates in the ocean, in wilderness, or in sparsely populated regions may have no such place within the search radius.
+
+In that case Immich falls back to matching the coordinates against country boundaries, which yields a **country only** — no state and no city. If even that fails, the asset keeps its coordinates but has no place names at all.
+
+The nearest-match rule also means a photo taken between towns is attributed to whichever qualifying place is closest, which is not necessarily the one you would name yourself.
+
+## What the place names are used for
+
+The stored values drive three things:
+
+- The location shown in the asset detail panel.
+- The **Locations** filter in [search](/user-guide/search-your-library), which matches on city, state, and country.
+- Grouping in the Places view.
+
+Coordinates themselves are what the map view uses, so the map still works for assets whose reverse geocoding produced nothing.
+
+<img src={require('./img/reverse-geocoding-mobile3.webp').default} width='33%' title='Reverse Geocoding' />
+<img src={require('./img/reverse-geocoding-mobile1.webp').default} width='33%' title='Reverse Geocoding' />
+<img src={require('./img/reverse-geocoding-mobile2.webp').default} width='33%' title='Reverse Geocoding' />
+
+## Keeping the data current
+
+The GeoNames dataset is imported into Postgres on minor version upgrades, so place names improve as the dataset does. Existing assets are not re-geocoded automatically — re-running metadata extraction is what applies newer data to assets that were already processed.
+
+Reverse geocoding can be turned off entirely in `Administration > Settings > Map & GPS Settings`. Coordinates continue to be extracted and stored when it is disabled; only the place-name lookup is skipped.

docs/docs/concepts/scaling.md

@@ -0,0 +1,49 @@
+# Scaling
+
+Immich is built to scale. Rather than a single process doing everything, the server is divided into independent **workers**, and most of the actual work is expressed as **jobs** that are queued and processed in the background. That division is what makes it possible to run Immich on one small machine or spread it across several.
+
+## Why the server is divided
+
+Serving the timeline and processing a video are very different workloads. One needs to answer quickly and constantly; the other is slow, CPU-hungry, and can be deferred. Running both in one undivided process means a transcoding backlog degrades browsing.
+
+Splitting them apart is what avoids that:
+
+- The `api` worker handles requests from the web and mobile apps.
+- The `microservices` worker runs the jobs — thumbnail generation, transcoding, machine learning, and everything else that happens after an upload.
+
+Because the two are separate processes coordinating only through Postgres and Redis, they do not have to run together. A single container runs both by default, but they can be split across containers, or across machines, with each set pointed at the same shared infrastructure.
+
+## Why work is expressed as jobs
+
+Treating background work as discrete, queued jobs has consequences beyond scheduling:
+
+- Work survives restarts, because the queue is durable rather than in-memory.
+- Progress is observable and jobs can be re-run, which is what makes it possible to reprocess a library after changing a setting.
+- Each kind of work gets its own concurrency limit, so an expensive job type cannot starve the rest.
+- Jobs can depend on each other, forming an order that is followed for every asset.
+
+## Running multiple instances
+
+The backend is designed so that multiple instances of its [workers](/reference/workers) can run in parallel. The only hard requirement is that every instance is connected to the same shared infrastructure: the same Postgres and Redis instances, and the same files mounted into the containers.
+
+This is useful when the hardware you have is uneven. You might have a gaming PC you want to use for transcoding and thumbnail generation, or a Kubernetes cluster of a few powerful servers you want to make use of.
+
+If you are scaling up only to get through background work faster, you can run additional containers with the API worker disabled so they do nothing but process jobs — see [Split workers across containers](/administration/split-workers-across-containers).
+
+:::info
+If you only have a single machine to run Immich on, scaling to multiple containers is unlikely to provide any benefit. An Immich container already runs multiple background tasks at once, and their [concurrency](/reference/jobs#concurrency) can be raised from the admin panel.
+:::
+
+How to actually scale across machines varies widely between environments and takes some knowledge to set up, so there is no single recipe. In some cases it is as easy as incrementing the replica count on a Kubernetes deployment; in others it means configuring network tunnels or NFS mounts.
+
+## Scaling down
+
+The same properties allow scaling in the other direction. All state lives in Postgres, Redis, and the filesystem, so stopping a running `immich-server` container carries no risk — for example, to free up a GPU for something else.
+
+As long as one API worker is running, Immich remains browsable, and jobs simply wait in their queues until a worker is available to process them.
+
+## Where to go next
+
+- [Jobs](/reference/jobs) — every job, what it does, and the order they run in
+- [Workers](/reference/workers) — the worker types and how to select them
+- [Split workers across containers](/administration/split-workers-across-containers)

docs/docs/concepts/self-hosted.md

@@ -0,0 +1,3 @@
+# Self-hosted
+
+Self-hosted has a few different meanings depending what you are referring to, but in the case of Immich it means running software on your own hardware, whether that be an old laptop, server, or rented VPS. Self-hosted is different from SaaS (software as a service) in that installation, upgrades,

docs/docs/concepts/sharing.md

@@ -0,0 +1,52 @@
+# Sharing
+
+Immich has three distinct ways to give someone access to assets, and they differ in who the recipient is, how much of the library they reach, and what they can do with it.
+
+| Mechanism       | Recipient                       | Scope                                     |
+| --------------- | ------------------------------- | ----------------------------------------- |
+| Shared album    | A user on the same instance     | The assets in that album                  |
+| Partner sharing | A user on the same instance     | The sharer's entire library               |
+| Public link     | Anyone with the URL, no account | The assets or album the link was made for |
+
+## Shared albums
+
+Albums can be shared between users on the same Immich instance. The shared users can view and add their own photos and videos to the shared album. When sharing an album, each user is assigned a permission — editor (read-write) or viewer (read-only).
+
+## Partner sharing
+
+Partner sharing allows you to share your _entire_ library with other users of your choice. They can then view your library and download the assets.
+
+Partner sharing includes:
+
+- Access to all non-archived and trashed photos and videos.
+- Access to all metadata, including GPS information.
+- Access to share assets via shared links, albums, etc.
+
+Partner sharing does _not_ include:
+
+- Already existing partner albums
+- If an asset is favorited
+- People and facial recognition data
+
+:::note
+
+- Partner sharing is one-way. To view your partner's assets, they must also share them with you.
+- Partner sharing may result in displaying duplicate assets on the main timeline, as duplicates are only detected on a per-user basis.
+
+:::
+
+## Public links
+
+You can create a public link to share a group of photos or videos, or an album, with anyone. The public link can be shared via email, social media, or any other method. There are a variety of options to customize the public link, such as setting an expiration date, password protection, and more. Public shared link is handy when you want to share a group of photos or videos with someone who doesn't have an Immich account and allow the shared user to upload their photos or videos to your account.
+
+The public shared link is generated with a random URL, which acts as as a secret to avoid the link being guessed by unwanted parties, for instance.
+
+A public link has no account behind it, so the URL itself is the credential. Immich generates a long random path for exactly this reason — the secret is the link, and anyone who obtains it has whatever access the link grants:
+
+```
+https://my.immich.app/share/JUckRMxlgpo7F9BpyqGk_cZEwDzaU_U5LU5_oNZp1ETIBa9dpQ0b5ghNm_22QVJfn3k
+```
+
+Because of that, links can be given an expiration date and a password, and the actions allowed through them can be restricted.
+
+To create and configure them, see [Share photos and albums](/user-guide/share-photos-and-albums).

docs/docs/concepts/versioning.md

@@ -0,0 +1,18 @@
+# Versioning
+
+Immich follows [semantic versioning](https://semver.org/), which tags releases in the format `<major>.<minor>.<patch>`. Breaking changes, including those to the API or to deployment, are intended to be limited to major version releases.
+
+## Pinning a version
+
+A Docker image can point at the current major version using a metatag, such as `:v3`. Metatags do not follow release candidates, so an instance pinned this way stays on stable releases within that major version.
+
+## Client and server compatibility
+
+The mobile app is typically compatible with the current and prior major version, but the server is only compatible with the matching major version. This asymmetry is why the recommended order is to upgrade all mobile clients **before** upgrading the server: a newer app can talk to the older server during the transition, while an older app cannot talk to a newer server.
+
+## What is and is not supported
+
+- Patches are not backported to earlier versions, so a fix is only available by moving to the most recent stable release.
+- Downgrading to an earlier version is not supported, even within the same minor version. Database migrations run on upgrade and are not reversible, which is also why a [backup](/concepts/backups) before a major upgrade matters.
+
+For the mechanics of upgrading, see [Upgrading](/install/upgrading).

docs/docs/developer/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Developer",
-  "position": 5
+  "position": 6
 }

docs/docs/developer/architecture.mdx

@@ -24,7 +24,7 @@ Immich has three main clients:
 3. CLI - Command-line utility for bulk upload
 
 :::info
-All three clients use [OpenAPI](/api.md) to auto-generate rest clients for easy integration. For more information about this process, see [OpenAPI](/api.md).
+All three clients use [OpenAPI](/developer/open-api) to auto-generate rest clients for easy integration. For more information about this process, see [OpenAPI](/developer/open-api).
 :::
 
 ### Mobile App
@@ -44,7 +44,7 @@ The web app is a [TypeScript](https://www.typescriptlang.org/) project that uses
 
 ### CLI
 
-The Immich CLI is an [npm](https://www.npmjs.com/) package that lets users control their Immich instance from the command line. It uses the API to perform various tasks, especially uploading assets. See the [CLI documentation](/features/command-line-interface.md) for more information.
+The Immich CLI is an [npm](https://www.npmjs.com/) package that lets users control their Immich instance from the command line. It uses the API to perform various tasks, especially uploading assets. See the [CLI documentation](/reference/immich-cli) for more information.
 
 ## Server
 
@@ -71,7 +71,7 @@ An incoming HTTP request is mapped to a controller (`src/controllers`). Controll
 
 ### Domain Transfer Objects (DTOs)
 
-The server uses [Domain Transfer Objects](https://en.wikipedia.org/wiki/Data_transfer_object) as public interfaces for the inputs (query, params, and body) and outputs (response) for each endpoint. DTOs translate to [OpenAPI](/api.md) schemas and control the generated code used by each client.
+The server uses [Domain Transfer Objects](https://en.wikipedia.org/wiki/Data_transfer_object) as public interfaces for the inputs (query, params, and body) and outputs (response) for each endpoint. DTOs translate to [OpenAPI](/developer/open-api) schemas and control the generated code used by each client.
 
 ### Background Jobs
 
@@ -83,11 +83,11 @@ Immich uses a [worker](https://github.com/immich-app/immich/blob/main/server/src
 - Smart Search
 - Facial Recognition
 - Storage Template Migration
-- Sidecar (see [XMP Sidecars](/features/xmp-sidecars.md))
+- Sidecar (see [XMP Sidecars](/reference/xmp-sidecars))
 - Background jobs (file deletion, user deletion)
 
 :::info
-This list closely matches what is available on the [Administration > Jobs](/administration/jobs-workers/#jobs) page, which provides some remote queue management capabilities.
+This list closely matches what is available on the [Administration > Jobs](/reference/jobs) page, which provides some remote queue management capabilities.
 :::
 
 ### Machine Learning

docs/docs/developer/open-api.md

@@ -0,0 +1,26 @@
+# OpenAPI
+
+Immich uses [OpenAPI](https://swagger.io/specification/) to describe its REST API, and generates the TypeScript and Dart client SDKs from that description. The published API documentation is at [api.immich.app](https://api.immich.app/); see [Immich API](/reference/immich-api) for the API itself.
+
+## How the specification is produced
+
+The specification is written to `immich-openapi-specs.json`, which is autogenerated by the server **when running in development mode**. Do not edit it by hand.
+
+Its contents are controlled by [`@nestjs/swagger`](https://docs.nestjs.com/openapi/types-and-parameters) decorators used or referenced by controller endpoints, so changes to the API surface are made there.
+
+## Regenerating the client SDKs
+
+When you add a new endpoint or modify an existing one, run the server in development mode and then run:
+
+```bash
+mise open-api
+```
+
+The generated SDKs are written to:
+
+| SDK        | Location                   |
+| ---------- | -------------------------- |
+| TypeScript | `packages/sdk/client`      |
+| Dart       | `mobile/generated/openapi` |
+
+Generation uses `openapi-generator-cli`, which can be installed by following its [installation instructions](https://openapi-generator.tech/docs/installation/).

docs/docs/developer/pr-checklist.md

@@ -74,7 +74,7 @@ Run all machine learning checks with `mise //machine-learning:checklist`
 
 ## OpenAPI
 
-The OpenAPI client libraries need to be regenerated whenever there are changes to the `immich-openapi-specs.json` file. Note that you should not modify this file directly as it is auto-generated. See [OpenAPI](/api.md) for more details.
+The OpenAPI client libraries need to be regenerated whenever there are changes to the `immich-openapi-specs.json` file. Note that you should not modify this file directly as it is auto-generated. See [OpenAPI](/developer/open-api) for more details.
 
 ## Database Migrations
 

docs/docs/features/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "Features",
-  "position": 3
-}

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

@@ -1,202 +0,0 @@
-# The Immich CLI
-
-Immich has a command line interface (CLI) that allows you to perform certain actions from the command line.
-
-## Features
-
-- Upload photos and videos to Immich
-- Check server version
-
-More features are planned for the future.
-
-:::tip Google Photos Takeout
-If you are looking to import your Google Photos takeout, we recommend this community maintained tool [immich-go](https://github.com/simulot/immich-go)
-:::
-
-## Requirements
-
-- Node.js 20 or above
-- Npm
-
-If you can't install node/npm, there is also a Docker version available below.
-
-## Installation (NPM)
-
-```bash
-npm i -g @immich/cli
-```
-
-NOTE: if you previously installed the legacy CLI, you will need to uninstall it first:
-
-```bash
-npm uninstall -g immich
-```
-
-## Installation (Docker)
-
-If npm is not available on your system you can try the Docker version
-
-```bash
-docker run -it -v "$(pwd)":/import:ro -e IMMICH_INSTANCE_URL=https://your-immich-instance/api -e IMMICH_API_KEY=your-api-key ghcr.io/immich-app/immich-cli:latest
-```
-
-Please modify the `IMMICH_INSTANCE_URL` and `IMMICH_API_KEY` environment variables as suitable. You can also use a Docker env file to store your sensitive API key.
-
-This `docker run` command will directly run the command `immich` inside the container. You can directly append the desired parameters (see under "usage") to the commandline like this:
-
-```bash
-docker run -it -v "$(pwd)":/import:ro -e IMMICH_INSTANCE_URL=https://your-immich-instance/api -e IMMICH_API_KEY=your-api-key ghcr.io/immich-app/immich-cli:latest upload -a -c 5 --recursive directory/
-```
-
-## Usage
-
-<details>
-<summary>Usage</summary>
-
-```
-$ immich
-Usage: immich [options] [command]
-
-Command line interface for Immich
-
-Options:
-  -V, --version                       output the version number
-  -d, --config-directory <directory>  Configuration directory where auth.yml will be stored (default: "~/.config/immich/", env:
-                                      IMMICH_CONFIG_DIR)
-  -u, --url [url]                     Immich server URL (env: IMMICH_INSTANCE_URL)
-  -k, --key [key]                     Immich API key (env: IMMICH_API_KEY)
-  -h, --help                          display help for command
-
-Commands:
-  login|login-key <url> <key>         Login using an API key
-  logout                              Remove stored credentials
-  server-info                         Display server information
-  upload [options] [paths...]         Upload assets
-  help [command]                      display help for command
-```
-
-</details>
-
-## Commands
-
-The upload command supports the following options:
-
-<details>
-<summary>Options</summary>
-
-```
-Usage: immich upload [paths...] [options]
-
-Upload assets
-
-Arguments:
-  paths                       One or more paths to assets to be uploaded
-
-Options:
-  -r, --recursive             Recursive (default: false, env: IMMICH_RECURSIVE)
-  -i, --ignore <pattern>      Pattern to ignore (env: IMMICH_IGNORE_PATHS)
-  -h, --skip-hash             Don't hash files before upload (default: false, env: IMMICH_SKIP_HASH)
-  -H, --include-hidden        Include hidden folders (default: false, env: IMMICH_INCLUDE_HIDDEN)
-  -a, --album                 Automatically create albums based on folder name (default: false, env: IMMICH_AUTO_CREATE_ALBUM)
-  -A, --album-name <name>     Add all assets to specified album (env: IMMICH_ALBUM_NAME)
-  --visibility <visibility>   Set the visibility of uploaded assets (choices: "archive", "timeline", "hidden", "locked", env: IMMICH_VISIBILITY)
-  -n, --dry-run               Don't perform any actions, just show what will be done (default: false, env: IMMICH_DRY_RUN)
-  -c, --concurrency <number>  Number of assets to upload at the same time (default: 4, env: IMMICH_UPLOAD_CONCURRENCY)
-  -j, --json-output           Output detailed information in json format (default: false, env: IMMICH_JSON_OUTPUT)
-  --delete                    Delete local assets after upload (env: IMMICH_DELETE_ASSETS)
-  --delete-duplicates         Delete local assets that are duplicates (already exist on server) (env: IMMICH_DELETE_DUPLICATES)
-  --no-progress               Hide progress bars (env: IMMICH_PROGRESS_BAR)
-  --watch                     Watch for changes and upload automatically (default: false, env: IMMICH_WATCH_CHANGES)
-  --help                      display help for command
-```
-
-</details>
-
-Note that the above options can read from environment variables as well.
-
-## Quick Start
-
-You begin by authenticating to your Immich server. For instance:
-
-```bash
-# immich login [url] [key]
-immich login http://192.168.1.216:2283/api HFEJ38DNSDUEG
-```
-
-This will store your credentials in a `auth.yml` file in the configuration directory which defaults to `~/.config/immich/`. The directory can be set with the `-d` option or the environment variable `IMMICH_CONFIG_DIR`. Please keep the file secure, either by performing the logout command after you are done, or deleting it manually.
-
-Once you are authenticated, you can upload assets to your Immich server.
-
-```bash
-immich upload file1.jpg file2.jpg
-```
-
-By default, subfolders are not included. To upload a directory including subfolder, use the --recursive option:
-
-```bash
-immich upload --recursive directory/
-```
-
-If you are unsure what will happen, you can use the `--dry-run` option to see what would happen without actually performing any actions.
-
-```bash
-immich upload --dry-run --recursive directory/
-```
-
-By default, the upload command will hash the files before uploading them. This is to avoid uploading the same file multiple times. If you are sure that the files are unique, you can skip this step by passing the `--skip-hash` option. Note that Immich always performs its own deduplication through hashing, so this is merely a performance consideration. If you have good bandwidth it might be faster to skip hashing.
-
-```bash
-immich upload --skip-hash --recursive directory/
-```
-
-You can automatically create albums based on the folder name by passing the `--album` option. This will automatically create albums for each uploaded asset based on the name of the folder they are in.
-
-```bash
-immich upload --album --recursive directory/
-```
-
-You can also choose to upload all assets to a specific album with the `--album-name` option.
-
-```bash
-immich upload --album-name "My summer holiday" --recursive directory/
-```
-
-It is possible to skip assets matching a glob pattern by passing the `--ignore` option. See [the library documentation](docs/features/libraries.md) on how to use glob patterns. You can add several exclusion patterns if needed.
-
-```bash
-immich upload --ignore **/Raw/** --recursive directory/
-```
-
-```bash
-immich upload --ignore **/Raw/** **/*.tif --recursive directory/
-```
-
-By default, hidden files are skipped. If you want to include hidden files, use the `--include-hidden` option:
-
-```bash
-immich upload --include-hidden --recursive directory/
-```
-
-You can set the visibility of uploaded assets to `archive`, `timeline`, `hidden`, or `locked` with the `--visibility` option:
-
-```bash
-immich upload --visibility archive --recursive directory/
-```
-
-You can use the `--json-output` option to get a json printed which includes
-three keys: `newFiles`, `duplicates` and `newAssets`. Due to some logging
-output you will need to strip the first three lines of output to get the json.
-For example to get a list of files that would be uploaded for further
-processing:
-
-```bash
-immich upload --dry-run --json-output . | tail -n +6 | jq .newFiles[]
-```
-
-### Obtain the API Key
-
-The API key can be obtained in the user setting panel on the web interface. You can also specify permissions for the key to limit its access.
-
-![Obtain Api Key](./img/obtain-api-key.webp)
-
-![Specify permissions for the key](./img/obtain-api-key-2.webp)

docs/docs/features/libraries.md

@@ -1,176 +0,0 @@
-# External Libraries
-
-:::info
-Currently an external library can only belong to a single user which is selected when the library is initially created.
-:::
-
-External libraries track assets stored in the filesystem outside of Immich. When the external library is scanned, Immich will load videos and photos from disk and create the corresponding assets. These assets will then be shown in the main timeline, and they will look and behave like any other asset, including viewing on the map, adding to albums, etc. Later, if a file is modified outside of Immich, you need to scan the library for the changes to show up.
-
-If an external asset is deleted from disk, Immich will move it to trash on rescan. To restore the asset, you need to restore the original file. After 30 days the file will be removed from trash, and any changes to metadata within Immich will be lost.
-
-:::caution
-
-If you add metadata to an external asset in any way (i.e. add it to an album or edit the description), that metadata is only stored inside Immich and will not be persisted to the external asset file. If you move an asset to another location within the library all such metadata will be lost upon rescan. This is because the asset is considered a new asset after the move. This is a known issue and will be fixed in a future release.
-
-:::
-
-:::caution
-
-Due to aggressive caching it can take some time for a refreshed asset to appear correctly in the web view. You need to clear the cache in your browser to see the changes. This is a known issue and will be fixed in a future release. In Chrome, you need to open the developer console with F12, then reload the page with F5, and finally right click on the reload button and select "Empty Cache and Hard Reload".
-
-:::
-
-### Import Paths
-
-External libraries use import paths to determine which files to scan. Each library can have multiple import paths so that files from different locations can be added to the same library. Import paths are scanned recursively, and if a file is in multiple import paths, it will only be added once. Each import file must be a readable directory that exists on the filesystem; the import path dialog will alert you of any paths that are not accessible.
-
-If the import paths are edited in a way that an external file is no longer in any import path, it will be removed from the library in the same way a deleted file would. If the file is moved back to an import path, it will be added again as if it was a new file.
-
-### Troubleshooting
-
-Sometimes, an external library will not scan correctly. This can happen if Immich can't access the files. Here are some things to check:
-
-- In the docker-compose file, are the volumes mounted correctly?
-- Are the volumes also mounted to any worker containers?
-- Are the import paths set correctly, and do they match the path set in docker-compose file?
-- Make sure you don't use symlinks in your import libraries, and that you aren't linking across docker mounts.
-- Are the permissions set correctly?
-- Make sure you are using forward slashes (`/`) and not backward slashes.
-
-To validate that Immich can reach your external library, start a shell inside the container. Run `docker exec -it immich_server bash` to a bash shell. If your import path is `/mnt/photos`, check it with `ls /mnt/photos`. If you are using a dedicated microservices container, make sure to add the same mount point and check for availability within the microservices container as well.
-
-### Exclusion Patterns
-
-By default, all files in the import paths will be added to the library. If there are files that should not be added, exclusion patterns can be used to exclude them. Exclusion patterns are glob patterns are matched against the full file path. If a file matches an exclusion pattern, it will not be added to the library. Exclusion patterns can be added in the Scan Settings page for each library.
-
-Some basic examples:
-
-- `**/*.tif` will exclude all files with the extension `.tif`
-- `**/hidden.jpg` will exclude all files named `hidden.jpg`
-- `**/Raw/**` will exclude all files in any directory named `Raw`
-- `**/*.{tif,jpg}` will exclude all files with the extension `.tif` or `.jpg`
-
-Note that `*` is a wildcard matching zero or more characters (i.e., withinin a filename or single directory name). `**` matches zero or more subdirectories, recursively. It also includes any/all files within a subdirectory, i.e., when used at the end of a pattern. For example, `**/exclude_me/**` will exclude all files in any directory named `exclude_me`, as well as all files in any subdirectories of `exclude_me`, recursively.
-
-Special characters such as @ should be escaped, for instance:
-
-- `**/\@eaDir/**` will exclude all files in any directory named `@eaDir`
-
-:::info
-Internally, Immich uses the [glob](https://www.npmjs.com/package/glob) package to process exclusion patterns, and sometimes those patterns are translated into [Postgres LIKE patterns](https://www.postgresql.org/docs/current/functions-matching.html). The intention is to support basic folder exclusions but we recommend against advanced usage since those can't reliably be translated to the Postgres syntax. Please refer to the [glob documentation](https://github.com/isaacs/node-glob#glob-primer) for a basic overview on glob patterns.
-:::
-
-### Automatic watching (EXPERIMENTAL)
-
-This feature is considered experimental and for advanced users only. If enabled, it will allow automatic watching of the filesystem which means new assets are automatically imported to Immich without needing to rescan.
-
-If your photos are on a network drive, automatic file watching likely won't work. In that case, you will have to rely on a [periodic library refresh](#set-custom-scan-interval) to pull in your changes.
-
-#### Troubleshooting
-
-If you encounter an `ENOSPC` error, you need to increase your file watcher limit. In sysctl, this key is called `fs.inotify.max_user_watches` and has a default value of 8192. Increase this number to a suitable value greater than the number of files you will be watching. Note that Immich has to watch all files in your import paths including any ignored files.
-
-```
-ERROR [LibraryService] Library watcher for library c69faf55-f96d-4aa0-b83b-2d80cbc27d98 encountered error: Error: ENOSPC: System limit for number of file watchers reached, watch '/media/photo.jpg'
-```
-
-In rare cases, the library watcher can hang, preventing Immich from starting up. In this case, disable the library watcher in the configuration file. If the watcher is enabled from within Immich, the app must be started without the microservices. Disable the microservices in the docker compose file, start Immich, disable the library watcher in the admin settings, close Immich, re-enable the microservices, and then Immich can be started normally.
-
-### Nightly job
-
-There is an automatic scan job that is scheduled to run once a day. Its schedule is configurable, see [Set Custom Scan Interval](#set-custom-scan-interval).
-
-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:
-
-- `/home/user/old-pics`: a folder containing childhood photos.
-- `/mnt/nas/christmas-trip`: photos from a christmas trip. The subfolder `/mnt/nas/christmas-trip/Raw` contains the raw files directly from the DSLR. We don't want to import the raw files to Immich
-- `/mnt/media/videos`: Videos from the same christmas trip.
-
-First, we need to plan how we want to organize the libraries. The christmas trip photos should belong to its own library since we want to exclude the raw files. The videos and old photos can be in the same library since we want to import all files. We could also add all three folders to the same library if there are no files matching the Raw exclusion pattern in the other folders.
-
-### Mount Docker Volumes
-
-The `immich-server` container will need access to the gallery. Modify your docker compose file as follows
-
-```diff title="docker-compose.yml"
-  immich-server:
-    volumes:
-      - ${UPLOAD_LOCATION}:/data
-+     - /mnt/nas/christmas-trip:/mnt/media/christmas-trip:ro
-+     - /home/user/old-pics:/mnt/media/old-pics:ro
-+     - /mnt/media/videos:/mnt/media/videos:ro
-+     - /mnt/media/videos2:/mnt/media/videos2 # WARNING: Immich will be able to delete the files in this folder, as it does not end with :ro
-+     - "C:/Users/user_name/Desktop/my media:/mnt/media/my-media:ro" # import path in Windows system.
-```
-
-:::tip
-The `ro` flag at the end only gives read-only access to the volumes.
-This will disallow the images from being deleted in the web UI, or adding metadata to the library ([XMP sidecars](/features/xmp-sidecars)).
-:::
-
-:::info
-_Remember to run `docker compose up -d` to register the changes. Make sure you can see the mounted path in the container._
-:::
-
-### Create A New Library
-
-These actions must be performed by the Immich administrator.
-
-- Click on your avatar in the upper right corner.
-- Click on `Administration -> External Libraries`.
-- Click on `Create Library`.
-- Select which user owns the library, this **can not** be changed later
-- You are now entering the library management page.
-- Click on `Add` in the `Folders` section.
-- Enter `/mnt/media/christmas-trip` then click Add.
-- Click on `Edit` Library and rename it to "Christmas Trip".
-
-NOTE: We have to use the `/mnt/media/christmas-trip` path and not the `/mnt/nas/christmas-trip` path since all paths have to be what the Docker containers see.
-
-Next, we'll add an exclusion pattern to filter out raw files.
-
-- Click on `Add` in the `Exclusion Patterns` section.
-- Enter `**/Raw/**` and click Add.
-- Click on `Scan`
-
-The christmas trip library will now be scanned in the background. In the meantime, let's add the videos and old photos to another library.
-
-- Go back to `Administration -> External Libraries`.
-- Click on `Create Library`.
-- Select which user owns the library,
-- You are now entering the library management page.
-- Click on `Add` in the `Folders` section.
-- Enter `/mnt/media/old-pics` then click Add
-- Click on `Add` in the `Folders` section.
-- Enter `/mnt/media/videos` then click Add
-- Click on `Scan`
-- Click on `Edit` Library and rename it to "Old videos and photos".
-
-Within seconds, the assets from the old-pics and videos folders should show up in the main timeline.
-
-### Folder view
-
-Folder view provides an additional view besides the timeline that is similar to a file explorer. It allows you to navigate through the folders and files in the library. This feature is handy for a highly curated and customized external library or a nicely configured storage template.
-
-You can enable this feature under [`Account Settings > Features > Folders`](https://my.immich.app/user-settings?isOpen=feature+folders)
-
-<img src={require('./img/folder-view-1.webp').default} width="100%" title='Folder-view' />
-
-### Set Custom Scan Interval
-
-:::note
-Only an admin can do this.
-:::
-
-You can define a custom interval for the trigger external library rescan under Administration -> Settings -> External Library.  
-You can set the scanning interval using the preset or cron format. For more information you can refer to [Crontab Guru](https://crontab.guru/).
-
-<img src={require('./img/library-custom-scan-interval.webp').default} width="75%" title='Set custom scan interval for external library' />

docs/docs/features/reverse-geocoding.md

@@ -1,15 +0,0 @@
-# Reverse Geocoding
-
-Immich supports local [Reverse Geocoding](https://en.wikipedia.org/wiki/Reverse_geocoding) using data from the [GeoNames](https://www.geonames.org/) geographical database. This data is loaded into the Postgres database on each minor version upgrade, allowing all queries to be run on your own server.
-
-## Extraction
-
-During Exif Extraction, assets with latitudes and longitudes are reverse geocoded to determine their City, State, and Country.
-
-## Usage
-
-Data from a reverse geocode is displayed in the image details, and used in [Smart Search](/features/searching.md).
-
-<img src={require('./img/reverse-geocoding-mobile3.webp').default} width='33%' title='Reverse Geocoding' />
-<img src={require('./img/reverse-geocoding-mobile1.webp').default} width='33%' title='Reverse Geocoding' />
-<img src={require('./img/reverse-geocoding-mobile2.webp').default} width='33%' title='Reverse Geocoding' />