From 3a68190b99a35656e00584b88ae68ec58e450ccf Mon Sep 17 00:00:00 2001 From: Matthew Momjian <50788000+mmomjian@users.noreply.github.com> Date: Fri, 10 May 2024 11:02:48 -0400 Subject: [PATCH] docs: warn against use on NTFS / WSL (#9371) * DB filesystem * updates to requirements * wording * OS update * Update environment-variables.md * Update FAQ.mdx * Update requirements.md --- docs/docs/FAQ.mdx | 5 +++++ docs/docs/install/environment-variables.md | 11 +++++++++-- docs/docs/install/requirements.md | 17 ++++++++++------- 3 files changed, 24 insertions(+), 9 deletions(-) diff --git a/docs/docs/FAQ.mdx b/docs/docs/FAQ.mdx index 6739670f46..aaf093d49f 100644 --- a/docs/docs/FAQ.mdx +++ b/docs/docs/FAQ.mdx @@ -399,6 +399,11 @@ If it mentions SIGILL (note the lack of a K) or error code 132, it most likely m If your version of Immich is below 1.92.0 and the crash occurs after logs about tracing or exporting a model, consider either upgrading or disabling the Tag Objects job. +### Why am I getting database errors? + +If you get database errors such as `FATAL: data directory "/var/lib/postgresql/data" has wrong ownership` upon database startup, this is likely due to an issue with your filesystem. +NTFS and ex/FAT/32 filesystems are not supported. See [here](/docs/install/environment-variables#supported-filesystems) for more details. + ### Why does Immich log migration errors on startup? Sometimes Immich logs errors such as "duplicate key value violates unique constraint" or "column (...) of relation (...) already exists". Because of Immich's container structure, this error can be seen when both immich and immich-microservices start at the same time and attempt to migrate or create the database structure. Since the database migration is run sequentially and inside of transactions, this error message does not cause harm to your installation of Immich and can safely be ignored. If needed, you can manually restart Immich by running `docker restart immich immich-microservices`. diff --git a/docs/docs/install/environment-variables.md b/docs/docs/install/environment-variables.md index 6826107893..5b498f1b27 100644 --- a/docs/docs/install/environment-variables.md +++ b/docs/docs/install/environment-variables.md @@ -24,11 +24,18 @@ If this should not work, try running `docker compose up -d --force-recreate`. | `DB_DATA_LOCATION` | Host Path for Postgres database | | database | :::tip - These environment variables are used by the `docker-compose.yml` file and do **NOT** affect the containers directly. - ::: +### Supported filesystems + +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. + +Regardless of filesystem, it is not recommended to use a network share for your database location due to performance and possible data loss issues. + ## General | Variable | Description | Default | Services | diff --git a/docs/docs/install/requirements.md b/docs/docs/install/requirements.md index b611d04f2c..8944336ec7 100644 --- a/docs/docs/install/requirements.md +++ b/docs/docs/install/requirements.md @@ -15,12 +15,15 @@ Hardware and software requirements for Immich Immich requires the command `docker compose` - the similarly named `docker-compose` is [deprecated](https://docs.docker.com/compose/migrate/) and is no longer compatible with Immich. ::: -:::info Podman -You can also use Podman to run the application. However, additional configuration might be required. -::: - ## Hardware -- **OS**: Preferred unix-based operating system (Ubuntu, Debian, MacOS, etc). Windows works too, with [Docker Desktop on Windows](https://docs.docker.com/desktop/install/windows-install/) -- **RAM**: At least 4GB, preferred 6GB. -- **CPU**: At least 2 cores, preferred 4 cores. +- **OS**: Recommended Linux operating system (Ubuntu, Debian, etc). + - Windows is supported with [Docker Desktop on Windows](https://docs.docker.com/desktop/install/windows-install/) or [WSL 2](https://docs.docker.com/desktop/wsl/). + - macOS is supported with [Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/). +- **RAM**: Minimum 4GB, recommended 6GB. +- **CPU**: Minimum 2 cores, recommended 4 cores. +- **Storage**: Recommended Unix-compatible filesystem (EXT4, ZFS, APFS, etc.) with support for user/group ownership and permissions. + - This can present an issue for Windows users. See [here](/docs/install/environment-variables#supported-filesystems) + for more details and alternatives. + - The generation of thumbnails and transcoded video can increase the size of the photo library by 10-20% on average. + - Network shares are supported for the storage of image and video assets only.