[HOW-TO] Immich: How to Change Your Immich Upload Directory and Other Useful Tips

[vhsdream]

Immich in an LXC

Love Immich? Hate Docker? Me too! That's why I wanted a Proxmox Helper Script for the best open-source, self-hosted photo management software to ever exist.

So the script is here, and it seems to work, and it's huge and kind of complex. Let's go over what the script CAN do and what it CANNOT do.

✅ Can do

• Install Immich, as an unprivileged (default) or privileged LXC.
• Setup hardware-accelerated transcoding (QuickSync/VAAPI) if you have a modern Intel CPU/iGPU AND if you have made the proper modifications to your Proxmox host (not covered in this guide). All you need to do is turn this on in the Immich Settings panel.
  • (It might also be able to do transcoding (VAAPI) with an AMD CPU/iGPU?).
• Setup hardware-accelerated machine-learning (Smart Search, Facial Recognition) with OpenVINO, if you have a compatible Intel CPU/iGPU.

🚫 Cannot Do

• Setup hardware-accelerated transcoding or machine-learning with NVIDIA/AMD/Rockchip GPU/APUs. Perhaps subject to change.
• Setup a custom Immich media upload folder that differs from /opt/immich/upload.
• Your laundry or your taxes.

Since so far we've been receiving feedback that the major problem people are having is related to using a different upload folder (with good reason!), this guide is mainly geared towards attempting to demystify that part.

📁 The upload Folder

It's located by default in /opt/immich/upload, on the same disk as the LXC itself. Definitely not ideal, since you're gonna have to continuously increase the size of the disk as you add more media. I'd wager that pretty much all of us use some kind of NAS, which is likely on completely different disks, and that's where we want to store our Immich uploads.

It defaults to where it does because there are many different ways to configure storage on Proxmox, and the script is unable accommodate them as well as properly setup permissions in each use case. So this is left up to you to figure out. That being said, this guide is not going to cover how to properly mount a network share in your LXC, aside from the fact of whether you should choose to create an unprivileged LXC or a privileged LXC.

❓ Choose Privileged if...

• You understand and accept the security risks of doing so. Not going into that here.
• You already have privileged LXCs with mounted external shares and you know how they work.
• You want more of an "Easy Mode" for ensuring the immich user can write to the share.

❔ Choose Unprivileged (default and recommended) if...

• You know how to edit the LXC configuration file for Immich with UID and GID mapping configs.
• You know how to add bind mounts to the LXC configuration file.
• You are comfortable with modifying /etc/subuid and /etc/subgid entries on your Proxmox host.

Needless to say, regardless of the path you choose, you should have this figured out before proceeding. But to be a good sport and to get you started, I'll say you need to learn about how unprivileged LXCs operate in relation to the host, and how to leverage that to be able to mount a writable share in your Immich LXC. Try this writeup for a good starting point. And now, the GUIDE.

⚙ Changing the Immich upload directory in your Immich LXC

1. Stop Immich services
   systemctl stop immich-web immich-ml
2. Edit your Immich .env file (/opt/immich/.env) to reflect your chosen mount point
   nano/vi /opt/immich/.env
   Look for IMMICH_MEDIA_LOCATION and change it to the path of your bind mount.
   For example, say your bind mount is at /mnt/immich. Do this:

IMMICH_MEDIA_LOCATION=/mnt/immich

Save and close the file.

3. Copy all folders from the old upload directory to the new one, especially if you already have uploaded data. This is the easiest method, and it also proves that at least the root user can write to the folder. Even if you haven't uploaded data, there are files in each of those folders that must also be present for this to work.
   cp -a /opt/immich/upload/* /mnt/immich (or whatever your location is)
   You want the folder structure to look like this:

root@immich-dev:~# tree -a -L 1 /mnt/immich/
/mnt/immich/
├── backups
├── encoded-video
├── library
├── profile
├── thumbs
└── upload

And within each of those dirs there should be an .immich file, and potentially a folder with a long alphanumeric name which is your user ID, if you have existing uploaded content.

4. Recreate some symlinks. This is the step I was missing for those who were having issues. I didn't think of it because I have a slightly different setup (which I'll explain below).

Delete these symlinks:

rm /opt/immich/app/upload
rm /opt/immich/app/machine-learning/upload

Recreate them so they point to your new location:

ln -sf </mnt/immich> (or whatever your location is) /opt/immich/app/upload
ln -sf </mnt/immich> (or whatever your location is) /opt/immich/app/machine-learning/upload

So the folders should look like the below:

root@immich-dev:/opt/immich# tree -a -L 1 app/ app/machine-learning/
app/
├── bin
├── dist
├── geodata -> /opt/immich/geodata
├── LICENSE
├── machine-learning
├── node_modules
├── package.json
├── package-lock.json
├── resources
├── start.sh
├── upload -> /mnt/immich
└── www
app/machine-learning/
├── ann
├── immich_ml
├── ml_start.sh
├── ml-venv
└── upload -> /mnt/immich

5. Confirm ownership of the Immich folder in case it's changed.
   chown -R immich:immich /opt/immich

6. Restart Immich services and tail the web log, then go check out your Immich feed and open an image.

systemctl start immich-ml immich-web
tail -f /var/log/immich/web.log

You need to check Immich because if you messed up or skipped the symlink thing, if you only check the log things will seem fine. As soon as you try to look at your timeline (all thumbnails blurred) or open a photo (it won't load), then you'll see the problem.

7. Once you are convinced it's all working (maybe upload a new photo), then you can delete the previous upload folder.
   rm -rf /opt/immich/upload

That should be it.

📝 A Note About Updating

During the update process, the script deletes everything in the /opt/immich/app/ directory, including those symlinks. But they get recreated, using the information from your .env, where IMMICH_MEDIA_LOCATION will point to your current upload directory! So you do not need to recreate anything yourself.

🚀 Advanced Settings

I mentioned earlier that my setup is a bit different, which caused me to overlook the symlink step. I actually have not changed IMMICH_MEDIA_LOCATION in my .env file. Instead I made an additional symlink from /opt/immich/upload/upload to my bind mount. I did this because I prefer to store the thumbnails, encoded videos and other data on the LXC (for the responsiveness and speed), while storing the photos themselves on the NAS. So far this has worked out for me, but keep in mind that if you want to do this, thumbnail and encoded video data do take up space on your LXC disk, so you'll have to make sure you increase your LXC disk size accordingly. You can also customise this to your liking, for example create another symlink for /opt/immich/upload/backups to your bind mount, to store the DB backups on your NAS (I might do this myself).

Steps (Photo files only, as an example)

1. **If you have any existing data in the /opt/immich/upload/upload folder, you better copy/move it to your bind mount location! And make double-certain that your destination has a .immich file (you can simply create an empty one if needed).

2. Delete the /opt/immich/upload/upload dir, leaving the others intact.
   rm -r /opt/immich/upload/upload

3. Create the symlink(s) and restore ownership

ln -sf </media/photoLibrary> (or whatever) /opt/immich/upload/upload
chown -R immich:immich /opt/immich

Looks like this:

root@immich:~# ls -l /opt/immich/upload/
total 11
drwx------ 2 immich immich 17 Jun  9 03:00 backups
drwx------ 3 immich immich  4 May 19 10:16 encoded-video
drwx------ 2 immich immich  3 May 19 09:39 library
drwx------ 3 immich immich  4 May 19 09:53 profile
drwx------ 3 immich immich  4 May 19 09:52 thumbs
lrwxrwxrwx 1 immich immich 20 May 30 16:58 upload -> /media/photoLibrary/

OK, that's all folks! If you think anything in this guide can be made more clear and/or explicit, or if you find any errors, please let me know and I will fix 👍🏼

[subtleslander]

Hi there, thanks for the excellent guide! I'm encountering an issue at Step 6:

ERROR [Microservices:StorageService] Failed to read /mnt/immich/encoded-video/.immich: Error: EACCES: permission denied, open '/mnt/immich/encoded-video/.immich'

Any idea on a solution? It doesn't seem to be permissions related, but at the same time the language does suggest as much.

[vhsdream]

Hi @subtleslander - it certainly does appear to be permissions-related. The first thing you should try is to change the ownership of the mount point - if your LXC is privileged then this should do it:

chown -R immich:immich /mnt/immich

If your LXC is unprivileged then you have more work to do, and it generally involves modifying the LXC config file, which is beyond the scope of this how-to.

[fbloemhof]

To complete my migration I also needed to import my database backup. After making my files available using the above how-to (partly) I did the following to restore the database of my Docker setup to the LXC installation.

Warning

Make sure you have backups in place and are working on the correct system etc. No warranty for the steps below.

1. Stop Immich

systemctl stop immich-web immich-ml

2. To make sure I got a fresh start:

# drop the existing database
sudo -u postgres psql -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'immich';"
sudo -u postgres psql -c "DROP DATABASE immich;"

# recreate the database with correct collation
sudo -u postgres createdb -O immich --locale=en_US.UTF-8 --template=template0 immich

3. Locate the last backup and restore it:

# set the data location and find the most recent backup
datalocation=/mnt/immich 
latest_backup=$(find $datalocation/backups/ -name 'immich-db-backup-*.sql.gz' -type f -printf '%T@ %p\n' | sort -n | tail -n1 | cut -d' ' -f2-)

# restore the backup
gunzip --stdout $latest_backup \
| sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
| sudo -u immich psql --dbname=immich --username=immich

4. Because the LXC script uses other users, we need to change the ownership and the priviliges

# reassing owner and permissions
sudo -u postgres psql -c "
ALTER DATABASE immich OWNER TO immich;
GRANT CONNECT, CREATE ON DATABASE immich TO immich;
REVOKE CONNECT ON DATABASE immich FROM PUBLIC;
"

5. Start Immich and monitor the logfile

systemctl start immich-ml immich-web
tail -f /var/log/immich/web.log

To list the databases and the privileges:

sudo -u postgres psql -c "\l"

I had some minor issues with differences between permissions of the postgres vs immich user, you might need to change that in the commands. Make sure you execute every line one by one to stay in control.

[KatherineTealeaf]

Hi

Thanks a lot for the amazing guide. I notice that when immich is creating files it creates them readable only by the immich user. How do I get it to automatically create the files so that they are readable by the group/all?

[vhsdream]

Hi @KatherineTealeaf - I appreciate the kind words. Normally in Proxmox, especially with an unprivileged LXC, that kind of thing is determined by the host settings.

Can you describe how your storage is configured on your host, primarily these details:

• Original location of storage (directly on Proxmox host, on a NAS, etc)
• Filesystem used (SMB/CIFS, NFS, ZFS, etc)
• How it's mounted in Proxmox (in /etc/fstab, in /etc/pve/storage.cfg, somewhere else)
  • then please provide the configuration details for this.

As an example, I'm storing my photos on a NAS that's running as a VM on Proxmox, with the disks passed through so the VM has control of them. I'm using SMB/CIFS to mount the share on my host, and I used Proxmox's storage UI to configure it. Here is how the entry in my /etc/pve/storage.cfg looks:

cifs: media
        path /mnt/pve/media
        server <ip-address>
        share storage
        content iso
        options uid=1000,gid=2222,file_mode=0660,dir_mode=0775
        prune-backups keep-all=1
        username <whatever>

Important to note is the 'options' part, where I added file_mode and dir_mode settings to ensure that when it's mounted in my LXC, the permissions will be appropriate. In my Immich LXC, files are readable and writable by the user and group as a result.

[wtangofoxtrot]

Running into DB restore issues, anyone else see it ? I followed the above steps to recreate the immich db and get the following when I attempt a restore:

$ gunzip --stdout "/mnt/immich/backups/immich-db-backup-1751156950651.sql.gz" \
| sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
| sudo -u postgres psql --dbname=immich --username=immich
...
COPY 59511
ERROR:  relation "public.face_search" does not exist
...
invalid command \N
invalid command \N
...
ERROR:  syntax error at or near "3038832"
LINE 1: 3038832 Vila 1.56654 42.53176 AD 03  2024-11-04 Encamp
        ^

[vhsdream]

@wtangofoxtrot Is your Immich DB dump that you are attempting to restore from different installation, like a Docker install?

If so, does that Docker install use the same Vector extension? It used to be pgvecto.rs now it's VectorChord (vchord).

[wtangofoxtrot]

Also pardon my ignorance but where does /opt/immich/app/machine-learning/upload reside in the docker setup that one is migrating from ? The only upload folder I know of is /usr/src/app/upload in the docker setup which maps to /opt/immich/app/upload here however I dont see where /opt/immich/app/machine-learning/upload resides on the docker setup as created using the official compose file https://github.com/immich-app/immich/blob/main/docker/docker-compose.yml

[vhsdream]

@wtangofoxtrot The LXC installation is not a 1:1 of the Immich docker setup. It's cobbled together from a few different sources. I believe that if you do not have the symlink in the machine-learning folder then machine-learning will fail.

[TLauzen]

For your advanced setup wouldn't it make more since to place upload/library on the NAS instead of upload/upload?