.default} "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).
-
-.default} "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]
-```
diff --git a/docs/docs/administration/user-management.mdx b/docs/docs/administration/manage-users.mdx
similarity index 95%
rename from docs/docs/administration/user-management.mdx
rename to docs/docs/administration/manage-users.mdx
index 6d2b2f9062..8028c6ed85 100644
--- a/docs/docs/administration/user-management.mdx
+++ b/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
diff --git a/docs/docs/administration/migrate-to-vectorchord.md b/docs/docs/administration/migrate-to-vectorchord.md
new file mode 100644
index 0000000000..e7f50226ba
--- /dev/null
+++ b/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:
+
+
-
-
-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:
-
-Migration steps (automatic)
-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` - -
-` 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();
-ALTER TABLE face_search ALTER COLUMN embedding SET DATA TYPE vector(512);
-```
-
-5. Start Immich and let it create new indices using VectorChord
-
-
-
-### Migrating from pgvector
-
-Migration steps (manual)
-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 `
-
-
-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
diff --git a/docs/docs/administration/server-commands.md b/docs/docs/administration/run-a-server-command.md
similarity index 55%
rename from docs/docs/administration/server-commands.md
rename to docs/docs/administration/run-a-server-command.md
index 49bcf17700..d5908fe6fe 100644
--- a/docs/docs/administration/server-commands.md
+++ b/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 Migration steps
-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 - -.default} "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.
+
+.default} "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 |
+
+.default} "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.
diff --git a/docs/docs/administration/email-notification.mdx b/docs/docs/administration/set-up-email-notifications.mdx
similarity index 77%
rename from docs/docs/administration/email-notification.mdx
rename to docs/docs/administration/set-up-email-notifications.mdx
index 6273d03b08..8cf623cdf7 100644
--- a/docs/docs/administration/email-notification.mdx
+++ b/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
diff --git a/docs/docs/features/ml-hardware-acceleration.md b/docs/docs/administration/set-up-hardware-accelerated-machine-learning.md
similarity index 88%
rename from docs/docs/features/ml-hardware-acceleration.md
rename to docs/docs/administration/set-up-hardware-accelerated-machine-learning.md
index 5ad0bcd11f..59ac1a4bc5 100644
--- a/docs/docs/features/ml-hardware-acceleration.md
+++ b/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=`. 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
diff --git a/docs/docs/features/hardware-transcoding.md b/docs/docs/administration/set-up-hardware-transcoding.md
similarity index 80%
rename from docs/docs/features/hardware-transcoding.md
rename to docs/docs/administration/set-up-hardware-transcoding.md
index e68f6f6983..d09cc4473a 100644
--- a/docs/docs/features/hardware-transcoding.md
+++ b/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:
immich.json
-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 { diff --git a/docs/docs/administration/oauth.md b/docs/docs/administration/set-up-oauth-authentication.md similarity index 77% rename from docs/docs/administration/oauth.md rename to docs/docs/administration/set-up-oauth-authentication.md index 246b1be7fe..65febd97fb 100644 --- a/docs/docs/administration/oauth.md +++ b/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. diff --git a/docs/docs/administration/split-workers-across-containers.md b/docs/docs/administration/split-workers-across-containers.md new file mode 100644 index 0000000000..53c7b5cecf --- /dev/null +++ b/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' +``` diff --git a/docs/docs/administration/storage-template.mdx b/docs/docs/administration/storage-template.mdx deleted file mode 100644 index 9eb9d2b8fe..0000000000 --- a/docs/docs/administration/storage-template.mdx +++ /dev/null @@ -1,5 +0,0 @@ -import StorageTemplate from '/docs/partials/_storage-template.md'; - -# Storage Template - -.default} "Facial Recognition 1")
-
-Upon clicking on a person, a list of assets that contain their face will be shown.
-
-.default} "Facial Recognition 2")
-
-The asset detail view will also show the faces that are recognized in the asset.
-
-.default} "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.
-
-.default} "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.
diff --git a/docs/docs/features/img/android-backup-options.webp b/docs/docs/concepts/img/android-backup-options.webp
similarity index 100%
rename from docs/docs/features/img/android-backup-options.webp
rename to docs/docs/concepts/img/android-backup-options.webp
diff --git a/docs/docs/features/img/background-app-refresh.webp b/docs/docs/concepts/img/background-app-refresh.webp
similarity index 100%
rename from docs/docs/features/img/background-app-refresh.webp
rename to docs/docs/concepts/img/background-app-refresh.webp
diff --git a/docs/docs/features/img/backup-album-selection.webp b/docs/docs/concepts/img/backup-album-selection.webp
similarity index 100%
rename from docs/docs/features/img/backup-album-selection.webp
rename to docs/docs/concepts/img/backup-album-selection.webp
diff --git a/docs/docs/features/img/backup-album-sync.webp b/docs/docs/concepts/img/backup-album-sync.webp
similarity index 100%
rename from docs/docs/features/img/backup-album-sync.webp
rename to docs/docs/concepts/img/backup-album-sync.webp
diff --git a/docs/docs/features/img/backup-options.webp b/docs/docs/concepts/img/backup-options.webp
similarity index 100%
rename from docs/docs/features/img/backup-options.webp
rename to docs/docs/concepts/img/backup-options.webp
diff --git a/docs/docs/features/img/enable-backup-button.webp b/docs/docs/concepts/img/enable-backup-button.webp
similarity index 100%
rename from docs/docs/features/img/enable-backup-button.webp
rename to docs/docs/concepts/img/enable-backup-button.webp
diff --git a/docs/docs/features/img/reverse-geocoding-mobile1.webp b/docs/docs/concepts/img/reverse-geocoding-mobile1.webp
similarity index 100%
rename from docs/docs/features/img/reverse-geocoding-mobile1.webp
rename to docs/docs/concepts/img/reverse-geocoding-mobile1.webp
diff --git a/docs/docs/features/img/reverse-geocoding-mobile2.webp b/docs/docs/concepts/img/reverse-geocoding-mobile2.webp
similarity index 100%
rename from docs/docs/features/img/reverse-geocoding-mobile2.webp
rename to docs/docs/concepts/img/reverse-geocoding-mobile2.webp
diff --git a/docs/docs/features/img/reverse-geocoding-mobile3.webp b/docs/docs/concepts/img/reverse-geocoding-mobile3.webp
similarity index 100%
rename from docs/docs/features/img/reverse-geocoding-mobile3.webp
rename to docs/docs/concepts/img/reverse-geocoding-mobile3.webp
diff --git a/docs/docs/features/mobile-backup.md b/docs/docs/concepts/mobile-backup.md
similarity index 79%
rename from docs/docs/features/mobile-backup.md
rename to docs/docs/concepts/mobile-backup.md
index f3eb1a359c..a23452ee31 100644
--- a/docs/docs/features/mobile-backup.md
+++ b/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
diff --git a/docs/docs/concepts/monitoring.md b/docs/docs/concepts/monitoring.md
new file mode 100644
index 0000000000..8850a4fa64
--- /dev/null
+++ b/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).
diff --git a/docs/docs/concepts/open-source.md b/docs/docs/concepts/open-source.md
new file mode 100644
index 0000000000..08731a176d
--- /dev/null
+++ b/docs/docs/concepts/open-source.md
@@ -0,0 +1 @@
+# Open Source
diff --git a/docs/docs/guides/remote-access.md b/docs/docs/concepts/remote-access.md
similarity index 99%
rename from docs/docs/guides/remote-access.md
rename to docs/docs/concepts/remote-access.md
index 09e34c5107..69dc76ec22 100644
--- a/docs/docs/guides/remote-access.md
+++ b/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.
diff --git a/docs/docs/concepts/reverse-geocoding.md b/docs/docs/concepts/reverse-geocoding.md
new file mode 100644
index 0000000000..c4c4143123
--- /dev/null
+++ b/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.
+
+.default} "Reverse Geocoding")
+.default} "Reverse Geocoding")
+.default} "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.
diff --git a/docs/docs/concepts/scaling.md b/docs/docs/concepts/scaling.md
new file mode 100644
index 0000000000..1d42cbddcc
--- /dev/null
+++ b/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)
diff --git a/docs/docs/concepts/self-hosted.md b/docs/docs/concepts/self-hosted.md
new file mode 100644
index 0000000000..d7a84994df
--- /dev/null
+++ b/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,
diff --git a/docs/docs/concepts/sharing.md b/docs/docs/concepts/sharing.md
new file mode 100644
index 0000000000..cc1934982a
--- /dev/null
+++ b/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).
diff --git a/docs/docs/administration/system-integrity.md b/docs/docs/concepts/system-integrity.md
similarity index 100%
rename from docs/docs/administration/system-integrity.md
rename to docs/docs/concepts/system-integrity.md
diff --git a/docs/docs/concepts/versioning.md b/docs/docs/concepts/versioning.md
new file mode 100644
index 0000000000..c53e2ebdf7
--- /dev/null
+++ b/docs/docs/concepts/versioning.md
@@ -0,0 +1,18 @@
+# Versioning
+
+Immich follows [semantic versioning](https://semver.org/), which tags releases in the format `
- Configuration directory where auth.yml will be stored (default: "~/.config/immich/", env:
- IMMICH_CONFIG_DIR)
- -u, --url [url] Immich server URL (env: IMMICH_INSTANCE_URL)
- -k, --key [key] Immich API key (env: IMMICH_API_KEY)
- -h, --help display help for command
-
-Commands:
- login|login-key Login using an API key
- logout Remove stored credentials
- server-info Display server information
- upload [options] [paths...] Upload assets
- help [command] display help for command
-```
-
-
-
-## Commands
-
-The upload command supports the following options:
-
-Usage
- -``` -$ immich -Usage: immich [options] [command] - -Command line interface for Immich - -Options: - -V, --version output the version number - -d, --config-directory
- Pattern to ignore (env: IMMICH_IGNORE_PATHS)
- -h, --skip-hash Don't hash files before upload (default: false, env: IMMICH_SKIP_HASH)
- -H, --include-hidden Include hidden folders (default: false, env: IMMICH_INCLUDE_HIDDEN)
- -a, --album Automatically create albums based on folder name (default: false, env: IMMICH_AUTO_CREATE_ALBUM)
- -A, --album-name Add all assets to specified album (env: IMMICH_ALBUM_NAME)
- --visibility Set the visibility of uploaded assets (choices: "archive", "timeline", "hidden", "locked", env: IMMICH_VISIBILITY)
- -n, --dry-run Don't perform any actions, just show what will be done (default: false, env: IMMICH_DRY_RUN)
- -c, --concurrency Number of assets to upload at the same time (default: 4, env: IMMICH_UPLOAD_CONCURRENCY)
- -j, --json-output Output detailed information in json format (default: false, env: IMMICH_JSON_OUTPUT)
- --delete Delete local assets after upload (env: IMMICH_DELETE_ASSETS)
- --delete-duplicates Delete local assets that are duplicates (already exist on server) (env: IMMICH_DELETE_DUPLICATES)
- --no-progress Hide progress bars (env: IMMICH_PROGRESS_BAR)
- --watch Watch for changes and upload automatically (default: false, env: IMMICH_WATCH_CHANGES)
- --help display help for command
-```
-
-
-
-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.
-
-
-
-
diff --git a/docs/docs/features/img/backup-settings-access.webp b/docs/docs/features/img/backup-settings-access.webp
deleted file mode 100644
index 06243af799..0000000000
Binary files a/docs/docs/features/img/backup-settings-access.webp and /dev/null differ
diff --git a/docs/docs/features/img/me.webp b/docs/docs/features/img/me.webp
deleted file mode 100644
index a177086ec2..0000000000
Binary files a/docs/docs/features/img/me.webp and /dev/null differ
diff --git a/docs/docs/features/img/mobile-upload-open-photo.webp b/docs/docs/features/img/mobile-upload-open-photo.webp
deleted file mode 100644
index fafa4c9048..0000000000
Binary files a/docs/docs/features/img/mobile-upload-open-photo.webp and /dev/null differ
diff --git a/docs/docs/features/img/user-change-password.webp b/docs/docs/features/img/user-change-password.webp
deleted file mode 100644
index a5d36ea2d9..0000000000
Binary files a/docs/docs/features/img/user-change-password.webp and /dev/null differ
diff --git a/docs/docs/features/img/user-popup.webp b/docs/docs/features/img/user-popup.webp
deleted file mode 100644
index f3d3c08e5f..0000000000
Binary files a/docs/docs/features/img/user-popup.webp and /dev/null differ
diff --git a/docs/docs/features/img/user-profile.webp b/docs/docs/features/img/user-profile.webp
deleted file mode 100644
index bba9499557..0000000000
Binary files a/docs/docs/features/img/user-profile.webp and /dev/null differ
diff --git a/docs/docs/features/libraries.md b/docs/docs/features/libraries.md
deleted file mode 100644
index 62831ab089..0000000000
--- a/docs/docs/features/libraries.md
+++ /dev/null
@@ -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)
-
-Options
- -``` -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.default} "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/).
-
-.default} "Set custom scan interval for external library")
diff --git a/docs/docs/features/reverse-geocoding.md b/docs/docs/features/reverse-geocoding.md
deleted file mode 100644
index b1aee74a99..0000000000
--- a/docs/docs/features/reverse-geocoding.md
+++ /dev/null
@@ -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).
-
-
-
-
diff --git a/docs/docs/guides/_category_.json b/docs/docs/guides/_category_.json
deleted file mode 100644
index 6b51b67c73..0000000000
--- a/docs/docs/guides/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "Guides",
- "position": 6
-}
diff --git a/docs/docs/guides/assets/20231219_183007_add-new-server-option.png b/docs/docs/guides/assets/20231219_183007_add-new-server-option.png
deleted file mode 100644
index 934c8c792f..0000000000
Binary files a/docs/docs/guides/assets/20231219_183007_add-new-server-option.png and /dev/null differ
diff --git a/docs/docs/guides/external-library.md b/docs/docs/guides/external-library.md
deleted file mode 100644
index a1c8092732..0000000000
--- a/docs/docs/guides/external-library.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# External Library
-
-This guide walks you through adding an [External Library](/features/libraries).
-This guide assumes you are running Immich in Docker and that the files you wish to access are stored
-in a directory on the same machine.
-
-# Mount the directory into the containers.
-
-Edit `docker-compose.yml` to add one or more new mount points in the section `immich-server:` under `volumes:`.
-If you want Immich to be able to delete the images in the external library or add metadata ([XMP sidecars](/features/xmp-sidecars)), remove `:ro` from the end of the mount point.
-
-```diff
-immich-server:
- volumes:
- - ${UPLOAD_LOCATION}:/data
-+ - /home/user/photos1:/home/user/photos1:ro
-+ - /mnt/photos2:/mnt/photos2:ro # you can delete this line if you only have one mount point, or you can add more lines if you have more than two
-```
-
-Restart Immich by running `docker compose up -d`.
-
-# 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.
- .default} "Administration link")
-
-- Select the **External Libraries** tab and click the **Create Library** button
- .default} "Create Library button")
-
-- In the dialog, select which user should own the new library
- .default} "Library owner dialog")
-
-- You are now entering the library management page.
- .default} "Library management page")
-
-- Click `Add` in the Folder section to specify a path for scanning and enter **/home/user/photos1** as the path and click Add
- .default} "Add an import path")
-
-- Click the three-dots menu and select **Scan New Library Files**
- .default} "Scan New Library Files menu option")
-
-# Confirm stuff is happening
-
-- Click **Administration**
-
-
-- Select the **Jobs** tab
- .default} "Jobs tab")
-
-- You should see non-zero Active jobs for
- Library, Generate Thumbnails, and Extract Metadata.
diff --git a/docs/docs/guides/img/add-path-button.webp b/docs/docs/guides/img/add-path-button.webp
deleted file mode 100644
index 014999069f..0000000000
Binary files a/docs/docs/guides/img/add-path-button.webp and /dev/null differ
diff --git a/docs/docs/guides/img/add-path-field.webp b/docs/docs/guides/img/add-path-field.webp
deleted file mode 100644
index 6ac5a33e30..0000000000
Binary files a/docs/docs/guides/img/add-path-field.webp and /dev/null differ
diff --git a/docs/docs/guides/img/edit-import-paths.webp b/docs/docs/guides/img/edit-import-paths.webp
deleted file mode 100644
index 70cc1cf7cf..0000000000
Binary files a/docs/docs/guides/img/edit-import-paths.webp and /dev/null differ
diff --git a/docs/docs/guides/img/libraries-dropdown.webp b/docs/docs/guides/img/libraries-dropdown.webp
deleted file mode 100644
index fe9d1fcf47..0000000000
Binary files a/docs/docs/guides/img/libraries-dropdown.webp and /dev/null differ
diff --git a/docs/docs/guides/img/path-save.webp b/docs/docs/guides/img/path-save.webp
deleted file mode 100644
index df0256a3df..0000000000
Binary files a/docs/docs/guides/img/path-save.webp and /dev/null differ
diff --git a/docs/docs/guides/img/user-avatar.webp b/docs/docs/guides/img/user-avatar.webp
deleted file mode 100644
index 78a8fd9270..0000000000
Binary files a/docs/docs/guides/img/user-avatar.webp and /dev/null differ
diff --git a/docs/docs/guides/scaling-immich.md b/docs/docs/guides/scaling-immich.md
deleted file mode 100644
index a8d916ae2a..0000000000
--- a/docs/docs/guides/scaling-immich.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Scaling Immich
-
-Immich is built with modern deployment practices in mind, and the backend is designed to be able to run multiple instances in parallel. When doing this, the only requirement you need to be aware of is that every instance needs to be connected to the shared infrastructure. That means they should all have access to the same Postgres and Redis instances, and have the same files mounted into the containers.
-
-Scaling can be useful for many reasons. Maybe you have a gaming PC that you want to use for transcoding and thumbnail generation, or perhaps you run a Kubernetes cluster across a handful of powerful servers that you want to make use of.
-
-:::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 will run multiple background tasks at once, and you can increase their number from the admin panel.
-:::
-
-The details of how to scale across multiple machines will vary widely between different environments and require some knowledge to set up, and as such this guide gives no specific instructions. In some cases scaling up can be as easy as incrementing the amount of replicas on a Kubernetes deployment, in others it might need you to configure network tunnels or NFS mounts. The details are left as an exercise for the reader ;)
-
-## Workers
-
-By default, each running `immich-server` container comes with multiple internal workers. If you're scaling up only to handle more background tasks, you can choose to disable the worker responsible for the API. See [workers](../administration/jobs-workers.md) for more detail.
-
-## Scaling down
-
-In the same way you can scale up to multiple containers, you can also choose to scale down. All state is stored in Postgres, Redis, and the filesystem so there is no risk in stopping a running immich-server container, for example if you want to use your GPU to play some games. As long as there is an API worker running you will still be able to browse Immich, and jobs will wait to be processed until there is a worker available for them.
diff --git a/docs/docs/guides/smtp-gmail.md b/docs/docs/guides/smtp-gmail.md
deleted file mode 100644
index 58c598c308..0000000000
--- a/docs/docs/guides/smtp-gmail.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# SMTP settings using Gmail
-
-This guide walks you through how to get the information you need to set up your Immich instance to send emails using Gmail's SMTP server.
-
-## Create an app password
-
-From your Google account settings
-
-- Add [2-Step Verification](https://support.google.com/accounts/answer/185839) to your Google account (Required)
-- [Create an app password](https://myaccount.google.com/apppasswords).
-
-At the end of creating your app passwords, a password will be displayed; save it, it will be used for the password field when setting up the SMTP server in Immich.
-
-
-
-## Entering the SMTP credential in Immich
-
-Entering your credential in Immich's email notification settings at `Administration -> Settings -> Notification Settings`
-
-
diff --git a/docs/docs/guides/smtp-microsoft365.md b/docs/docs/guides/smtp-microsoft365.md
deleted file mode 100644
index 2ba78a4e18..0000000000
--- a/docs/docs/guides/smtp-microsoft365.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# SMTP settings using Microsoft 365
-
-This guide walks you through how to get the information you need to set up your Immich instance to send emails using Microsoft's SMTP server.
-
-## Create an app password
-
-You will need to generate an app password to use your Microsoft email in Immich. Depending on if you have a personal or business account, you can use https://go.microsoft.com/fwlink/?linkid=2274139 or https://myaccount.microsoft.com/securtiy-info respectively.
-
-## Entering the SMTP credential in Immich
-
-Entering your credential in Immich's email notification settings at `Administration -> Settings -> Notification Settings`
-
-Host: smtp-mail.outlook.com
-Port: 587
-username: your mail address
-Password: app password you created earlier
-SMTPS: set it to disabled
-
-
diff --git a/docs/docs/overview/help.md b/docs/docs/help-me.md
similarity index 95%
rename from docs/docs/overview/help.md
rename to docs/docs/help-me.md
index e6523547fa..3642c75412 100644
--- a/docs/docs/overview/help.md
+++ b/docs/docs/help-me.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 6
+sidebar_position: 9
---
# Help Me!
diff --git a/docs/docs/install/all-in-one.md b/docs/docs/install/all-in-one.md
index 4d37952179..8df06981f7 100644
--- a/docs/docs/install/all-in-one.md
+++ b/docs/docs/install/all-in-one.md
@@ -2,13 +2,15 @@
sidebar_position: 70
---
-# All-In-One [Community]
+import CommunityDisclaimer from '@site/src/components/community-disclaimer';
-:::note
-This is a community contribution and not officially supported by the Immich team, but included here for convenience.
+# Install with All-in-One
-**Please report issues to the corresponding [Github Repository][github].**
-:::
+.default} "Job Queues tab")
+
---
## Review the database backup and restore process
Immich has built-in database backups. You can refer to the
-[database backup](/administration/backup-and-restore) for more information.
+[database backup](/administration/back-up-and-restore) for more information.
:::danger
The database only contains metadata and user information. You must setup manual backups of the images and videos stored in `UPLOAD_LOCATION`.
@@ -82,12 +80,12 @@ The database only contains metadata and user information. You must setup manual
## Where to go from here?
-You may decide you'd like to install the server a different way; the Install category on the left menu provides many options.
+You may decide you'd like to install the server a different way; [Install and upgrade](/install/) lists every method.
You may decide you'd like to add the _rest_ of your photos from Google Photos, even those not on your mobile device, via Google Takeout. You can use [immich-go](https://github.com/simulot/immich-go) for this.
-You may want to [upload photos from your own archive](/features/command-line-interface).
+You may want to [upload photos from your own archive](/user-guide/upload-media-with-the-cli).
-You may want to incorporate a pre-existing archive of photos from an [External Library](/features/libraries); there's a [guide](/guides/external-library) for that.
+You may want to incorporate a pre-existing archive of photos from an [External Library](/concepts/external-libraries); there's a [guide](/administration/add-an-external-library) for that.
-You may want your mobile device to [back photos up to your server automatically](/features/mobile-backup).
+You may want your mobile device to [back photos up to your server automatically](/concepts/mobile-backup).
diff --git a/docs/docs/install/requirements.md b/docs/docs/install/requirements.md
deleted file mode 100644
index 155aa1ae75..0000000000
--- a/docs/docs/install/requirements.md
+++ /dev/null
@@ -1,82 +0,0 @@
----
-sidebar_position: 10
----
-
-# Requirements
-
-Hardware and software requirements for Immich:
-
-## Hardware
-
-- **OS**: Recommended Linux or \*nix 64-bit operating system (Ubuntu, Debian, etc).
- - Non-Linux OSes tend to provide a poor Docker experience and are strongly discouraged.
- Our ability to assist with setup or troubleshooting on non-Linux OSes will be severely reduced.
- If you still want to try to use a non-Linux OS, you can set it up as follows:
- - Windows: [Docker Desktop on Windows](https://docs.docker.com/desktop/install/windows-install/) or [WSL 2](https://docs.docker.com/desktop/wsl/).
- - macOS: [Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/).
- - Immich runs well in a virtualized environment when running in a full virtual machine.
- The use of Docker in LXC containers is [not recommended](https://pve.proxmox.com/wiki/Linux_Container), but may be possible for advanced users.
- If you have issues, we recommend that you switch to a supported VM deployment.
-- **RAM**: Minimum 6GB, recommended 8GB.
-- **CPU**: Minimum 2 cores, recommended 4 cores.
- - Immich runs on the `amd64` and `arm64` platforms.
- Since `v3`, the machine learning container on `amd64` requires the `>= x86-64-v2` [microarchitecture level](https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels).
- Most CPUs released since ~2012 support this microarchitecture.
- If you are using a virtual machine, ensure you have selected a [supported microarchitecture](https://pve.proxmox.com/pve-docs/chapter-qm.html#_qemu_cpu_types).
- If you are unable to support this instruction set, the last version to support `x86-64-v1` is `v2.7.5`.
- Note that this release is no longer supported, and you must run a matching `immich-server` version.
-- **Storage**: Recommended Unix-compatible filesystem (EXT4, ZFS, APFS, etc.) with support for user/group ownership and permissions.
- - The generation of thumbnails and transcoded video can increase the size of the photo library by 10-20% on average.
-
-:::note RAM requirements
-For a smooth experience, especially during asset upload, Immich requires at least 6GB of RAM.
-For systems with only 4GB of RAM, Immich can be run with machine learning features disabled.
-:::
-
-:::tip Postgres setup
-Good performance and a stable connection to the Postgres database is critical to a smooth Immich experience.
-The Postgres database files are typically between 1-3 GB in size.
-For this reason, the Postgres database (`DB_DATA_LOCATION`) should ideally use local SSD storage, and never a network share of any kind.
-Additionally, if Docker resource limits are used, the Postgres database requires at least 2GB of RAM.
-Windows users may run into issues with non-Unix-compatible filesystems, see below for more details.
-:::
-
-## Software
-
-Immich requires [**Docker**](https://docs.docker.com/get-started/get-docker/) with the **Docker Compose plugin**:
-
-- **Docker Engine**: This CLI variant is designed for Linux servers (or Windows via WSL2).
-- **Docker Desktop**: This GUI variant is **not recommended** for Linux, but is available for Windows or macOS.
-
-The Compose plugin will be installed by both Docker Engine and Desktop by following the linked installation guides; it can also be [separately installed](https://docs.docker.com/compose/install/).
-
-:::note
-Immich requires the command `docker compose`; the similarly named `docker-compose` is [deprecated](https://docs.docker.com/retired/#docker-compose-v1-replaced-by-compose-v2) and is no longer supported by Immich.
-:::
-
-### Special requirements for Windows users
-
-
-
diff --git a/docs/docs/install/script.md b/docs/docs/install/script.md
index ce05dc82d9..15ca83f4d3 100644
--- a/docs/docs/install/script.md
+++ b/docs/docs/install/script.md
@@ -2,15 +2,15 @@
sidebar_position: 20
---
-# Install script [Experimental]
+# Install with the install script [Experimental]
:::caution
-This method is experimental and not currently recommended for production use. For production, please refer to installing with [Docker Compose](/install/docker-compose.mdx).
+This method is experimental and not currently recommended for production use. For production, please refer to installing with [Docker Compose](/install/docker-compose).
:::
## Requirements
-Follow the [requirements page](/install/requirements) to get started.
+Follow the [requirements page](/reference/requirements) to get started.
The install script only supports Linux operating systems and requires Docker to be already installed on the system.
@@ -32,5 +32,5 @@ The web application and mobile app will be available at `http://Database storage on Windows systems
- -The Immich Postgres database (`DB_DATA_LOCATION`) must be located on a filesystem that supports user/group -ownership and permissions (EXT2/3/4, ZFS, APFS, BTRFS, XFS, etc.). It will not work on any filesystem formatted in NTFS or ex/FAT/32. -It will not work in WSL (Windows Subsystem for Linux) when using a mounted host directory (commonly under `/mnt`). -If this is an issue, you can change the bind mount to a Docker volume instead as follows: - -Make the following change to `.env`: - -```diff -- DB_DATA_LOCATION=./postgres -+ DB_DATA_LOCATION=pgdata -``` - -Add the following line to the bottom of `docker-compose.yml`: - -```diff -volumes: - model-cache: -+ pgdata: -``` - -Updating Immich using Container Manager
diff --git a/docs/docs/install/truenas.md b/docs/docs/install/truenas.md index 9135b72fe6..aa8b8f4cf6 100644 --- a/docs/docs/install/truenas.md +++ b/docs/docs/install/truenas.md @@ -2,18 +2,17 @@ sidebar_position: 80 --- +import CommunityDisclaimer from '@site/src/components/community-disclaimer'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# TrueNAS [Community] +# Install on TrueNAS -:::note -This is a community contribution and not officially supported by the Immich team, but included here for convenience. +.default} "Advanced search filters")
-
-### Full path or folder
-
-Use this mode when you know a folder name or part of the original asset path.
-
-Example: for /John/Projects/3D_Printing/2026-07-01/IMG_0001.jpg, searches like Projects, 3D, Printing, or 2026 match the asset.
-
-## Configuration
-
-Navigating to `Administration > Settings > Machine Learning Settings > Smart Search` will show the options available.
-
-### CLIP models
+## Choosing a model
The default search model is fast, but there are many other options that can provide better search results. The tradeoff of using these models is that they're slower and/or use more memory (both when indexing images with background Smart Search jobs and when searching).
@@ -58,17 +21,7 @@ If your users will only search in English, then the [CLIP][huggingface-clip] sec
For more details, check the tables below to see how they compare in memory usage, speed and quality by language.
-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.
+## Model comparison
Please note that memory and execution time values are only _estimates_: actual usage will be different depending on many factors. As such, it's mainly intended as a way to compare the relative tradeoffs of each model.
@@ -1208,5 +1161,3 @@ Feel free to make a feature request if there's a model you want to use that we d
[huggingface-clip]: https://huggingface.co/collections/immich-app/clip-654eaefb077425890874cd07
[huggingface-multilingual-clip]: https://huggingface.co/collections/immich-app/multilingual-clip-654eb08c2382f591eeb8c2a7
-[smart-search-settings]: https://my.immich.app/admin/system-settings?isOpen=machine-learning+smart-search
-[job-status-page]: https://my.immich.app/admin/queues
diff --git a/docs/docs/install/config-file.md b/docs/docs/reference/config-file.md
similarity index 62%
rename from docs/docs/install/config-file.md
rename to docs/docs/reference/config-file.md
index 5c34acdd9d..513d7b6533 100644
--- a/docs/docs/install/config-file.md
+++ b/docs/docs/reference/config-file.md
@@ -2,19 +2,50 @@
sidebar_position: 100
---
-# Config File
+# Config file
-A config file can be provided as an alternative to the UI configuration.
+Immich's system configuration — everything under `Administration > Settings` — is normally stored in the database and edited from the web UI. When the `IMMICH_CONFIG_FILE` environment variable is set, Immich reads that configuration from a file instead.
-:::note Interaction with the web UI
-While the config file does not need to include all keys from the below example, specifying `IMMICH_CONFIG_FILE` will disable the ability to edit other properties from the Immich web UI.
-:::
+For a walkthrough of setting one up, see [Use a config file](/administration/use-a-config-file).
-### Step 1 - Create a new config file
+## Format
-In JSON format, create a new config file (e.g. `immich-config.json`) and put it in a location mounted in the container that can be accessed by Immich.
-YAML-formatted config files are also supported.
-The default configuration looks like this:
+The file may be written as JSON or YAML. It is parsed as YAML, and JSON is a subset of YAML, so both are accepted regardless of the file extension.
+
+## Location
+
+`IMMICH_CONFIG_FILE` holds the path to the file **as seen from inside the container**, not a path on the host. Every container that runs Immich reads its own configuration, so a deployment with separate `microservices` workers needs the file mounted into those containers at the same path.
+
+See [Environment Variables](/reference/environment-variables) for the variable itself.
+
+## How values are resolved
+
+- **Partial files are valid.** Any key absent from the file takes its default value, so the file only needs to contain the settings that differ from the defaults.
+- **The database configuration is ignored.** While `IMMICH_CONFIG_FILE` is set, the file is the only source of system configuration; it is not merged with settings previously saved through the web UI. Those saved settings are left untouched in the database and apply again if the variable is removed.
+- **Unknown keys are ignored.** They are reported as a warning in the server log.
+- **Changes are not picked up automatically.** The configuration is read and cached when Immich loads it. Restart the containers to apply an edited file.
+
+## Failure behavior
+
+A config file is validated more strictly than the database configuration, because a mistake in it cannot be corrected from the UI:
+
+| Condition | Result |
+| ------------------------------------------------ | ------------------------------------------------------------- |
+| File missing, unreadable, or not valid YAML/JSON | The error is logged and configuration loading fails |
+| A value fails schema validation | The error is logged with the offending key, and loading fails |
+| An unknown key is present | Logged as a warning; the key is ignored |
+
+Without a config file, schema validation failures are logged but non-fatal.
+
+## Effect on the web UI and API
+
+- The settings in `Administration > Settings` are shown read-only.
+- Requests to update the system configuration are rejected with `400 Cannot update configuration while IMMICH_CONFIG_FILE is in use`.
+- The server reports `configFile: true` in its feature flags, and admin onboarding is treated as complete.
+
+## Default configuration
+
+The full set of keys and their default values:
immich-config.json
@@ -246,30 +277,3 @@ The default configuration looks like this: ```![]({require("./img/admin-jobs.webp").default} "Admin jobs")
+
+## Extract metadata
+
+Reads metadata from each asset — date, GPS, camera, dimensions, faces, and tags. See [EXIF tags](/reference/exif-tags) for every tag involved and which feature each one drives.
+
+**Actions:** All, Missing
+
+## Generate Thumbnails
+
+Generates large, small, and blurred thumbnails for each asset, as well as a thumbnail for each person.
+
+**Actions:** All, Missing
+
+## Transcode videos
+
+Transcodes videos for wider compatibility with browsers and devices, according to the transcode policy in the video transcoding settings. The original file is never replaced.
+
+**Actions:** All, Missing
+
+## Smart Search
+
+Runs the [CLIP model](/reference/clip-models) over each asset to produce the embeddings that power contextual search.
+
+**Actions:** All, Missing — requires machine learning to be enabled
+
+## Face detection
+
+Detects the faces in assets using machine learning. For videos, only the thumbnail is considered. Detected faces are queued for Facial Recognition once detection completes.
+
+**Actions:** Reset, Refresh, Missing — requires machine learning to be enabled
+
+## Facial Recognition
+
+Groups detected faces into people. This step runs after Face detection is complete. See [Facial recognition](/concepts/facial-recognition) for how the clustering works.
+
+**Actions:** Reset, Missing — requires machine learning to be enabled
+
+## OCR
+
+Uses machine learning to recognize text in images so that it can be searched.
+
+**Actions:** All, Missing — requires machine learning to be enabled
+
+## Duplicate Detection
+
+Detects visually similar assets. Relies on the embeddings produced by Smart Search. See [Duplicate detection](/concepts/duplicate-detection).
+
+**Actions:** All, Missing — requires machine learning to be enabled
+
+## Sidecar metadata
+
+Discovers and synchronizes [XMP sidecar](/reference/xmp-sidecars) files on the filesystem. The same queue runs Sidecar Write, which writes edited metadata back out to the sidecar.
+
+**Actions:** Sync, Discover
+
+## External Libraries
+
+Scans [external libraries](/concepts/external-libraries) for new and changed assets, and cleans up libraries that are stuck in deletion.
+
+**Actions:** Rescan
+
+## Storage template migration
+
+Moves existing files to match the current [storage template](/administration/use-the-storage-template). Only needed after changing the template; new assets are placed correctly on upload.
+
+**Actions:** Start
+
+## Migration
+
+Moves thumbnails for assets and faces to the latest folder structure.
+
+**Actions:** Start
+
+## Processing order
+
+Jobs are queued in a fixed order, with later jobs depending on the output of earlier ones. Uploading an asset runs the following:
+
+```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]
+```
+
+Thumbnail generation is the fan-out point: Smart Search, Face detection, OCR, and video transcoding all wait for it, because they operate on the generated preview rather than the original. Duplicate Detection then depends on Smart Search, and Facial Recognition on Face detection.
+
+## Running a job manually
+
+Each queue offers some combination of the following actions:
+
+| Action | Effect |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| **All** | Queues every asset, reprocessing assets that already have a result. |
+| **Missing** | Queues only assets that have not been processed yet. |
+| **Refresh** | Reprocesses all assets without discarding existing data first. |
+| **Reset** | Clears existing results and reprocesses everything. |
+| **Sync** / **Discover** | Synchronizes metadata from known sidecar files, or discovers new sidecar files. |
+| **Rescan** | Rescans external libraries for changes. |
+| **Start** | Begins a one-off migration. |
+
+Resetting face data is destructive — it discards all detected faces, and people have to be rebuilt by Facial Recognition.
+
+## Concurrency
+
+Each job's concurrency is set independently at `Administration > Settings > Job Settings`, and the defaults are listed under `job` in the [config file reference](/reference/config-file#default-configuration). Video transcoding and the machine learning jobs are the most resource-intensive, which is why their defaults are lower than the rest.
+
+## Jobs configured elsewhere
+
+Some scheduled work does not appear on the Job Queues page:
+
+- **Nightly tasks** — memory generation, database cleanup, missing thumbnails, and face clustering. These run every night at midnight by default; the schedule and which tasks run are set under [Nightly Tasks Settings](https://my.immich.app/admin/system-settings?isOpen=nightly-tasks).
+
+ ![]({require("./img/admin-nightly-tasks.webp").default} "Admin nightly tasks")
+
+- **Database backups** — see [Backups](/concepts/backups).
+- **External library scanning** — the periodic scan interval is configured per library, not on the queue page.
+- **Integrity checks** — see [System Integrity](/concepts/system-integrity).
diff --git a/docs/docs/reference/logging.md b/docs/docs/reference/logging.md
new file mode 100644
index 0000000000..4f637e0fef
--- /dev/null
+++ b/docs/docs/reference/logging.md
@@ -0,0 +1,59 @@
+# Logging
+
+Immich logs to standard output, so logs are read with `docker logs` — see [Inspect containers and logs](/administration/inspect-containers-and-logs). Three environment variables control what is logged and how it is formatted.
+
+## Log level
+
+`IMMICH_LOG_LEVEL` sets the minimum severity that is logged. The levels, from most to least verbose:
+
+| Level | Notes |
+| --------- | ------------------------------------------------- |
+| `verbose` | Very noisy; useful when diagnosing a specific job |
+| `debug` | |
+| `log` | The default, commonly known as `info` |
+| `warn` | |
+| `error` | |
+| `fatal` | Only errors that stop the server |
+
+The level can also be set from the web UI under `Administration > Settings > Logging`. When `IMMICH_LOG_LEVEL` is set, it takes precedence and the setting cannot be changed from the UI.
+
+## Log format
+
+`IMMICH_LOG_FORMAT` selects the output format.
+
+| Value | Output |
+| --------- | ----------------------------------------------- |
+| `console` | The default. Human-readable, one line per entry |
+| `json` | One JSON object per line, for log aggregation |
+
+Use `json` for deployments that ship logs to a system such as Grafana Loki, the ELK stack, Datadog, or Splunk.
+
+### 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"}
+```
+
+Each object contains:
+
+| Field | Meaning |
+| ----------- | --------------------------------------------- |
+| `level` | Log level of the entry |
+| `pid` | Process ID that emitted it |
+| `timestamp` | Unix timestamp in milliseconds |
+| `message` | The log message |
+| `context` | Service or component that generated the entry |
+
+## Color
+
+Console output is color-coded by default. Setting `NO_COLOR` to any non-empty value disables it, following the [NO_COLOR convention](https://no-color.org/).
+
+| Variable | Effect |
+| ---------- | ------------------------------------------------------- |
+| `NO_COLOR` | Any non-empty value disables color-coded console output |
+
+This is worth setting when logs are captured to a file or piped into a tool that does not interpret ANSI escape codes, since the escape sequences would otherwise appear as literal characters. It has no effect on `json` output, which is never colorized.
+
+See [Environment Variables](/reference/environment-variables#general) for these variables alongside the rest, and [Monitor Immich](/administration/monitor-immich) for wiring logs into a monitoring stack.
diff --git a/docs/docs/reference/oauth-settings.md b/docs/docs/reference/oauth-settings.md
new file mode 100644
index 0000000000..ac96ff540b
--- /dev/null
+++ b/docs/docs/reference/oauth-settings.md
@@ -0,0 +1,41 @@
+# OAuth settings
+
+The settings below are configured on the web at `Administration > Settings > Authentication`. For the steps to register a client application with a provider and turn OAuth on, see [Set up OAuth authentication](/administration/set-up-oauth-authentication).
+
+| 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](/administration/set-up-oauth-authentication#auto-launch) | boolean | false | When true, will skip the login page and automatically start the OAuth login process |
+| [Mobile Redirect URI Override](/administration/set-up-oauth-authentication#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.
+
+:::
+
+:::note Claim options [1]
+Claims are only used on user creation and are not synchronized after that.
+:::
+
+The Issuer URL should return a valid JSON document, for example:
+
+- `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 is added automatically during discovery.
diff --git a/docs/docs/reference/requirements.md b/docs/docs/reference/requirements.md
new file mode 100644
index 0000000000..a823d2165d
--- /dev/null
+++ b/docs/docs/reference/requirements.md
@@ -0,0 +1,90 @@
+---
+sidebar_position: 10
+---
+
+# Requirements
+
+This page lists the software and hardware requirements for running Immich.
+
+## Software
+
+Immich is distributed as a set of Docker images. Running them requires [Docker](/reference/docker) with the [Docker Compose](https://docs.docker.com/compose/) plugin.
+
+:::info
+`docker compose` and `docker-compose` are two different distributions of Docker Compose, with the latter being [deprecated](https://docs.docker.com/retired/#docker-compose-v1-replaced-by-compose-v2) and no longer supported. Make sure that you are installing and using `docker compose`.
+:::
+
+### Special requirements for Windows users
+
+
+
+
+## Hardware
+
+### OS
+
+A Linux or \*nix 64-bit operating system (Ubuntu, Debian, etc.) is recommended.
+
+Non-Linux operating systems tend to provide a poor Docker experience and are strongly discouraged. Our ability to assist with setup or troubleshooting on non-Linux operating systems will be severely reduced. If you still want to use one:
+
+- Windows: [Docker Desktop on Windows](https://docs.docker.com/desktop/install/windows-install/) or [WSL 2](https://docs.docker.com/desktop/wsl/).
+- macOS: [Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/).
+
+Immich runs well in a virtualized environment when running in a full virtual machine. The use of Docker in LXC containers is [not recommended](https://pve.proxmox.com/wiki/Linux_Container), but may be possible for advanced users. If you have issues, we recommend that you switch to a supported VM deployment.
+
+Windows users should also review [special requirements for Windows users](#special-requirements-for-windows-users).
+
+### RAM
+
+Minimum 6GB, recommended 8GB.
+
+For a smooth experience, especially during asset upload, Immich requires at least 6GB of RAM. For systems with only 4GB of RAM, Immich can be run with machine learning features disabled.
+
+If Docker resource limits are used, the Postgres database requires at least 2GB of RAM on its own.
+
+### CPU
+
+Minimum 2 cores, recommended 4 cores.
+
+Immich runs on the `amd64` and `arm64` platforms. Since `v3`, the machine learning container on `amd64` requires the `>= x86-64-v2` [microarchitecture level](https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels). Most CPUs released since ~2012 support this microarchitecture. If you are using a virtual machine, ensure you have selected a [supported microarchitecture](https://pve.proxmox.com/pve-docs/chapter-qm.html#_qemu_cpu_types).
+
+If you are unable to support this instruction set, the last version to support `x86-64-v1` is `v2.7.5`. Note that this release is no longer supported, and you must run a matching `immich-server` version.
+
+### Storage
+
+A Unix-compatible filesystem (EXT4, ZFS, APFS, etc.) with support for user/group ownership and permissions is recommended.
+
+The generation of thumbnails and transcoded video can increase the size of the photo library by 10-20% on average. See [Storage locations](/reference/storage-locations) for what Immich writes where.
+
+Good performance and a stable connection to the Postgres database is critical to a smooth Immich experience. The Postgres database files are typically between 1-3 GB in size. For this reason, the Postgres database (`DB_DATA_LOCATION`) should ideally use local SSD storage, and never a network share of any kind.
+
+## Database
+
+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`.
diff --git a/docs/docs/reference/reverse-proxy-requirements.md b/docs/docs/reference/reverse-proxy-requirements.md
new file mode 100644
index 0000000000..7657e6483d
--- /dev/null
+++ b/docs/docs/reference/reverse-proxy-requirements.md
@@ -0,0 +1,32 @@
+# Reverse proxy requirements
+
+A custom reverse proxy can sit in front of Immich to handle TLS termination, load balancing, or other advanced features. Any proxy between Immich and the user must meet the requirements below. For configurations that satisfy them, see [Set up a reverse proxy](/administration/set-up-a-reverse-proxy).
+
+## Headers
+
+All headers must be forwarded, and these must be set to their appropriate values:
+
+| Header | Value |
+| ------------------- | ------------------------------------------- |
+| `Host` | The front-facing host |
+| `X-Real-IP` | The client address |
+| `X-Forwarded-Proto` | The scheme the client used (`http`/`https`) |
+| `X-Forwarded-For` | The client address chain |
+
+WebSocket upgrades must also be passed through.
+
+## Upload size
+
+The proxy must allow uploads large enough for the assets being sent. A body-size limit lower than the largest asset will fail uploads.
+
+## Timeouts
+
+Response timeouts need to be long enough for large uploads. A default of 60 seconds is too low and causes video uploads to stop after a minute (error code 499).
+
+## Path
+
+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.
+
+## Let's Encrypt http-01
+
+If the reverse proxy uses the [Let's Encrypt](https://letsencrypt.org/) [http-01 challenge](https://letsencrypt.org/docs/challenge-types/#http-01-challenge), verify that the Immich well-known endpoint (`/.well-known/immich`) is routed to Immich. Otherwise it will likely be routed elsewhere and the mobile app may run into connection issues.
diff --git a/docs/docs/reference/server-commands.md b/docs/docs/reference/server-commands.md
new file mode 100644
index 0000000000..44c6cb9b94
--- /dev/null
+++ b/docs/docs/reference/server-commands.md
@@ -0,0 +1,61 @@
+# Server Commands
+
+The `immich-server` docker image comes preinstalled with an administrative CLI (`immich-admin`) that supports the commands below.
+
+To run one, see [Run a server command](/administration/run-a-server-command), which includes example output for each command.
+
+## `help`
+
+Display the list of available commands.
+
+## `reset-admin-password`
+
+Reset the password for the admin user, optionally invalidating existing sessions at the same time. This is the recovery path when nobody can log in as admin; the equivalent for other users is [Password Reset](/administration/manage-users#password-reset).
+
+## `disable-password-login`
+
+Disable password login for the entire instance, the same as turning it off under [Password Authentication](/reference/system-settings#password-authentication).
+
+## `enable-password-login`
+
+Enable password login, the same as turning it on under [Password Authentication](/reference/system-settings#password-authentication). This is how to recover when password login was disabled while OAuth was also unavailable, which otherwise leaves nobody able to log in.
+
+## `disable-maintenance-mode`
+
+Take the instance out of [maintenance mode](/administration/use-maintenance-mode).
+
+## `enable-maintenance-mode`
+
+Put the instance into [maintenance mode](/administration/use-maintenance-mode) and print a URL for logging in to it. Running it again issues a new URL, which is how to regain access if you are logged out while maintenance mode is active.
+
+## `enable-oauth-login`
+
+Enable OAuth login, the same as turning it on under [OAuth Authentication](/reference/system-settings#oauth-authentication). See [Set up OAuth authentication](/administration/set-up-oauth-authentication) for configuring a provider and [OAuth settings](/reference/oauth-settings) for every available option.
+
+## `disable-oauth-login`
+
+Disable OAuth login, the same as turning it off under [OAuth Authentication](/reference/system-settings#oauth-authentication).
+
+## `list-users`
+
+Print every user on the instance, including id, email, storage label, and admin status. See [Manage users](/administration/manage-users).
+
+## `grant-admin`
+
+Grant admin privileges to a user, selected by email. See [Manage users](/administration/manage-users).
+
+## `revoke-admin`
+
+Revoke admin privileges from a user, selected by email. See [Manage users](/administration/manage-users).
+
+## `version`
+
+Print the running Immich version. See [Versioning](/concepts/versioning) for what the version number implies about compatibility and upgrades.
+
+## `change-media-location`
+
+Rewrite the file paths stored in the database to match a new value of `IMMICH_MEDIA_LOCATION`. Run this after moving media to a new location — the command updates the database, it does not move any files. See [Storage locations](/reference/storage-locations).
+
+## `schema-check`
+
+Verify that database migrations are up to date and check for schema drift. See [Schema drift](/errors#schema-drift) for what to do when drift is reported.
diff --git a/docs/docs/reference/storage-locations.md b/docs/docs/reference/storage-locations.md
new file mode 100644
index 0000000000..2e4868b1ba
--- /dev/null
+++ b/docs/docs/reference/storage-locations.md
@@ -0,0 +1,101 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Storage locations
+
+Immich stores original assets, generated content, database dumps, and the database itself in separate directories. This page describes what each one holds. Some locations depend on whether the [storage template](/administration/use-the-storage-template) is enabled.
+
+The root of this layout is `UPLOAD_LOCATION`; individual directories can be redirected elsewhere with the location environment variables documented in [Environment Variables](/reference/environment-variables). For which of these to include in a backup, see [Backups](/concepts/backups).
+
+## Directories
+
+Database storage on Windows systems
+ +The Immich Postgres database (`DB_DATA_LOCATION`) must be located on a filesystem that supports user/group +ownership and permissions (EXT2/3/4, ZFS, APFS, BTRFS, XFS, etc.). It will not work on any filesystem formatted in NTFS or ex/FAT/32. +It will not work in WSL (Windows Subsystem for Linux) when using a mounted host directory (commonly under `/mnt`). +If this is an issue, you can change the bind mount to a Docker volume instead as follows: + +Make the following change to `.env`: + +```diff +- DB_DATA_LOCATION=./postgres ++ DB_DATA_LOCATION=pgdata +``` + +Add the following line to the bottom of `docker-compose.yml`: + +```diff +volumes: + model-cache: ++ pgdata: +``` + +`exif:SubSecDateTimeOriginal`
`exif:DateTimeOriginal`
`xmp:SubSecCreateDate`
`xmp:CreateDate`
`xmp:CreationDate`
`xmp:MediaCreateDate`
`xmp:SubSecMediaCreateDate`
`xmp:DateTimeCreated` | | **Location** | `exif:GPSLatitude`, `exif:GPSLongitude` | `exif:GPSLatitude`, `exif:GPSLongitude` | -| **Tags** | `digiKam:TagsList` | In prioritized order:
`digiKam:TagsList`
`lr:HierarchicalSubject`
`IPTC:Keywords` | +| **Tags** | `digiKam:TagsList` | In prioritized order:
`digiKam:TagsList`
`lr:HierarchicalSubject`
`IPTC:Keywords`
See [hierarchical tags](/reference/exif-tags#hierarchical-tags) for how levels are split | :::note All other fields (e.g. `Creator`, `Source`, IPTC, Lightroom edits) remain in the `.xmp` file and are **not searchable** in Immich. diff --git a/docs/docs/overview/support-the-project.md b/docs/docs/support-the-project.md similarity index 98% rename from docs/docs/overview/support-the-project.md rename to docs/docs/support-the-project.md index ae24a3f1ce..17cd3e8fd8 100644 --- a/docs/docs/overview/support-the-project.md +++ b/docs/docs/support-the-project.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 10 --- # Support The Project diff --git a/docs/docs/user-guide/_category_.json b/docs/docs/user-guide/_category_.json new file mode 100644 index 0000000000..2e41e63c01 --- /dev/null +++ b/docs/docs/user-guide/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "User Guide", + "position": 5 +} diff --git a/docs/docs/user-guide/browse-and-manage-people.md b/docs/docs/user-guide/browse-and-manage-people.md new file mode 100644 index 0000000000..2673fb6c7b --- /dev/null +++ b/docs/docs/user-guide/browse-and-manage-people.md @@ -0,0 +1,33 @@ +# 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. To understand how the grouping actually works, see [Facial recognition](/concepts/facial-recognition). + +## Find the people in your library + +The list of people is shown in the Explore page. + +
+
+Upon clicking on a person, a list of assets that contain their face will be shown.
+
+
+
+The asset detail view will also show the faces that are recognized in the asset.
+
+
+
+## Manage a person
+
+From the app bar in the detail view of a person, you can:
+
+- Change the feature photo of the person
+- Hide the faces of a person from the Explore page and detail view
+- Set a person's date of birth, so that the age of the person can be shown at the time the photo was taken
+- Merge two or more detected people into one person
+- Favorite a person to pin them to the top of the list
+
+
+
+## Improve the results
+
+If the grouping is poor — the same person split across several entries, or unrelated faces lumped together — the settings under `Administration > Settings > Machine Learning Settings > Facial Recognition` control it. See [tuning facial recognition](/concepts/facial-recognition#configuration) for what each setting does, and [Better facial recognition clusters](/administration/improve-facial-recognition-clusters) for a step-by-step tuning procedure.
diff --git a/docs/docs/features/casting.md b/docs/docs/user-guide/cast-media.md
similarity index 79%
rename from docs/docs/features/casting.md
rename to docs/docs/user-guide/cast-media.md
index 2a6785dc6c..81f64be069 100644
--- a/docs/docs/features/casting.md
+++ b/docs/docs/user-guide/cast-media.md
@@ -1,6 +1,6 @@
-# Chromecast support
+# Cast media
-Immich supports the Google's Cast protocol so that photos and videos can be cast to devices such as a Chromecast and a Nest Hub. This feature is considered experimental and has several important limitations listed below. Currently, this feature is only supported by the web client, support on Android and iOS is planned for the future.
+Immich supports the Google's Cast protocol so that photos and videos can be cast to devices such as a Chromecast and a Nest Hub. This feature is considered experimental and has several important limitations listed below.
## Enable Google Cast Support
@@ -16,4 +16,4 @@ To use casting with Immich, there are a few prerequisites:
1. Your instance must be accessed via an HTTPS connection in order for the casting menu to show.
2. Your instance must be publicly accessible via HTTPS and a DNS record for the server must be accessible via Google's DNS servers (`8.8.8.8` and `8.8.4.4`)
-3. Videos must be in a format that is compatible with Google Cast. For more info, check out [Google's documentation](https://developers.google.com/cast/docs/media)
+3. Videos must be in a format that is compatible with Google Cast (see [Supported Media Formats](/reference/supported-media-formats) for what Immich itself accepts). For more info, check out [Google's documentation](https://developers.google.com/cast/docs/media)
diff --git a/docs/docs/features/editing.mdx b/docs/docs/user-guide/edit-photos.mdx
similarity index 98%
rename from docs/docs/features/editing.mdx
rename to docs/docs/user-guide/edit-photos.mdx
index 5d51798e15..af6579e4ff 100644
--- a/docs/docs/features/editing.mdx
+++ b/docs/docs/user-guide/edit-photos.mdx
@@ -1,4 +1,4 @@
-# Editing
+# Edit photos
Immich supports non-destructive editing of photos. This means that any edits you make to an asset do not modify the original file, but instead create a new version of the asset with the edits applied. You can always revert back to the original asset if needed.
diff --git a/docs/docs/features/img/advanced-search-filters.webp b/docs/docs/user-guide/img/advanced-search-filters.webp
similarity index 100%
rename from docs/docs/features/img/advanced-search-filters.webp
rename to docs/docs/user-guide/img/advanced-search-filters.webp
diff --git a/docs/docs/user-guide/img/backup-album-sync.webp b/docs/docs/user-guide/img/backup-album-sync.webp
new file mode 100644
index 0000000000..1a05ef0584
Binary files /dev/null and b/docs/docs/user-guide/img/backup-album-sync.webp differ
diff --git a/docs/docs/features/img/facial-recognition-1.webp b/docs/docs/user-guide/img/facial-recognition-1.webp
similarity index 100%
rename from docs/docs/features/img/facial-recognition-1.webp
rename to docs/docs/user-guide/img/facial-recognition-1.webp
diff --git a/docs/docs/features/img/facial-recognition-2.webp b/docs/docs/user-guide/img/facial-recognition-2.webp
similarity index 100%
rename from docs/docs/features/img/facial-recognition-2.webp
rename to docs/docs/user-guide/img/facial-recognition-2.webp
diff --git a/docs/docs/features/img/facial-recognition-3.webp b/docs/docs/user-guide/img/facial-recognition-3.webp
similarity index 100%
rename from docs/docs/features/img/facial-recognition-3.webp
rename to docs/docs/user-guide/img/facial-recognition-3.webp
diff --git a/docs/docs/features/img/facial-recognition-4.webp b/docs/docs/user-guide/img/facial-recognition-4.webp
similarity index 100%
rename from docs/docs/features/img/facial-recognition-4.webp
rename to docs/docs/user-guide/img/facial-recognition-4.webp
diff --git a/docs/docs/features/img/folder-access.webp b/docs/docs/user-guide/img/folder-access.webp
similarity index 100%
rename from docs/docs/features/img/folder-access.webp
rename to docs/docs/user-guide/img/folder-access.webp
diff --git a/docs/docs/user-guide/img/folder-view-1.webp b/docs/docs/user-guide/img/folder-view-1.webp
new file mode 100644
index 0000000000..be4a55873d
Binary files /dev/null and b/docs/docs/user-guide/img/folder-view-1.webp differ
diff --git a/docs/docs/features/img/folder-view-enable.webp b/docs/docs/user-guide/img/folder-view-enable.webp
similarity index 100%
rename from docs/docs/features/img/folder-view-enable.webp
rename to docs/docs/user-guide/img/folder-view-enable.webp
diff --git a/docs/docs/features/img/free-up-space.webp b/docs/docs/user-guide/img/free-up-space.webp
similarity index 100%
rename from docs/docs/features/img/free-up-space.webp
rename to docs/docs/user-guide/img/free-up-space.webp
diff --git a/docs/docs/features/img/gcast-enable.webp b/docs/docs/user-guide/img/gcast-enable.webp
similarity index 100%
rename from docs/docs/features/img/gcast-enable.webp
rename to docs/docs/user-guide/img/gcast-enable.webp
diff --git a/docs/docs/features/img/mobile-upload-selected-photos.webp b/docs/docs/user-guide/img/mobile-upload-selected-photos.webp
similarity index 100%
rename from docs/docs/features/img/mobile-upload-selected-photos.webp
rename to docs/docs/user-guide/img/mobile-upload-selected-photos.webp
diff --git a/docs/docs/features/img/obtain-api-key-2.webp b/docs/docs/user-guide/img/obtain-api-key-2.webp
similarity index 100%
rename from docs/docs/features/img/obtain-api-key-2.webp
rename to docs/docs/user-guide/img/obtain-api-key-2.webp
diff --git a/docs/docs/features/img/obtain-api-key.webp b/docs/docs/user-guide/img/obtain-api-key.webp
similarity index 100%
rename from docs/docs/features/img/obtain-api-key.webp
rename to docs/docs/user-guide/img/obtain-api-key.webp
diff --git a/docs/docs/features/img/partner-sharing-1.webp b/docs/docs/user-guide/img/partner-sharing-1.webp
similarity index 100%
rename from docs/docs/features/img/partner-sharing-1.webp
rename to docs/docs/user-guide/img/partner-sharing-1.webp
diff --git a/docs/docs/features/img/partner-sharing-2.webp b/docs/docs/user-guide/img/partner-sharing-2.webp
similarity index 100%
rename from docs/docs/features/img/partner-sharing-2.webp
rename to docs/docs/user-guide/img/partner-sharing-2.webp
diff --git a/docs/docs/features/img/partner-sharing-3.webp b/docs/docs/user-guide/img/partner-sharing-3.webp
similarity index 100%
rename from docs/docs/features/img/partner-sharing-3.webp
rename to docs/docs/user-guide/img/partner-sharing-3.webp
diff --git a/docs/docs/features/img/partner-sharing-4.webp b/docs/docs/user-guide/img/partner-sharing-4.webp
similarity index 100%
rename from docs/docs/features/img/partner-sharing-4.webp
rename to docs/docs/user-guide/img/partner-sharing-4.webp
diff --git a/docs/docs/features/img/partner-sharing-5.webp b/docs/docs/user-guide/img/partner-sharing-5.webp
similarity index 100%
rename from docs/docs/features/img/partner-sharing-5.webp
rename to docs/docs/user-guide/img/partner-sharing-5.webp
diff --git a/docs/docs/features/img/partner-sharing-6.webp b/docs/docs/user-guide/img/partner-sharing-6.webp
similarity index 100%
rename from docs/docs/features/img/partner-sharing-6.webp
rename to docs/docs/user-guide/img/partner-sharing-6.webp
diff --git a/docs/docs/features/img/partner-sharing-7.webp b/docs/docs/user-guide/img/partner-sharing-7.webp
similarity index 100%
rename from docs/docs/features/img/partner-sharing-7.webp
rename to docs/docs/user-guide/img/partner-sharing-7.webp
diff --git a/docs/docs/features/img/partner-sharing-8.webp b/docs/docs/user-guide/img/partner-sharing-8.webp
similarity index 100%
rename from docs/docs/features/img/partner-sharing-8.webp
rename to docs/docs/user-guide/img/partner-sharing-8.webp
diff --git a/docs/docs/features/img/public-shared-link-album.webp b/docs/docs/user-guide/img/public-shared-link-album.webp
similarity index 100%
rename from docs/docs/features/img/public-shared-link-album.webp
rename to docs/docs/user-guide/img/public-shared-link-album.webp
diff --git a/docs/docs/features/img/public-shared-link-form.webp b/docs/docs/user-guide/img/public-shared-link-form.webp
similarity index 100%
rename from docs/docs/features/img/public-shared-link-form.webp
rename to docs/docs/user-guide/img/public-shared-link-form.webp
diff --git a/docs/docs/features/img/public-shared-link-individual.webp b/docs/docs/user-guide/img/public-shared-link-individual.webp
similarity index 100%
rename from docs/docs/features/img/public-shared-link-individual.webp
rename to docs/docs/user-guide/img/public-shared-link-individual.webp
diff --git a/docs/docs/features/img/read-only-mode.webp b/docs/docs/user-guide/img/read-only-mode.webp
similarity index 100%
rename from docs/docs/features/img/read-only-mode.webp
rename to docs/docs/user-guide/img/read-only-mode.webp
diff --git a/docs/docs/features/img/shared-album-mobile.webp b/docs/docs/user-guide/img/shared-album-mobile.webp
similarity index 100%
rename from docs/docs/features/img/shared-album-mobile.webp
rename to docs/docs/user-guide/img/shared-album-mobile.webp
diff --git a/docs/docs/features/img/shared-album-user-selection.webp b/docs/docs/user-guide/img/shared-album-user-selection.webp
similarity index 100%
rename from docs/docs/features/img/shared-album-user-selection.webp
rename to docs/docs/user-guide/img/shared-album-user-selection.webp
diff --git a/docs/docs/features/img/shared-album.webp b/docs/docs/user-guide/img/shared-album.webp
similarity index 100%
rename from docs/docs/features/img/shared-album.webp
rename to docs/docs/user-guide/img/shared-album.webp
diff --git a/docs/docs/features/img/tag-creation.webp b/docs/docs/user-guide/img/tag-creation.webp
similarity index 100%
rename from docs/docs/features/img/tag-creation.webp
rename to docs/docs/user-guide/img/tag-creation.webp
diff --git a/docs/docs/features/img/tag-enable.webp b/docs/docs/user-guide/img/tag-enable.webp
similarity index 100%
rename from docs/docs/features/img/tag-enable.webp
rename to docs/docs/user-guide/img/tag-enable.webp
diff --git a/docs/docs/features/img/tag-form.webp b/docs/docs/user-guide/img/tag-form.webp
similarity index 100%
rename from docs/docs/features/img/tag-form.webp
rename to docs/docs/user-guide/img/tag-form.webp
diff --git a/docs/docs/features/img/tag-view.webp b/docs/docs/user-guide/img/tag-view.webp
similarity index 100%
rename from docs/docs/features/img/tag-view.webp
rename to docs/docs/user-guide/img/tag-view.webp
diff --git a/docs/docs/features/img/user-settings-1.webp b/docs/docs/user-guide/img/user-settings-1.webp
similarity index 100%
rename from docs/docs/features/img/user-settings-1.webp
rename to docs/docs/user-guide/img/user-settings-1.webp
diff --git a/docs/docs/features/img/user-settings-2.webp b/docs/docs/user-guide/img/user-settings-2.webp
similarity index 100%
rename from docs/docs/features/img/user-settings-2.webp
rename to docs/docs/user-guide/img/user-settings-2.webp
diff --git a/docs/docs/features/img/user-settings-3.webp b/docs/docs/user-guide/img/user-settings-3.webp
similarity index 100%
rename from docs/docs/features/img/user-settings-3.webp
rename to docs/docs/user-guide/img/user-settings-3.webp
diff --git a/docs/docs/features/img/web-edit-download.webp b/docs/docs/user-guide/img/web-edit-download.webp
similarity index 100%
rename from docs/docs/features/img/web-edit-download.webp
rename to docs/docs/user-guide/img/web-edit-download.webp
diff --git a/docs/docs/features/img/web-edit-interface.webp b/docs/docs/user-guide/img/web-edit-interface.webp
similarity index 100%
rename from docs/docs/features/img/web-edit-interface.webp
rename to docs/docs/user-guide/img/web-edit-interface.webp
diff --git a/docs/docs/features/user-settings.md b/docs/docs/user-guide/manage-your-user-settings.md
similarity index 72%
rename from docs/docs/features/user-settings.md
rename to docs/docs/user-guide/manage-your-user-settings.md
index 402105cd43..025a0ab371 100644
--- a/docs/docs/features/user-settings.md
+++ b/docs/docs/user-guide/manage-your-user-settings.md
@@ -1,6 +1,6 @@
-# User Settings
+# Manage your user settings
-Immich gives each user the ability to manage their own settings. This includes being able to update their profile, toggle certain feature, generate API keys, manage the logged in devices, a view of account usage statistics, and more.
+Immich gives each user the ability to manage their own settings. This includes being able to update their profile, toggle certain feature, generate [API keys](/reference/immich-api), manage the logged in devices, a view of account usage statistics, and more.
.default} "User settings lists")
@@ -15,9 +15,9 @@ You can access the [user settings](https://my.immich.app/user-settings) by click
---
:::tip Reset Password
-The admin can reset a user password through the [User Management](/administration/user-management.mdx) screen.
+The admin can reset a user password through the [User Management](/administration/manage-users) screen.
:::
:::tip Reset Admin Password
-The admin password can be reset using a [Server Command](/administration/server-commands.md)
+The admin password can be reset using a [server command](/administration/run-a-server-command)
:::
diff --git a/docs/docs/user-guide/review-duplicates.md b/docs/docs/user-guide/review-duplicates.md
new file mode 100644
index 0000000000..d4a047b0e5
--- /dev/null
+++ b/docs/docs/user-guide/review-duplicates.md
@@ -0,0 +1,9 @@
+# Review duplicates
+
+The "Review duplicates" utility lists assets that Immich has found to be [visually similar](/concepts/duplicate-detection), and lets you choose what to keep. Open it [here](https://my.immich.app/utilities/duplicates).
+
+For how detection works, how Immich decides what to preselect, and what happens to the metadata of the assets you trash, see [Duplicate detection](/concepts/duplicate-detection).
+
+## Reviewing duplicates
+
+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.
diff --git a/docs/docs/user-guide/search-your-library.md b/docs/docs/user-guide/search-your-library.md
new file mode 100644
index 0000000000..f927575301
--- /dev/null
+++ b/docs/docs/user-guide/search-your-library.md
@@ -0,0 +1,37 @@
+# Search your library
+
+Immich offers two ways to find assets: contextual search, which understands the content of your photos and videos, and advanced search filters, which narrow results by metadata. You can try both on the [Demo site](https://demo.immich.app).
+
+Contextual search works without any specific keywords in the metadata — describe what you remember about the photo. Which model powers it, and how to change it, is covered in the [CLIP models reference](/reference/clip-models).
+
+## Search with advanced filters
+
+Advanced search lets you find specific content using customizable filters, including location, one or more faces, specific albums, and more. You can search the following types of content:
+
+| Type | Description |
+| ----------------------------------- | ----------------------------------------------------- |
+| People | Faces that are recognized in your photos/videos. |
+| Contextual | Content of the photos and videos. |
+| File name or extension | Full or partial file's name, or file's extension |
+| Full path or folder | Full or partial folder names from the original path. |
+| Description | Description added to assets. |
+| Optical Character Recognition (OCR) | Text in images |
+| Locations | Cities, states, and countries from reverse geocoding. |
+| Tags | Tags assigned or extracted from assets. |
+| Camera | make, model and lens model |
+| Time frame | Start and end date of a specific time bucket |
+| Media type | Image or video or both |
+| Display options | In Archive, in Favorites or Not in any album |
+| Star rating | User-assigned star rating |
+
+
+
+## Search by folder or path
+
+Use the **Full path or folder** filter when you know a folder name or part of the original asset path.
+
+For example, for `/John/Projects/3D_Printing/2026-07-01/IMG_0001.jpg`, searches like `Projects`, `3D`, `Printing`, or `2026` all match the asset.
+
+## Search by location
+
+Cities, states, and countries come from [reverse geocoding](/concepts/reverse-geocoding), which runs during metadata extraction — so location search only works for assets that have GPS coordinates.
diff --git a/docs/docs/features/sharing.md b/docs/docs/user-guide/share-photos-and-albums.md
similarity index 53%
rename from docs/docs/features/sharing.md
rename to docs/docs/user-guide/share-photos-and-albums.md
index a884884bee..3c1d918016 100644
--- a/docs/docs/features/sharing.md
+++ b/docs/docs/user-guide/share-photos-and-albums.md
@@ -1,13 +1,11 @@
-# Sharing
+# Share photos and albums
-Immich supports local sharing, with users on the same Immich instance, and public sharing via public links.
+Immich supports sharing albums and partner libraries with users on the same instance, and public links for people without an account. For how the three differ, see [Sharing](/concepts/sharing).
## Local sharing
### 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.
-
After creating an album, you can access the sharing options by clicking on the share icon. When sharing an album, you can select the users you want to share the album with and assign them permissions either as editors (read-write) or viewers (read-only).
#### Web
@@ -22,20 +20,10 @@ After creating an album, you can access the sharing options by clicking on the s
### Partners
-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.
-
-You can read this guide to learn more about [partner sharing](/features/partner-sharing).
+You can read this guide to learn more about [partner sharing](/user-guide/share-with-a-partner).
## Public sharing
-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.
-
-```
-https://my.immich.app/share/JUckRMxlgpo7F9BpyqGk_cZEwDzaU_U5LU5_oNZp1ETIBa9dpQ0b5ghNm_22QVJfn3k
-```
-
### Creating a public share link
You can create a public share link by selecting the photos or videos, or from the share icon on an album.
diff --git a/docs/docs/features/partner-sharing.md b/docs/docs/user-guide/share-with-a-partner.md
similarity index 64%
rename from docs/docs/features/partner-sharing.md
rename to docs/docs/user-guide/share-with-a-partner.md
index 1934344d01..0d5e2cb3a0 100644
--- a/docs/docs/features/partner-sharing.md
+++ b/docs/docs/user-guide/share-with-a-partner.md
@@ -1,25 +1,8 @@
-# Partner Sharing
+# Share with a partner
-Immich allows you to share your library with other users. They can then view your library and download the assets. You can manage Partner Sharing from the [User Settings](docs/features/user-settings.md) page on the web.
+Immich allows you to [share your entire library](/concepts/sharing#partner-sharing) with other users. They can then view your library and download the assets. You can manage Partner Sharing from the [User Settings](/user-guide/manage-your-user-settings) page on the web.
-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.
-
-:::
+For exactly what a partner can and cannot see, see [Sharing](/concepts/sharing#partner-sharing).
## Sharing with a Partner
diff --git a/docs/docs/guides/python-file-upload.md b/docs/docs/user-guide/upload-files-with-python.md
similarity index 76%
rename from docs/docs/guides/python-file-upload.md
rename to docs/docs/user-guide/upload-files-with-python.md
index 6816924e6f..99e3b2ee9d 100644
--- a/docs/docs/guides/python-file-upload.md
+++ b/docs/docs/user-guide/upload-files-with-python.md
@@ -1,4 +1,6 @@
-# Python File Upload
+# Upload files with Python
+
+A minimal example of uploading an asset by calling the API directly, for cases where the [CLI](/reference/immich-cli) is not a good fit. See the [Immich API](/reference/immich-api) reference for the published API documentation.
```python
#!/usr/bin/python3
diff --git a/docs/docs/user-guide/upload-media-with-the-cli.md b/docs/docs/user-guide/upload-media-with-the-cli.md
new file mode 100644
index 0000000000..49e140a624
--- /dev/null
+++ b/docs/docs/user-guide/upload-media-with-the-cli.md
@@ -0,0 +1,122 @@
+# Upload media with the CLI
+
+This guide covers uploading photos and videos to Immich from a terminal with the [Immich CLI](/reference/immich-cli). Install it first, then come back here.
+
+:::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).
+:::
+
+## Obtain an 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.
+
+
+
+
+
+## Authenticate
+
+Log in with your server URL and API key:
+
+```bash
+# immich login [url] [key]
+immich login http://192.168.1.216:2283/api HFEJ38DNSDUEG
+```
+
+This stores your credentials in an `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`. Keep the file secure, either by running `immich logout` when you are done or by deleting it manually.
+
+## Upload individual files
+
+```bash
+immich upload file1.jpg file2.jpg
+```
+
+## Upload a directory and its subfolders
+
+By default, subfolders are not included. To upload a directory including subfolders, use the `--recursive` option:
+
+```bash
+immich upload --recursive directory/
+```
+
+## Preview what would happen
+
+If you are unsure what will happen, use the `--dry-run` option to see what would be uploaded without actually performing any actions:
+
+```bash
+immich upload --dry-run --recursive directory/
+```
+
+## Skip hashing to upload faster
+
+By default, the upload command hashes files before uploading them to avoid uploading the same file multiple times. If you are sure that the files are unique, you can skip this step with `--skip-hash`. 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/
+```
+
+## Create albums from folder names
+
+`--album` creates an album for each uploaded asset based on the name of the folder it is in:
+
+```bash
+immich upload --album --recursive directory/
+```
+
+To put everything into one specific album instead, use `--album-name`:
+
+```bash
+immich upload --album-name "My summer holiday" --recursive directory/
+```
+
+## Skip files matching a pattern
+
+`--ignore` skips assets matching a glob pattern. See [Exclusion patterns](/reference/exclusion-patterns) for how to write 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/
+```
+
+## Include hidden files
+
+By default, hidden files are skipped:
+
+```bash
+immich upload --include-hidden --recursive directory/
+```
+
+## Set the visibility of uploaded assets
+
+You can set the visibility of uploaded assets to `archive`, `timeline`, `hidden`, or `locked`:
+
+```bash
+immich upload --visibility archive --recursive directory/
+```
+
+## Post-process the results as JSON
+
+The `--json-output` option prints JSON with three keys: `newFiles`, `duplicates` and `newAssets`. Due to some logging output you need to strip the first few lines of output to get at 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[]
+```
+
+## Run the CLI from Docker
+
+If npm is not available on your system, you can use the Docker image instead:
+
+```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
+```
+
+Modify the `IMMICH_INSTANCE_URL` and `IMMICH_API_KEY` environment variables as appropriate. You can also use a Docker env file to store your sensitive API key.
+
+This `docker run` command runs the `immich` command inside the container, so you can append the desired parameters directly to the command line:
+
+```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/
+```
diff --git a/docs/docs/features/folder-view.md b/docs/docs/user-guide/use-folder-view.md
similarity index 81%
rename from docs/docs/features/folder-view.md
rename to docs/docs/user-guide/use-folder-view.md
index 3d8613a042..48e19cb41f 100644
--- a/docs/docs/features/folder-view.md
+++ b/docs/docs/user-guide/use-folder-view.md
@@ -1,6 +1,6 @@
-# Folder View
+# Use 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.
+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](/concepts/external-libraries) or a nicely configured [storage template](/reference/storage-locations).
You can enable this feature under [`Account Settings > Features > Folders`](https://my.immich.app/user-settings?isOpen=feature+folders)
diff --git a/docs/docs/features/tags.md b/docs/docs/user-guide/use-tags.md
similarity index 67%
rename from docs/docs/features/tags.md
rename to docs/docs/user-guide/use-tags.md
index 79a9696d9a..f6d425518d 100644
--- a/docs/docs/features/tags.md
+++ b/docs/docs/user-guide/use-tags.md
@@ -1,6 +1,6 @@
-# Tags
+# Use tags
-Immich supports hierarchical tags, with the ability to read existing tags from the XMP `TagsList` field and IPTC `Keywords` field. Any changes to tags made through Immich are also written back to a [sidecar](/features/xmp-sidecars) file. You can re-run the metadata extraction jobs for all assets to import your existing tags.
+Immich supports [hierarchical tags](/reference/exif-tags#hierarchical-tags), and can import tags that already exist in your files — see [EXIF tags](/reference/exif-tags#tags) for which metadata fields are read. Any changes to tags made through Immich are also written back to a [sidecar](/reference/xmp-sidecars) file. You can re-run the metadata extraction jobs for all assets to import your existing tags.
## Enable tags feature
diff --git a/docs/docs/features/mobile-app.mdx b/docs/docs/user-guide/use-the-mobile-app.mdx
similarity index 87%
rename from docs/docs/features/mobile-app.mdx
rename to docs/docs/user-guide/use-the-mobile-app.mdx
index 1b7c7e21d5..66301c8e92 100644
--- a/docs/docs/features/mobile-app.mdx
+++ b/docs/docs/user-guide/use-the-mobile-app.mdx
@@ -4,7 +4,9 @@ import MobileAppDownload from '/docs/partials/_mobile-app-download.md';
import MobileAppLogin from '/docs/partials/_mobile-app-login.md';
import MobileAppBackup from '/docs/partials/_mobile-app-backup.md';
-# Mobile App
+# Use the mobile app
+
+Installing the app, signing in, and the settings that control what it uploads. For how mobile backup behaves — deduplication, networking, album sync, and platform differences — see [Mobile Backup](/concepts/mobile-backup).
## Download
@@ -74,7 +76,7 @@ Now make sure that the local album is selected in the backup screen (steps 1-2 a
To use the reclaimed space right away, you must empty the system/gallery trash manually outside of Immich.
:::
-Provided the server is healthy and [backed up](/administration/backup-and-restore.md), assets removed by Free Up Space can always be accessed in the Immich app.
+Provided the server is healthy and [backed up](/administration/back-up-and-restore), assets removed by Free Up Space can always be accessed in the Immich app.
### iCloud Photos
@@ -100,19 +102,7 @@ If Immich backs up your WhatsApp folder and you run **Free Up Space**, the local
You can sync or mirror an album from your phone to the Immich server on your account. For example, if you select Recents, Camera and Videos album for backup, the corresponding album with the same name will be created on the server. Once the assets from those albums are uploaded, they will be put into the target albums automatically.
-### Album Synchronization Highlights
-
-- **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](/features/libraries) for further details.
+For the semantics of the sync — what matches, what merges, and what is not propagated — see [Mobile Backup](/concepts/mobile-backup#album-synchronization-semantics).
### Synchronizing albums from the past
diff --git a/docs/src/components/community-disclaimer.tsx b/docs/src/components/community-disclaimer.tsx
new file mode 100644
index 0000000000..c3523c8bc7
--- /dev/null
+++ b/docs/src/components/community-disclaimer.tsx
@@ -0,0 +1,18 @@
+import Admonition from '@theme/Admonition';
+import React from 'react';
+
+/**
+ * Disclaimer shown at the top of every community-contributed installation guide.
+ * Pass the platform's support venue as children.
+ */
+export default function CommunityDisclaimer({ children }: { children?: React.ReactNode }): JSX.Element {
+ return (
+ + This is a community contribution, not officially supported by the Immich team, and is included here for + convenience. Use it at your own risk. +
+ {children} +
{#if duplicates && duplicates.length > 0}
-
{#key duplicates[duplicatesIndex].duplicateId}
diff --git a/web/src/routes/ErrorLayout.svelte b/web/src/routes/ErrorLayout.svelte
index 8976e88fee..a66c82eb33 100644
--- a/web/src/routes/ErrorLayout.svelte
+++ b/web/src/routes/ErrorLayout.svelte
@@ -78,7 +78,10 @@
{$t('read_changelog')}
-
+
{$t('check_logs')}
diff --git a/web/src/routes/admin/system-settings/AuthSettings.svelte b/web/src/routes/admin/system-settings/AuthSettings.svelte
index 22118d97a8..d1a1b921bc 100644
--- a/web/src/routes/admin/system-settings/AuthSettings.svelte
+++ b/web/src/routes/admin/system-settings/AuthSettings.svelte
@@ -75,7 +75,7 @@
{#snippet children({ message })}
- {message}
+ {message}
{/snippet}
diff --git a/web/src/routes/admin/system-settings/MapSettings.svelte b/web/src/routes/admin/system-settings/MapSettings.svelte
index 07eb5292ae..e9eb9f23e8 100644
--- a/web/src/routes/admin/system-settings/MapSettings.svelte
+++ b/web/src/routes/admin/system-settings/MapSettings.svelte
@@ -55,7 +55,7 @@
{#snippet children({ tag, message })}
{#if tag === 'link'}
-
+
{message}
{/if}
{$t('duplicates_description')}
+ {$t('duplicates_description')}
+