mirror of
https://github.com/immich-app/immich.git
synced 2024-12-28 06:31:58 +00:00
docs: improve install/requirements and install/docker-compose (#13569)
* cleanup install docs * Apply suggestions from mmomjian's code review Co-authored-by: Matthew Momjian <50788000+mmomjian@users.noreply.github.com> * consequent wording simplifications * latest rewording of start/restart * Update requirements.md removed leftover newline --------- Co-authored-by: Matthew Momjian <50788000+mmomjian@users.noreply.github.com>
This commit is contained in:
pyorot
GitHub
parent
f180ae70f9
commit
364b717fde
3 changed files with 51 additions and 34 deletions
|
|
@ -8,9 +8,8 @@ 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.
|
||||
|
||||
### 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
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
|
|
@ -54,31 +52,37 @@ Optionally, you can enable hardware acceleration for machine learning and transc
|
|||
<CodeBlock language="bash">{ExampleEnv}</CodeBlock>
|
||||
</details>
|
||||
|
||||
- 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.
|
||||
|
||||
### Step 3 - Start the containers
|
||||
:::info Optional Features
|
||||
You can edit `docker-compose.yml` to add external libraries or enable hardware acceleration now by following [their guides](#setting-up-optional-features).
|
||||
:::
|
||||
|
||||
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`.
|
||||
## 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 this command:
|
||||
|
||||
```bash title="Start the containers using docker compose command"
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
:::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].
|
||||
This starts immich as a background service (per the `-d` flag), ensuring it restarts after system reboots or crashes (per the `restart` fields in `docker-compose.yml`).
|
||||
|
||||
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:
|
||||
:::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 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:
|
||||
|
||||
```
|
||||
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 container images can be deleted with the following command:
|
||||
|
||||
```bash title="Delete all obsolete container images"
|
||||
docker image 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
|
||||
|
|
|
|||
|
|
@ -8,11 +8,15 @@ Hardware and software requirements for Immich:
|
|||
|
||||
## Software
|
||||
|
||||
- [Docker](https://docs.docker.com/engine/install/)
|
||||
- [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 (or 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/compose/migrate/) and is no longer compatible with Immich.
|
||||
Immich requires the command `docker compose`; the similarly named `docker-compose` is [deprecated](https://docs.docker.com/compose/migrate/) and is no longer supported by Immich.
|
||||
:::
|
||||
|
||||
## Hardware
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue