Blog
Docker Compose Builder

Docker Compose Builder

September 25, 2026

— Immich Team

An overview of Docker Compose Builder, a new tool for building compose files for Immich.

Docker Compose Builder tool with options panel and sample docker-compose.yml preview

Hello again!

We recently released a new tool for building a docker-compose.yml file for Immich! We’re calling it: Docker Compose Builder. If you haven’t seen it or tried it out yet, you can access it at https://immich.app/docker-compose-builder. There is also a GitHub Discussion about the topic if you have any feedback for the team. It’s only been out a few weeks so we’re constantly improving it based off of community feedback.

Join the discussion

Motivation

The motivation for building a tool like this ultimately came from a desire to reduce the issues and confusion we see around the docker-compose.yml file, which are MANY. Most of the issues and confusion stem from the fact that we use an .env file in conjunction with docker-compose.yml. This setup seems to introduce several foot guns in addition to other inconveniences. The Docker Compose Builder tool is an attempt to remove the .env file entirely from the docker-compose.yml, while also centralizing Immich deployment best practices and common patterns, which currently exist scattered around the Immich docs, GitHub discussions, issues, release notes, or in support threads on Discord.

Environment variables in compose files

Some environment variables are used in the old docker-compose.yml file for templating. The following example uses IMMICH_VERSION, although many are used across the file:

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}

In this example the immich-server tag can be controlled or set dynamically based off of the value of IMMICH_VERSION. Docker Compose will automatically read a sibling .env file and will load and use variables from it, in addition to any others available in the current shell. While this is nice in theory it actually introduces a bunch of different problems. More on that below.

Polluting the container

The first problem is that the immich-server container also passes the same .env file to the container directly:

env_file:
  - .env

Any environment variables used for templating now also get passed into the immich-server container.

There have been some cases where users used an environment variable, like PORT or HOST in their template, but since it was also passed into the container it changed the container’s behavior leading to unintended consequences which were difficult to understand. This is one of the motivations to migrate our PORT environment variable to IMMICH_PORT. Obviously, if we could avoid this whole class of problems in the first place that would be even better.

Volume templates

There are some templating environment variables that are used on the left side of volumes such as UPLOAD_LOCATION.

volumes:
  - ${UPLOAD_LOCATION}:/data

What would happen if you tried to start up containers referencing a volume that didn’t have a value? Well, you get errors like this:\n

WARN The "UPLOAD_LOCATION" variable is not set. Defaulting to a blank string.

WARN The "DB_DATA_LOCATION" variable is not set. Defaulting to a blank string.

invalid spec: :/var/lib/postgresql/data: empty section between colons

For many users it is not clear what this error message means. Also, the fact that unset environment variables default to a blank string can further lead to unexpected consequences.

Really, there should always be an UPLOAD_LOCATION and probably it should be inlined/hard-coded directly into the docker-compose.yml file itself, not dynamically “rendered” based on environment variables and whether it is correctly set in another file or not.

Support requests

We get a lot of support requests from users. Often the culprit is a simple misconfiguration, hence we ask for the docker-compose.yml and .env files for verification. Users sometimes have a hard time locating or copying the .env file, because file managers on most operating system hide a file if it starts with a leading dot. Especially on Windows, the file manager option to see hidden files is tucked away, complicating the process. We've also had many users try to move the docker-compose.yml file to another directory, but completely miss the hidden .env file. Leading to their install not starting up, or starting up with a wrong configuration making it look like all their data was GONE.

Solution

As you can see, there are a lot of “problems” that originate from how we use the .env file in our docker-compose.yml. While there are a few different ways to address some of the specific issues, we thought it would be good to just have a clicky-pointy online tool for it.

The team can easily and quickly update and maintain a website — we already know how to do that. The tool has a configuration box that basically replaces what used to be in the .env file, except that we now have access to other form elements like checkboxes, dropdowns, etc. We can also dynamically show or hide options as needed.

Probably the most important part about this whole thing is that it generates a single file version of docker-compose.yml (no .env file!), which we hope will make it easier for users to get started with Immich. The motivation for this has always been to simplify running and maintaining Immich and we hope this tool can play a small part in that.

Open Docker Compose Builder

Like most things we do, this is open source. It is licensed under the terms of the MIT license and available on GitHub. Feel free to use GitHub issues to report problems or pull requests to submit changes, and don’t forget to let us know if you have any feedback.

Special shout out to bo0tzz who revived this project and pushed it to the finish line in static-pages/#660!

Cheers,
The Immich Team