diff --git a/docs/docs/install/docker-compose.mdx b/docs/docs/install/docker-compose.mdx index b73d51b4d240a..6473f70cca5dc 100644 --- a/docs/docs/install/docker-compose.mdx +++ b/docs/docs/install/docker-compose.mdx @@ -7,10 +7,9 @@ import ExampleEnv from '!!raw-loader!../../../docker/example.env'; # Docker Compose [Recommended] -Docker Compose is the recommended method to run Immich in production. Below are the steps to deploy Immich with Docker Compose. -Immich requires Docker Compose version 2.x. +Docker Compose is the recommended method to run Immich in production. Below are the steps to deploy Immich with Docker Compose. -### Step 1 - Download the required files +## Step 1 - Download the required files Create a directory of your choice (e.g. `./immich-app`) to hold the `docker-compose.yml` and `.env` files. @@ -19,7 +18,7 @@ mkdir ./immich-app cd ./immich-app ``` -Download [`docker-compose.yml`][compose-file] and [`example.env`][env-file], either by running the following commands: +Download [`docker-compose.yml`][compose-file] and [`example.env`][env-file] by running the following commands: ```bash title="Get docker-compose.yml file" wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml @@ -29,6 +28,11 @@ wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/ wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env ``` +You can alternatively download these two files from your browser and move them to the directory that you created, in which case ensure that you rename `example.env` to `.env`. + +:::info Optional Features +If you intend to use hardware acceleration for transcoding or machine learning (ML), you can download now the config files you'll need, in the same way: + ```bash title="(Optional) Get hwaccel.transcoding.yml file" wget -O hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml ``` @@ -37,15 +41,9 @@ wget -O hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/la wget -O hwaccel.ml.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml ``` -or by downloading from your browser and moving the files to the directory that you created. - -Note: If you downloaded the files from your browser, also ensure that you rename `example.env` to `.env`. - -:::info -Optionally, you can enable hardware acceleration for machine learning and transcoding. See the [Hardware Transcoding](/docs/features/hardware-transcoding.md) and [Hardware-Accelerated Machine Learning](/docs/features/ml-hardware-acceleration.md) guides for info on how to set these up. ::: -### Step 2 - Populate the .env file with custom values +## Step 2 - Populate the .env file with custom values
@@ -54,31 +52,37 @@ Optionally, you can enable hardware acceleration for machine learning and transc {ExampleEnv}
-- Populate custom database information if necessary. -- Populate `UPLOAD_LOCATION` with your preferred location for storing backup assets. +- Populate `UPLOAD_LOCATION` with your preferred location for storing backup assets. It should be a new directory on the server with enough free space. - Consider changing `DB_PASSWORD` to a custom value. Postgres is not publically exposed, so this password is only used for local authentication. - To avoid issues with Docker parsing this value, it is best to use only the characters `A-Za-z0-9`. + To avoid issues with Docker parsing this value, it is best to use only the characters `A-Za-z0-9`. `pwgen` is a handy utility for this. - Set your timezone by uncommenting the `TZ=` line. +- Populate custom database information if necessary. + +:::info Optional Features +You can make the required edits to `docker-compose.yml` to add external libraries or enable hardware acceleration now by following [their guides](#setting-up-optional-features) up to and including those edits. +::: -### Step 3 - Start the containers +## Step 3 - Start the containers -From the directory you created in Step 1, (which should now contain your customized `docker-compose.yml` and `.env` files) run `docker compose up -d`. +From the directory you created in Step 1 (which should now contain your customized `docker-compose.yml` and `.env` files), run `docker compose up -d`. ```bash title="Start the containers using docker compose command" docker compose up -d ``` +The `restart: always` entries in `docker-compose.yml` for each container mean they will always restart after system reboot or program crashes. + :::info Docker version -If you get an error `unknown shorthand flag: 'd' in -d`, you are probably running the wrong Docker version. (This happens, for example, with the docker.io package in Ubuntu 22.04.3 LTS.) You can correct the problem by `apt remove`ing Ubuntu's docker.io package and installing docker and docker-compose via [Docker's official repository][docker-repo]. +If you get an error `unknown shorthand flag: 'd' in -d`, you are probably running the wrong Docker version. (This happens, for example, with the docker.io package in Ubuntu 22.04.3 LTS.) You can correct the problem by following the complete [Docker Engine install](https://docs.docker.com/engine/install/) procedure for your distribution, crucially the "Uninstall old versions" and "Install using the apt/rpm repository" sections. These replace the distro's Docker packages with Docker's official ones. -Note that the correct command really is `docker compose`, not `docker-compose`. If you try the latter on vanilla Ubuntu 22.04 it will fail in a different way: +Note that the correct command really is `docker compose`, not `docker-compose`. If you try the latter on vanilla Ubuntu 22.04, it will fail in a different way: ``` The Compose file './docker-compose.yml' is invalid because: 'name' does not match any of the regexes: '^x-' ``` -See the previous paragraph about installing from the official docker repository. +See the previous paragraph about installing from the official Docker repository. ::: :::info Health check start interval @@ -93,7 +97,17 @@ For more information on how to use the application, please refer to the [Post In Downloading container images might require you to authenticate to the GitHub Container Registry ([steps here][container-auth]). ::: -### Step 4 - Upgrading +## Next Steps + +### Setting Up Optional Features + +You can set up the following now: + +- [External Libraries](/docs/features/libraries.md) +- [Hardware Transcoding](/docs/features/hardware-transcoding.md) +- [Hardware-Accelerated Machine Learning](/docs/features/ml-hardware-acceleration.md) + +### Upgrading :::danger Breaking Changes It is important to follow breaking updates to avoid problems. You can see versions that had breaking changes [here][breaking]. @@ -101,12 +115,18 @@ It is important to follow breaking updates to avoid problems. You can see versio If `IMMICH_VERSION` is set, it will need to be updated to the latest or desired version. -When a new version of Immich is [released][releases], the application can be upgraded with the following commands, run in the directory with the `docker-compose.yml` file: +When a new version of Immich is [released][releases], the application can be upgraded and restarted with the following commands, run in the directory with the `docker-compose.yml` file: -```bash title="Upgrade Immich" +```bash title="Upgrade and restart Immich" docker compose pull && docker compose up -d ``` +To clean up disk space, the old version's obsolete containers can be deleted with the following command, which deletes all stopped containers. As such, make sure to start Immich (with the previous command) before running it. + +```bash title="Delete all stopped containers" +docker system prune +``` + :::caution Automatic Updates Immich is currently under heavy development, which means you can expect [breaking changes][breaking] and bugs. Therefore, we recommend reading the release notes prior to updating and to take special care when using automated tools like [Watchtower][watchtower]. ::: @@ -117,4 +137,3 @@ Immich is currently under heavy development, which means you can expect [breakin [breaking]: https://github.com/immich-app/immich/discussions?discussions_q=label%3Achangelog%3Abreaking-change+sort%3Adate_created [container-auth]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry [releases]: https://github.com/immich-app/immich/releases -[docker-repo]: https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository diff --git a/docs/docs/install/requirements.md b/docs/docs/install/requirements.md index b96705203aa8f..0984eb4ffb453 100644 --- a/docs/docs/install/requirements.md +++ b/docs/docs/install/requirements.md @@ -8,18 +8,20 @@ Hardware and software requirements for Immich: ## Software -- [Docker](https://docs.docker.com/get-docker/) -- [Docker Compose](https://docs.docker.com/compose/install/) +Immich requires [**Docker**](https://docs.docker.com/get-started/get-docker/) with the **Docker Compose plugin**: + +- **Docker Engine**: This CLI variant is suitable for Linux servers or Windows via WSL2. +- **Docker Desktop**: This GUI variant is suitable for Linux (desktop), 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/) (pick the plugin, not the standalone). :::note -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. +Immich requires the command `docker compose` (the plugin); the similarly named `docker-compose` (the standalone) is [deprecated](https://docs.docker.com/compose/migrate/) and is no longer compatible with Immich. ::: ## Hardware -- **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/). +- **OS**: Linux is recommended, and Windows and macOS are supported: any version or distribution that Docker can be installed on (see above). - **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. diff --git a/docs/docs/overview/quick-start.mdx b/docs/docs/overview/quick-start.mdx index e352757a0f67e..597c94d1acd78 100644 --- a/docs/docs/overview/quick-start.mdx +++ b/docs/docs/overview/quick-start.mdx @@ -14,13 +14,7 @@ Check the [requirements page](/docs/install/requirements) to get started. ## Install and Launch via Docker Compose -Follow the [Docker Compose (Recommended)](/docs/install/docker-compose) instructions -to install the server. - -- Where random passwords are required, `pwgen` is a handy utility. -- `UPLOAD_LOCATION` should be set to some new directory on the server - with enough free space. -- You may ignore "Step 4 - Upgrading". +Follow the [Docker Compose (Recommended)](/docs/install/docker-compose) instructions to install the server. ## Try the Web UI