Immich running with hetzner storage box

[Blotz]

Using docker volumes, you can mount a remote storage such as hetzner storage box as your image and updating UPLOAD_LOCATION in .env. You need to specify the volume as external in docker compose. I had issues with SSHFS disconnecting, but CIFS is reliable. I'm sure NFS would also do great too. If you are using hetzner, and you are trying to mount a subaccount over CIFS, check out this blog for the commands. The official docs aren't very good with this part.

This makes for a pretty cheap self-hosted option, a VPS with lots of storage is expensive. Hetzner charges €3.84 for 1TB which is not bad.

[Blotz]

Update for anyone else trying the same as me. CIFS can hang/disconnect which causes immich to no longer work. I'm trying out mounting CIFS as hard. Hopefully that causes immich to crash/reboot which will cause docker to reconnect to the CIFS volume. This is getting janky LOL.

Edit: It did not work. immich wont crash and restart. it simply fails to read/write. Also it stops logging any errors

[brokeDude2901]

how about rclone ?

[SandiyosDev]

how about rclone ?

Bruh, not cold storage.

[brokeDude2901]

rclone works for GDrive and many more, I don't see why FUSE will not work with immich

[zoonderkins]

I have 500GB photos and I use both CIFS and Rclone mount (idrive-e2) with softlink
And you have to wait for 8 hours to let the immich docker really start.

[SandiyosDev]

considering this as well, that's pretty neat!

[YJ14]

This is not really working! I mounted the Storage Box and tried to add the /mnt/hetnzer to the .env in UPLOAD_LOCATION, doesn't work! I get errors and the server doesn't start.

[bencagri]

this works like a charm. 👍 awesome solution.

[MaexNi]

Can you please tell me how to configure fstab that this works?
I tried a lot of different things but always get the same error. My fstab looks like:

//u123456.your-storagebox.de/backup /mnt/storagebox cifs vers=3.0,iocharset=utf8,credentials=/etc/storagebox.credentials,uid=0,gid=0,file_mode=0777,dir_mode=0777 0 0

the mount works, but immich cannot write into the folder

[Nest] 6 - 07/24/2025, 10:01:59 PM ERROR [Microservices:StorageService] Failed to read upload/encoded-video/.immich: Error: ENOENT: no such file or directory, open 'upload/encoded-video/.immich' microservices worker error: Error: Failed to read "<UPLOAD_LOCATION>/encoded-video/.immich - Please see https://immich.app/docs/administration/system-integrity#folder-checks for more information.", stack: Error: Failed to read "<UPLOAD_LOCATION>/encoded-video/.immich - Please see https://immich.app/docs/administration/system-integrity#folder-checks for more information."

what is the correct uid and gid for this? I thought it should be 0 as everything runs as root

[Blotz]

Did you set your upload location in Immich correctly? If you arnt sure, enter the docker container using docker exec -it immich_server bash and verify that all the right folders are in ./uploads

[emanuelsan]

I also ran into this error after mounting an external volume to the Immich container.
The cause was the fact that Immich has a "system integrity" check which looks for these directories in the UPLOAD_LOCATION:

encoded-video/.immich 
originals/.immich 
thumbs/.immich 
profile/.immich 
library/.immich 
backups/.immich

With the default docker-compose setup, Immich creates them automatically. If it can't write (or the path is empty and it doesn't have permissions), you'll get the ENOENT error.
Solution on my end was to create the directories myself.

# base=/mnt/immich-library
# sudo mkdir -p "$base"/{upload,encoded-video,thumbs,profile,library,backups}
for d in upload encoded-video thumbs profile library backups; do
  sudo touch "$base/$d/.immich"
done

/mnt/immich-library is the directory I've mounted the Hetzner Storage Box via CIFS to my VPS on which I'm running Immich.

Hope this helps.

[styxlab]

Tried the same, storagebox connected via cifs and only library folder pointing to the storagebox but it does not work reliably. I am now trying hetzner volumes which are fast SSD disks (though more expensive).

[styxlab]

@emanuelsan I am using the docker-compose file provided by Coolify and changed only one line:

services:
  immich:
    image: 'ghcr.io/immich-app/immi'/mnt/storagebox/immich/immich-uploadsch-server:${IMMICH_VERSION:-release}'
    volumes:
      - '/mnt/storagebox/immich/immich-uploads:/usr/src/app/upload'
      - '/etc/localtime:/etc/localtime:ro

and mounted my storagebox to /mnt/storagebox. I also created the directories with

mkdir -p /mnt/storagebox/immich/immich-uploads

This is my current seutp, but I saw in the immich docs that you can directly mount your cifs volume in docker compose. I would try this method next time, as you do not need to worry about mounting the storage box to /mnt.

https://docs.immich.app/FAQ#how-can-i-mount-a-cifssamba-volume-within-docker

Let us know what you ended up with. I recommend to have at least 8 CPUS when you first upload your images. After that you can easily scale down to 4.

[emanuelsan]

Hey @styxlab, thanks for the pointers! Really appreciate you taking the time to help.

I’ve managed to get everything working smoothly now — Immich running on a Hetzner VPS with the library mounted to a Hetzner Storage Box via CIFS, all orchestrated through Coolify, like you.

I think I might have taken a longer route, though it's working fine now. I suspect your approach is cleaner/faster.

In any case, here’s the “Happy Path” that worked for me. I'll leave it here hoping it helps others:

---

Prerequisites:

1. Deploy a Hetzner VPS
2. Deploy a Hetzner Storage Box
3. Have Coolify running with an Immich resource deployed on the Hetzner VPS mentioned at (1) above

---

1. Install CIFS utilities and required modules on the VPS

Install cifs-utils and required dependencies on the Hetzner VPS host to enable mounting the Storage Box.
The raw Hetzner VPS was missing some libraries that prevented the CIFS mount.

sudo apt update && sudo apt install -y cifs-utils keyutils libcap-ng0 libtalloc2 libwbclient0 libgnutls30
sudo apt install -y linux-modules-extra-$(uname -r)
sudo modprobe nls_utf8 && sudo modprobe cifs

---

2. Create an SMB credentials file

Store your Hetzner Storage Box credentials in a file to avoid typing them in plain text.

sudo bash -c 'cat <<EOF > /root/.smbcredentials
username=u123456-exmpl
password=your-storagebox-password
EOF
chmod 600 /root/.smbcredentials'

---

3. Mount the Hetzner Storage Box to the VPS

Still inside the VPS host, mount the Storage Box to /mnt/immich-library.

sudo mkdir -p /mnt/immich-library
sudo mount -t cifs //<storagebox> /mnt/immich-library \
  -o credentials=/root/.smbcredentials,vers=3.0,iocharset=utf8,uid=1000,gid=1000,file_mode=0664,dir_mode=0775,noperm,noserverino

Replace <storagebox> with the address of your Hetzner Storage Box. It should be in the format:
//u999999-sub1.your-storagebox.de/u999999-sub1

Verify the mount:

df -h /mnt/immich-library
touch /mnt/immich-library/.write-test && ls -la /mnt/immich-library

---

4. Update the Immich docker-compose file in Coolify

In the Coolify resource editor for Immich, click on "Edit Docker Compose" button:

• Add an init service to create Immich’s folder structure on the mounted volume.
• Change the mounted volume of the immich service to point to /mnt/immich-library.
• Update the UPLOAD_LOCATION environment variable.

services:
  init-upload-tree:
    image: alpine:3.20
    volumes:
      - /mnt/immich-library:/target
    command: >
      sh -lc 'for d in upload encoded-video thumbs profile library backups;
      do mkdir -p "/target/$d" && touch "/target/$d/.immich"; done;'
    restart: "no"

  immich:
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - /mnt/immich-library:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
    environment:
      - UPLOAD_LOCATION=/usr/src/app/upload
    depends_on:
      init-upload-tree:
        condition: service_completed_successfully

[... leave the rest untouched]

• Save the updated compose file.

---

5. Redeploy in Coolify

• Update the persistent storage path in Coolify for the "Immich" service to /mnt/immich-library. To do this, go to "Persistent Storage" → "Source Path" input field on the first item in the list (called "Immich"). Click "Update"
• Redeploy the resource (Click "Restart" or "Deploy").

✅ Once deployed, uploads and thumbnails are written directly to the Storage Box, and everything runs reliably.

---

Regarding CPU usage

After setting this up, it all works fine and I didn't encounter any hiccups. I run Immich on a 4-core, 8GB RAM VPS but I uploaded videos and photos incrementally, 10-20 at a time and it worked flawlessly so far.

[samyouel]

hey @emanuelsan, you are probably using a CX33 from hetzner?
the video upload for large files somehow doesn't seem to work for me.
I keep getting sun.net.ConnectionResetException: Connection reset Errors when uploading files larger than 100mb.
I'm not proxying through Cloudflare anymore, but the issue still persists.

Did you notice something similar or how is your setup that this works for you?
Thanks!

[samyouel]

#24501
actually a similar issue was described here, I had to change my reverse proxy in coolify to caddy, otherwise the uploads kept running into the default 60s timeout of traefik. Extending the timeout like described here didn't really work for me sadly...

[emanuelsan]

Hey Samouel,

I'm using a CPX31 server. 4 vCPUs, 8GB of RAM.

I did encounter something similar with large video files. I usually resolve it by uploading via a fast Wifi (so the upload duration is shorter) so I think you're on to something regarding the timeout. I uploaded 500MiB videos this way, without problems.

I've also encountered some issues when connecting the mobile app on a new phone without using a Wifi connection (on the mobile internet connection). The app would request a lot of thumbnails from the server and it would freeze. Now that you mentioned a connection timeout, it might be related.