Immich - vincios/rpi-setup GitHub Wiki

Install

Warning

Immich requires docker.

Follow the official documentation.

See this .env example as reference:

✨ Click to see the code

# You can find documentation for all the supported env variables at https://immich.app/docs/install/environment-variables

# The location where your uploaded files are stored
UPLOAD_LOCATION=/media/snas/Immich-Library
# The location where your database files are stored
DB_DATA_LOCATION=./data/postgres

# To set a timezone, uncomment the next line and change Etc/UTC to a TZ identifier from this list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
TZ=Europe/Rome

# The Immich version to use. You can pin this to a specific version like "v1.71.0"
IMMICH_VERSION=release

# Connection secret for postgres. You should change it to a random password
DB_PASSWORD=postgres

# External libraries
# EXT_LIB=/external/lib/path

###################################################################################
# Split workers configuration
# See:
#   - https://immich.app/docs/administration/jobs-workers
#   - https://github.com/vincios/rpi-setup/wiki/Immich#outsource-microservices-and-machine-learning-computation
###################################################################################
# Host Machine: Set this to disable microservices
# IMMICH_WORKERS_INCLUDE=api

# Worker Machine: Set this to disable web server
# IMMICH_WORKERS_EXCLUDE=api

###################################################################################
# The values below this line do not need to be changed
###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Outsource microservices and machine learning computation

Immich workers approach allows you to setup multiple worker instances on different remote hosts and let the server outsource computation to them.

It uses redis to issue jobs to the workers (microservices and machine learning)

Important

Since the docker configuration must coincide between the server and microservices instances, you should fully configure your docker-compose.yml/.env files (including the definition of external library volumes) on the host machine (server) before to clone them to the worker machine.

Important

The UPLOAD library and (eventually) external libraries must be accessible on both the server and the worker hosts, so make sure to share them from a common source (e.g. a NAS).

On the server host:

On the docker-compose.yml file, expose the ports on both the database and the redis services

Take the default ports form the official documentation.

Example:
```
redis:
  # ...
  ports:
    - 6379:6379

database:
  # ...
  ports:
    - 5432:5432
```

Disable the microservices worker: in the .env file uncomment the line IMMICH_WORKERS_INCLUDE=api

...
# Host Machine: Set this to disable microservices
IMMICH_WORKERS_INCLUDE=api

# Worker Machine: Set this to disable web server
# IMMICH_WORKERS_EXCLUDE=api

Warning

Make also sure that IMMICH_WORKERS_EXCLUDE=api is commented

Tip

You can leave the microservices worker enabled if you want to make a computation cluster. Each instance will pick up some waiting jobs.

Run all the services
```
$ docker compose up -d
```

Stop the immich-machine-learning service

$ docker compose down immich-machine-learning

Note

You cannot leave the immich-machine-learning service running (as well as the microservices) because, on the frontend, you can set only one Machine Learning url.

[Maybe it could be possible because, theoretically, also the ML Jobs queue is managed with redis, and the endpoint url is used only for the search queries - NEED TO INVESTIGATE THIS].

On the worker host:

Copy the docker-compose.yml and .env files from the server to the worker host

Tip

If you can SSH your server, you can use SCP to transfer files.

In docker-compose.yml:

rename the immich-server service to immich-microservices
rename the container_name to immich_microservices
remove redis and database services and ports

...
services:
- immich-server:
-   container_name: immich_server
-   ...
-   ports:
-     - 2283:3001
-   depends_on:
-     - redis
-     - database
+ immich-microservices:
+   container_name: immich_microservices
...

- redis:
-   container_name: immich_redis
-   ...
-   restart: always

- database:
-   container_name: immich_postgres
-   ...
-   restart: always

On the docker-compose.yml expose the port on the immich-machine-learning service

Take the default port form the official documentation.

Example:
```
immich-machine-learning:
  # ...
  ports:
    - 3003:3003
```
(Optional) Enable hardware acceleration (transcoding/machine learning).

On the .env file:

Add DB_HOSTNAME and REDIS_HOSTNAME variables. Set them to the server's IP

# Remote server configuration
DB_HOSTNAME=192.168.1.X
REDIS_HOSTNAME=192.168.1.X

Disable the web server worker: uncomment the line IMMICH_WORKERS_EXCLUDE=api

...
# Host Machine: Set this to disable microservices
# IMMICH_WORKERS_INCLUDE=api

# Worker Machine: Set this to disable web server
IMMICH_WORKERS_EXCLUDE=api

Warning

Make also sure that IMMICH_WORKERS_INCLUDE=api is commented

⚠️ Important! Mount the UPLOAD LIBRARY and (eventually) EXTERNAL LIBRARIES exactly on the same paths as defined in the volumes section of the docker-compose.yml file
- For example, if you have defined your volumes like this
```
# UPLOAD_LOCATION=/media/nas/immich
# LIBRARY_LOCATION=/media/nas/photo

immich-microservices:
  # ...
  volumes:
    - ${UPLOAD_LOCATION}:/usr/src/app/upload
    - ${LIBRARY_LOCATION}:/mnt/media/library:ro
```
  Make sure that
  1. on the host, the UPLOAD library is correctly mounted into the /media/nas/immich folder and the external library is correctly mounted into the /media/nas/photo folder
  2. into the docker container, the libraries are correctly visible
    
    i.e. connect to the docker container and check with ls that folder and files are correctly visible
```
$ docker exec -it immich_microservices /bin/bash
# ls /usr/src/app/upload
# ls /mnt/media/library
```
Pull the containers
```
$ docker compose pull
```
Start immich-microservices and immich-machine-learning services
```
$ docker compose up -d
```

Tip

Run docker compose logs -f to have some feedback from the logs

Note

In some circumstances, the immich_microservices instance could several minutes to start, so don't move to the next step until you see the line

LOG [Microservices:Bootstrap] Immich Microservices is running [...] [PRODUCTION]

On the frontend:

Important

Note that also the frontend settings (Administration > Settings page) are sent to the microservices via redis when you click on a Save button.

So, before to change any settings make sure that microservices/machine learning services are running on the worker host.

Make sure that server settings are applied also to the worker's microservices
1. Go to the Administation -> Settings page
2. Export settings as JSON and re-import them
3. Check on the worker's logs that settings was updated
Update the Machine Learning URL in Settings

Now you can start any Job / upload assets / import external libraries and the computation will be automatically picked up by the workers.

fail2ban setup

Here

Immich tools

immich-go

immich-go is an alternative to the immich-CLI command.

To install/update simply download the latest release and extract.

$ wget https://github.com/simulot/immich-go/releases/latest/download/immich-go_Linux_arm64.tar.gz
$ tar -zxvf immich-go_Linux_arm64.tar.gz

Tip

On the first run the tool stores the Server URL and the API key into a configuration file (default $HOME/.immich-go/immich-go.json if not specified with the -use-configuration parameter). So, -server and -key can be omitted for the next runs.

Deprecated

[1.105 and below] Outsource microservices and machine learning computation

Immich uses redis to issue jobs to the workers (microservices and machine learning), so you can setup multiple worker instances on different remote hosts and let the server outsource computation to them.

Important

The UPLOAD library and (eventually) external libraries must be accessible on both the server and the worker hosts, so make sure to share them from a common source (e.g. a NAS).

On the server host:

On the docker-compose.yml file, expose the ports on both the database and the redis services

Take the default ports form the official documentation.

Example:
```
redis:
  # ...
  ports:
    - 6379:6379

database:
  # ...
  ports:
    - 5432:5432
```
Run all the services
```
$ docker compose up -d
```
Stop the immich-machine-learning and (optional) the immich-microservices services
```
$ docker compose down immich-microservices immich-machine-learning
```

Tip

You can leave the immich-microservices service running if you want to make a computation cluster. Each instance will pick up some waiting jobs.

The same cannot be made for the immich-machine-learning because, on the frontend, you can set only one Machine Learning url. [But could be possible because, theoretically, also the ML Jobs queue is managed with redis, and the endpoint url is used only for the search - NEED TO INVESTIGATE THIS].

On the worker host:

Copy the docker-compose.yml and .env files from the server to the worker host

Tip

If you can SSH your server, you can use SCP to transfer files.

Remove immich-server, redis, and database services from docker-compose.yml
On the docker-compose.yml expose the port on the immich-machine-learning service

Take the default port form the official documentation.

Example:
```
immich-machine-learning:
  # ...
  ports:
    - 3003:3003
```
(Optional) Enable hardware acceleration (transcoding/machine learning).
On the .env file, add DB_HOSTNAME and REDIS_HOSTNAME variables. Set them to the server's IP
```
# Remote server configuration
DB_HOSTNAME=192.168.1.X
REDIS_HOSTNAME=192.168.1.X
```
⚠️ Important! Mount the UPLOAD LIBRARY and (eventually) EXTERNAL LIBRARIES exactly on the same paths as defined in the volumes section of the docker-compose.yml file
- For example, if you have defined your volumes like this
```
# UPLOAD_LOCATION=/media/nas/immich
# LIBRARY_LOCATION=/media/nas/photo

immich-microservices:
  # ...
  volumes:
    - ${UPLOAD_LOCATION}:/usr/src/app/upload
    - ${LIBRARY_LOCATION}:/mnt/media/library:ro
```
  Make sure that
  1. on the host, the UPLOAD library is correctly mounted into the /media/nas/immich folder and the external library is correctly mounted into the /media/nas/photo folder
  2. into the docker container, the libraries are correctly visible
    
    i.e. connect to the docker container and check with ls that folder and files are correctly visible
```
$ docker exec -it immich_microservices /bin/bash
# ls /usr/src/app/upload
# ls /mnt/media/library
```
Start immich-microservices and immich-machine-learning services
```
$ docker compose up
```

Tip

Run without -d so you can have some feedback from the logs

Note

In some circumstances, the immich_microservices instance could several minutes to start, so don't move to the next step until you see the line

LOG [ImmichMicroservice] Immich Microservices is listening on http://[::1]:3002

On the frontend:

Important

Note that also the frontend settings (Administration > Settings page) are sent to the microservices via redis when you click on a Save button.

So, before to change any settings make sure that microservices/machine learning services are running on the worker host.

Make sure that server settings are applied also to the worker's microservices
1. Go to the Administation -> Settings page
2. Export settings as JSON and re-import them
3. Check on the worker's logs that settings was updated
Update the Machine Learning URL in Settings

Now you can start any Job / upload assets / import external libraries and the computation will be automatically picked up by the workers.

Immich - vincios/rpi-setup GitHub Wiki

Install

Outsource microservices and machine learning computation

fail2ban setup

Immich tools

immich-go

Deprecated

[1.105 and below] Outsource microservices and machine learning computation

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️