[Tutorial] Immich remote video transcoding

[erkexzcx]

Description & Prerequisites

Decided to write this in order to help fellow users to transcode their library on remote server (e.g. gaming PC), where their immich server isn't powerful enough, or doesn't have required hardware acceleration.

In this example, immich server is the server that hosts your Immich instance on (basically docker-compose.yml contents). remote server is more powerful hardware, e.g. your gaming PC.

Prerequisites:

• Remote server has to be able to access your immich server directly.
• Remote server has to be able to access your ${UPLOAD_LOCATION} mountpoint/files directly. It means that users who don't store files in remote storage (e.g. via NFS) will have a hard time to set it up, but it's not a problem to me.

So before you begin - understand this if you are using local storage, you might need to mount it via SMB or NFS to your remote server. If you cannot do this - this guide tutorial will not work for you.

Procedure

Perform these steps on immich server:

1. Expose redis (ports: [6379:6379]) and database (ports: [5432:5432]) ports in your docker-compose.yml, so these 2 are accessible from the outside (so your remote server can access it).
2. Edit .env and add this variable: IMMICH_WORKERS_INCLUDE: 'api'
3. Restart your docker-compose.yml stack: docker compose down and docker compose up -d.

Now perform these steps on remote server:

1. Download docker-compose.yml, example.env (rename to .env) and hwaccel.transcoding.yml files. From docker-compose remove everything but immich-server and update how you mount your ${UPLOAD_LOCATION}, so it points to the same physical location as your immich server.
2. Edit .env and update DB password and DB name to match what's on your immich server. Additionally, add these variables: DB_HOSTNAME=<ip_of_immich_server> and REDIS_HOSTNAME=<ip_of_immich_server> and IMMICH_WORKERS_INCLUDE: 'microservices'.
3. Bring it up: docker compose up -d and see if no errors: docker logs -f immich_server (all should be green).

Now go back to Immich WebUI and configure hardware transcoding settings. My remote server has RX 7900 GRE, it supports AV1 encoding & decoding and hardware acceleration is powered by vaapi method, so I enabled it. Now go to jobs and press to transcode all your videos. Once it starts, run docker logs -f immich_server on your remote server to see if any errors (e.g. if your hardware acceleration is working). If no errors in red - congratulations, everything is working. :)

Depending on your use-case, you might want to revert the changes. Security & firewall aspects are out of scope for this tutorial.

[legalimpurity]

Awesome!

[lovelacecreativeco]

Thanks for this!

[Junod972]

thanks a looooooot. I will use these like right now. Because, I need to set up at least 3 workers on 3 machines. And, I am struggling like hell to do even the basic.
So, again, thanks a lot.

[biggt]

I love this but what I haven't seen is the ability to have the main server running both API and microservices AND THEN another machine running the microservices for all ML and transcoding needs.

Is it possible to do something like this:

IMMICH_WORKERS_INCLUDE: 'api,microservices'

Official documentation nor unofficial that I have found mentions the specifics of having multiple containers for microservices and ML

[erkexzcx]

Lol. Check out latest release 😅

AND THEN another machine running the microservices for all ML and transcoding needs.

It's getting there. AFAIK whole immich project is trying to become stateless, so you can even host in Kubernetes with various components and scale as you wish. 🙌 It's getting there, just wait.

[bo0tzz]

It's already there. All of this works just fine, you can run whatever components you want wherever you want.

[traktuner]

It's already there. All of this works just fine, you can run whatever components you want wherever you want.

@bo0tzz
Thats awesome!
Will this also get added to the docs like "remote machine learning"? I would really need this just for "remote transcoding"

[flipflower]

Would be great to combine these two, remote machine learning is working perfectly on my pc, would be great just to add an url to video transcoding (or any other type of heavy cpu task)

[bo0tzz]

@traktuner I think that's already covered in https://immich.app/docs/guides/scaling-immich/

[flipflower]

if i have machine learning already set up on my pc & working, how to point to it for transcoding videos?

[erkexzcx]

What?

[flipflower]

i have to recreate the machine learning docker on my pc?

[erkexzcx]

Yes

[DerHexer]

As I was struggling with the details on SMB mountings, I would like to add my results to this post in order to avoid this hassle for others. I'm using the external library function to bring my pictures into immesh (hence the two volumes):

in the .env file:
UPLOAD_LOCATION=immichvolume1

---

in the docker_compose:

[...]
services:
immich-server:
volumes:
- ${UPLOAD_LOCATION}:/usr/src/app/upload
- immichvolume2:/usr/src/app/external:ro
[....]
volumes:
immichvolume1:
driver_opts:
type: cifs
o: username=SMBUSERNAME,password=SMBPASSWORD,domain=SMBNAME
device: "//SMBIP/docker/immich-compose/library"
immichvolume2:
driver_opts:
type: cifs
o: username=SMBUSERNAME,password=SMBPASSWORD,domain=SMBNAME
device: "//SMBIP/photofolder/"
model-cache:

[jltdhome]

Anyway to change the default port of the DB to something else. My synology has that port bound to their services database?

[ToddH-ITPro]

Just like when you are setting up any other docker container, when you go to the ports section, you can change the left port (external) to anything, keeping the right port (internal) set to what the container is looking for. This is exactly what I do with many of my services that are all using similar ports.

As an example, my load balancer config has the following for hosts:ports

upstream immich_ml_containers {
   server prd-docker08:3003 max_fails=3 fail_timeout=60s;
   server prd-docker09:3003 max_fails=3 fail_timeout=60s;
#   server prd-docker13:3003 max_fails=3 fail_timeout=60s; ## main immich server # Disabled to ensure main server does not go down
   server lovo:3003 max_fails=3 fail_timeout=60s weight=2;
   #server dominator:3003 max_fails=3 fail_timeout=60s weight=2; #GPU - 3080 10GB
   #server dominator:3005 max_fails=3 fail_timeout=60s weight=2; #GPU - 970 4GB
   server dominator:3004 max_fails=3 fail_timeout=60s weight=8; #CPU
}

My docker-compose.yml file for immich-machine-learning on another host has the following:

    ports:
      - '3004:3003'

Just change the left to whatever you want. The right of : is wanting 3003 for machine learning container.

[kevin201]

Thank you. This is the best tutorial I've found on the subject.
I have a couple of questions:

My immich_server section in docker-compose.yml has this in it:

    depends_on:
      - redis
      - database

Should this be copied the remote docker-compose.yml too, or omitted?

You say "add this variable: IMMICH_WORKERS_INCLUDE: 'api'", presumably you mean "add this variable: IMMICH_WORKERS_INCLUDE = 'api'" (with an equals sign)?

[Metacowboy]

Somehow it stopped working for me after upgrade
Running Remote server on a PC and Client on MAC
Get permanent following error
[Nest] 7 - 04/13/2025, 8:08:39 AM LOG [Microservices:StorageService] Verifying system mount folder checks, current state: {"mountChecks":{"thumbs":true,"upload":true,"backups":true,"library":true,"profile":true,"encoded-video":true}}
immich_server | [Nest] 7 - 04/13/2025, 8:08:39 AM ERROR [Microservices:StorageService] Failed to read upload/encoded-video/.immich: Error: ENOENT: no such file or directory, open 'upload/encoded-video/.immich'
.
.
immich_server | microservices worker exited with code 1
But there is a encoded-video/.immich with permission read write all

Any sugestion where to look for a a way to get it back running ?

Thank you in advance

Server Version : 1.131.3
My composer file on Remote Immich
name: immich

services:
immich-server:
container_name: immich_server
image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
extends:
file: hwaccel.transcoding.yml
service: nvenc # set to one of [cpu, nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
volumes:
# Do not edit the next line. If you want to change the media storage location on your system, edit the value of UPLOAD_LOCATION in the .env file
- ${UPLOAD_LOCATION}:/usr/src/app/upload
- ${THUMB_LOCATION}:/usr/src/app/upload/thumbs
- ${ENCODED_VIDEO_LOCATION}:/usr/src/app/upload/encoded-video
- /etc/localtime:/etc/localtime:ro
env_file:
- .env
ports:
- '2283:2283'

restart: always
healthcheck:
  disable: false

immich-machine-learning:
container_name: immich_machine_learning
# For hardware acceleration, add one of -[armnn, cuda, openvino] to the image tag.
# Example tag: ${IMMICH_VERSION:-release}-cuda
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-cuda
extends: # uncomment this section for hardware acceleration - see https://immich.app/docs/features/ml-hardware-acceleration
file: hwaccel.ml.yml
service: cuda # cpu set to one of [armnn, cuda, openvino, openvino-wsl] for accelerated inference - use the -wsl version for WSL2 where applicable
volumes:
- model-cache:/cache
env_file:
- .env
restart: always
ports:
- '3003:3003'

volumes:
model-cache:
immich_upload:
driver: local
driver_opts:
type: cifs
o: username=metacowboy,password=soleyman,uid=501,gid=20,file_mode=0664,dir_mode=0775
device: "\METACATALINAPRO\IMMICHPhotos"

ENV-File Folder part
#The location where your uploaded files are stored
UPLOAD_LOCATION=W:
THUMB_LOCATION=W:\thumbs
ENCODED_VIDEO_LOCATION=W:\encoded-video

Immich host wie convret videos for

DB_HOSTNAME=192.168.8.100
REDIS_HOSTNAME=192.168.8.100
IMMICH_WORKERS_INCLUDE: 'microservices'

[kevin201]

I haven't been able to get it working with docker volumes. It works when I mount the host directories on the remote machine:

#External library
sudo mount -t cifs //10.0.101.156/Photos /home/myhome/mnt/photos -o "rw,username=mylogonuser,password=mysmbpword,uid=1000,gid=1000" 
#Upload location
sudo mount -t cifs //10.0.101.156/immich-library /home/myhome/mnt/library -o "rw,username=mylogonuser,password=mysmbpword"

#In the remote .env

UPLOAD_LOCATION=/home/myhome/mnt/library
TZ=Asia/Bangkok
IMMICH_VERSION=release
DB_PASSWORD=postgres
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
DB_HOSTNAME=10.0.101.156
REDIS_HOSTNAME=10.0.101.156
IMMICH_WORKERS_EXCLUDE='api'

#in the remote docker compose file:

volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
      - /home/myhome/mnt/photos:/photos

I also had to add the URL of the remote machine in the Admnistration, Settings, "Machine Learning Settings" section of the host machine settings:

http://10.0.101.156:3003

And I exposed the ports in the host docker compose file for machine learning:

immich-machine-learning:
    container_name: immich_machine_learning
    ports:
        - '3003:3003'

And the postgres service:

database:
    container_name: immich_postgres
    ports:
     - '5432:5432'

And redis:

redis:
    container_name: immich_redis
    ports:
     - '6379:6379'

[alextran1502]

@kevin201 make sure to mount those drive in /etc/fstab otherwise they don't get automatically mounted after restarting the server/vm

[kevin201]

Thank you, yes. I think you mean the fs tab on the remote. I'm actually only running the remote as a temporary measure while I populate the initial video encodes and thumbnails so I don't need to, but if it was permanent I certainly would. Any ideas why the docker volumes won't work?

[alextran1502]

I am not sure, I've never gone down that route. I've always mounted to a local path on host first before mount it to the docker containers