New Docker Compose Builder

[bo0tzz]

We've just released a new tool to build a docker-compose.yml for Immich! You can find it at https://immich.app/docker-compose-builder.

The reason we built this is to try and simplify the process of installing Immich, especially when needing customizations beyond the default compose file that we include in the repository. Using features like hardware acceleration and external libraries, or customizing the installation in various other ways, has always required manual edits based on snippets that are scattered throughout the docs. Along with the separate .env file which has proven unfamiliar to many self-hosters, this has caused plenty of confusion and trouble. The new tool aims to codify these nuances in a way that's easy to use, giving you a single file that's ready to go.

Please give it a try and let us know how it goes! Is it easy and intuitive to use? Does the generated file work properly for you? Are there any features you're missing?

[Yann-P]

Awesome!

[fast-facts]

If possible, a really useful feature would be for the url to adjust with the setting overrides. That way we can bookmark it and if the docker compose ever changes, we can quickly go to the link and copy the new yml.

[bo0tzz]

A sharing feature is something we had in mind when we first started building this, I kinda just didn't get around to adding it yet.

[bo0tzz]

Sharing is now added!

[meyerrj]

A few things I think that would be nice for advanced options:

• Support for external postgresql databases, using DB_URL
• Trusted proxies

Also with databases, allow for postgresql version selection from known compatible releases.

It defaults to 14, and postgres:18-vectorchord1.1.1-pgvector0.8.5 appears to be the latest version that is provided.

https://github.com/immich-app/base-images/pkgs/container/postgres

[bo0tzz]

An external db is already supported. Trusted proxies seems to me like it’s not much different from most other env vars, and I’m reluctant to start listing out all of those in the builder.

[meyerrj]

Understandable. It was more suggestions for some advanced options if the tool happens to build out that far. :)

[Tubare]

Intel OpenVINO (WSL2) missing /dev/dri on newer Intel products with only /dev/dxg

For the machine learning component, I selected Intel OpenVINO (WSL2). The configuration file includes the following device mappings:

yaml
devices:

• /dev/dri:/dev/dri
• /dev/dxg:/dev/dxg
  However, after enabling WSL on some newer Intel products, only /dev/dxg is available and /dev/dri is missing. I am using an Intel Ultra 225 with integrated graphics only.

It would be great if this issue could be handled. Thanks!

[bo0tzz]

I don't entirely follow, is this something missing in the builder or your system not having a device? The builder matches what we currently have in https://github.com/immich-app/immich/blob/main/docker/hwaccel.ml.yml#L51-L54, so if that doesn't work then this is a broader issue and should probably be tracked elsewhere.

[Tubare]

Thanks for the clarification. This is not a missing device mapping in the builder — the issue is that /dev/dri does not exist on my system at all.

I am using an Intel Core Ultra 225 with integrated graphics only, running Windows 11 with WSL2. On this newer Intel platform, WSL2 exposes the GPU through /dev/dxg, but there is no /dev/dri device:

$ ls /dev/dxg
/dev/dxg

$ ls /dev/dri
ls: cannot access '/dev/dri': No such file or directory

As far as I understand, this is expected with the newer WSL2 GPU-PV architecture, where the Windows GPU is exposed to Linux through /dev/dxg rather than the traditional Linux /dev/dri interface.

For now, I have simply commented out the following line from the configuration:

# - /dev/dri:/dev/dri

and kept:

- /dev/dxg:/dev/dxg

Interestingly, OpenVINO hardware acceleration for the machine learning component works correctly with this configuration. I have tested it and confirmed that the ML workloads are actually using the Intel integrated GPU.

However, I have not yet found a way to get hardware-accelerated video transcoding working on this system. So at the moment, ML hardware acceleration works, but video transcoding hardware acceleration does not.

This makes me wonder whether the video transcoding side has an additional dependency on /dev/dri (for example, VA-API), while OpenVINO can work directly through the WSL2 /dev/dxg path.

[bo0tzz]

#31253

[open-rais]

Great tool! Really usefull for new users! As feedback, I think that "None" option on ML should fully disable (removing) the container for low end instances where you want to fully disattach the ML service and run it on other machine

[bo0tzz]

An option to disable ML has now been added.

[Janka55]

Awesome! I just learned about this project through AI, and it helped me get it deployed locally right away.

[Glideh]

Great tool. I didn't see much alike until now and it's really usefull to keep reference up to date.

One thing to improve maybe:

• When you need to copy only some config lines, sometime it seems to include the line numbers, example:

    image: ghcr.io/immich-app/immich-machine-learning:v3-openvino
24	
    volumes:
25	
      - model-cache:/cache
26	
      - /dev/bus/usb:/dev/bus/usb
27	

[bo0tzz]

What browser are you using/how are you copying etc? I can't reproduce this, and the code block element shouldn't allow it either

[Glideh]

I'm using Brave on Ubuntu, and I just noticed it only happens with the X clipboard (middle click paste).
Maybe we can't really control anything with that, I see there is already a user-select: none on the line number CSS so...

[HackintoshwithUbuntu]

Looks great! One suggestion from me would be to add an option to specify volumes to mount - this would help when migrating from existing nas setups or other already stored images. I believe that volumes mounted need to be mounted within the /mnt/media directory inside the container as read-only (:ro).

"Volume Mount" probably isn't the most intuitive name for new users...

[HackintoshwithUbuntu]

I didn't notice that, nice! I initially thought that eye icon was to hide something so just ignored it, that might just be me though (I can't really think of any better icon to put there instead either)

[bo0tzz]

Yeah I agree, the button could be clearer but I also don't fully know how to pull that off.

[HackintoshwithUbuntu]

Maybe a similar blue button placed beside the download one (or potentially placed on the left side of screen above the actual settings) that says "Show advanced settings"? The tradeoff being that things start becoming more text heavy.

[bo0tzz]

It should be a lot clearer now.

[HackintoshwithUbuntu]

Beautiful work!

[headtr1ck]

Would it be possible to add a little copy-pastable script to run on the server which discoves HW capabilities?
Maybe in a little ❓next to the input.

[bo0tzz]

I think that would be a whole different project, IMO it doesn't have much to do with this builder.

[headtr1ck]

Fair enough

[garvageart]

This tool is lovely, thank you! I used it to update my docker-compose.yml to add some Intel hardware accelerated stuff.

A small improvement to add I think would be to show an option to show a live diff to show what has changed compared to the original/base compose.

[bo0tzz]

Ooh very shiny, I'll have a look at what's possible.

[bo0tzz]

Added!

[garvageart]

Beautiful, thank you! Works great :)

[tomelfring]

Just started with Immich, this tool definitely helped me generating an starting Docker compose file.

One issue I found, when checking rootless, there's a small issue with the machine-learning image.
According to #25447 (comment) it's missing 2 mandatory file mounts (/.cache and /.config).

[bo0tzz]

Those mounts are no longer necessary. The canonical file to compare to is https://github.com/immich-app/immich/blob/main/docker/docker-compose.rootless.yml#L52-L53

[tomelfring]

Weird.. Without those mounts I've got the same error as in that issue. Running a face detection failed on my side.

[bo0tzz]

Woops, the container-side change for that hasn't actually been released yet 😅

[Zero-Circle]

Could we have an option to compare an existing config?

[bo0tzz]

Do you mean the diff view but based on an arbitrary starting point? I considered it, but the UI for picking that starting point seemed like it would get gnarly pretty quickly and I wanted to avoid that.

[Zero-Circle]

Do you mean the diff view but based on an arbitrary starting point? I considered it, but the UI for picking that starting point seemed like it would get gnarly pretty quickly and I wanted to avoid that.

Yeah, show a diff between a pasted version.
My compose was made by some unraid plugin and ive no idea on the toggles and switches enabled, Using this would be very helpful for me when i migrate the config and use it to check the structure.
For a unskilled user the unraid community is very helpful but now i know docker well i would like to do a diff between my existing config and the official one.

[bo0tzz]

I would recommend to just use any standard diff tool on the plain yaml for now.

[Balor992]

I love the idea behind this tool, I personally remove most port mappings to my host machine since I’m running everything behind traefik as a reverse proxy, I din’t see any option to remove the port mapping entirely though

[gary-hammer]

Immich Version Tag
Currently any V3 if you pick rolling. I'd rather stay with release, then I don't need to edit for v4 and I won't get any RC builds

[bo0tzz]

I had to pick one to keep the form from becoming overcomplicated, and using a general tag like release is generally not a good idea as major releases may have breaking changes.
Nb none of these tags include RC builds, you only get those if you explicitly opt in.

[gary-hammer]

Good to know on the rc versions.

[gary-hammer]

Perhaps I missed a change, or are we supposed to use .env for things not in the docker-compose?

Missing Container Environment Variables: In the official setup, .env supplies default database connection strings and service hostnames to immich-server and immich-machine-learning. Without .env or explicit environment: blocks, the application services will not know how to communicate with the database or redis containers.

[bo0tzz]

Where are you seeing that message?
This new builder is part of an effort to move away from that .env file setup in order to simplify things.

[gary-hammer]

Ahhh, I understand. As long as I use the default database, etc no need to be explicit.

[mrmuiz]

Still a verry old Postgres. Atleast the option to choose a version? And maybe Environment settings? Not everyone uses a .ENV

[bo0tzz]

It's the same postgres version as in the default compose file.
Setting env vars is straightforward enough that I don't think we need a specific entry in the builder for it, people can just add those manually.

[mrmuiz]

Yes 14 verry old. And emv is not straightforward for everyone tough. But it was just how i see it.

[c0by85]

Looks great! But is it safe to change from

    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro

to

    volumes:
      - ./library:/data
      - /etc/localtime:/etc/localtime:ro

?

From :/usr/src/app/upload to :/data ?

[bo0tzz]

See https://github.com/immich-app/immich/releases/tag/v1.137.0. It should migrate automatically

[gatortux]

Very useful tool. Only thing I changed is I like to use a restart mode of 'unless-stopped' instead of 'always'. But that is also simple enough to modify after it is generated.

[multi-suggester]

i think itd be nice if there were some sort of windows to linux location converter sorta thing ?
(like what should i write if my folder is d:xxxx/xxx/xxx instead of ./xxxx/xxx ?)
something like an on off switch for windows+ insert directory sorta thing would prob help?

[multi-suggester]

(its also an issue for external library in my experience btw i always have to look it up how to adjust it)

[zwimer]

This is a very appreciated feature. One possible bit of clarification that would be appreciated is whether custom rootless UID/GIDs are supported. Under advanced, the option to change them does exist, however, in some of the containers I notice that user 1000 can map to the user node. Since the default rootless config is 1000:1000 this runs as node:node which makes sense; so clarification that either it is or is not known to be safe to run as 1001:1001 instead of node:node would be nice.

[technomensch]

Not sure if this a feature request, or if this is already possible and I just don't see it. Right now, I am using the SynoCommunity package on my Synology. Since it looks like I have to wait for them to release their packages, and would like to upgrade, is there a way to use this feature to build the compose script so it either a) migrates the core application itself, while keeping my library/upload files exactly where there are, or b) can move them properly into an immich folder under Docker? Essentially, being able to tell the script to move my immich from local to the Docker container. I'd be curious how much would need to go in the container vs. can stay where it already is. (I just finished setting up the Package this weekend, so of course you'd release the new version just as I finally getting it working.)

Thanks.