Understanding Files Custom Locations

[LucaBH]

Hi all.
Soon I'll deploy Immich on my server. Meanwhile I'm reading its documentation and I found some inconsistencies (at least what appeared to me) about the usage of the Files Custom Locations.

1. Env variables defined the the Files Custom Locations page aren't reported in the general Environment Variables page, so not sure if/how they're actually supported.
2. How they work is somehow obscure. Let me break it.
   • Without using them (therefore keeping just UPLOAD_LOCATION defined), everything is stored under this root folder. For instance, thumbs are stored to UPLOAD_LOCATION/thumbs/<userID> ... (supposing storage template is used).
   • Using them instead (therefore defining THUMB_LOCATION along with UPLOAD_LOCATION), thumbs seem getting stored in THUMB_LOCATION/<userID>, which potentially has anything to share, filesystem-wise, with the UPLOAD_LOCATION, as if the definition of this specific variable fully overloads the default storage behavior. If it's so, maybe it should be stressed in the documentation.
   • Most important, what happens to the originals folder? Without custom locations they are inside UPLOAD_LOCATION/library. But with such locations defined? As there's no dedicated variable, maybe UPLOAD_LOCATION takes a different role (i.e. root of originals only) if other env variables are defined? Documentation says nothing on it.

So please could you guys clarify the whole thing? Did I understand well or there's something I'm missing?

[bo0tzz]

1. The env vars from the guide are custom ones only used in the compose file. The application doesn't see them.

As there's no dedicated variable, maybe UPLOAD_LOCATION takes a different role (i.e. root of originals only) if other env variables are

exactly

[bo0tzz]

What's the actual error you're getting?

[LucaBH]

What's the actual error you're getting?

I'll get back to you asap (now I'm far from the PC).
Meanwhile let me give you some context (maybe I underestimated its impact): unprivileged LXC container in Proxmox, Ubuntu 24.04, /mnt/photos mounted in the container and hosted in the host on a ZSF dataset.
(I know that running Docker in LXC is discouraged, but since 1) the default installation went ok, and 2) error was about other folders than /data/library, I guessed that the failure was just a matter of wrong configuration by my side)

[LucaBH]

What's the actual error you're getting?

Here it is the error:

For reference, this is the .env:

and this it the yml:

[LucaBH]

Ok, my bad, I didn't set up correct permissions on the mounted folder (/mnt/photos) :(

Once fixed them (root:root), 'docker compose up' finishes, but I got a strange folders configuration on the filesystem: in ./ (the .env and .yml folder) a 'library' folder is created; and both ./library and /mnt/photos/app-lib have 'thumbs', 'encoded-video', 'profile' and 'backup' folders inside. No 'library' nor 'upload'.
And (related?) the immich_server container stays in 'starting' for a while before going back to 'restarting', and Immich webUI is unreachable.

I'm starting suspecting that's impossible to separate the library subfolder (where originals get stored) from the rest of the folder structure.

Am I right? Or am I playing wrong with configuration?

[LucaBH]

Keeping on experimenting, now taking the HDD out of the equation. The role of these custom locations, honestly, is obscure...

This .env file:

Produces the following folders tree:

'docker compose up' successfully terminates, but immich_server container falls back into restarting loop, and consequently the webUI cannot be reached.

Not sure what requirement they are for -- surely not the one I'm looking for (i.e. offloading the originals only to an HDD). An explanation would be really appreciated.