Immich Docker Compose | Official Docker Compose Setup

Immich Docker Compose setup is the recommended way to run Immich for photo and video backup in production. Docker Compose is the recommended method to run Immich in production.

Here’s how you can deploy Immich using Docker Compose (official recommended method) plus tips & caveats:

🛠 Official Docker Compose Setup

According to the Immich docs: “Docker Compose is the recommended method to run Immich in production.”

Here are the steps:

Step 1: Prepare a directory & get files

Download the docker-compose.yml and the environment example:

If you downloaded manually via browser, rename example.env to .env.

Also Read : Charlie Kirk on a Coin

Step 2: Edit .env

Open .env and set the variables you need. Some key ones:

If you change environment vars, you’ll need to recreate containers so they pick up the new values.

Step 3: Start the stack

Run:

This will pull the necessary images and bring up all relevant services (server, Redis, PostgreSQL, machine learning, etc.)

Note: The command is docker compose, not docker‑compose (depending on your Docker version).

If you get errors like unknown shorthand flag: 'd', your Docker command version is misaligned (e.g. using older Docker). Use the proper Docker engine install for your OS.

One known issue: some users see errors like can't set healthcheck.start_interval if their Docker engine version is older (pre v25). In that case, comment out or remove that healthcheck line under the database service in docker-compose.yml.

⚠ Caveats and Tips from Community & Issues

• If you already have an existing Docker Compose setup with services (databases, Redis, etc.), conflicts may arise. For example, some people report conflicts due to generic service names like database, redis, or environment variables that collide.

• Some have had to rewrite parts of the official compose file to integrate with existing stacks.

• On Unraid, people sometimes need to remove or disable healthcheck blocks because their Docker engine version doesn’t support certain healthcheck parameters.

• A very common error is “Unable to connect to database / getaddrinfo ENOTFOUND database” — that usually indicates network or host name mismatches (i.e. your DB_HOSTNAME not matching service name or network).

• When upgrading Immich, many users just update the docker-compose.yml and .env based on the breaking changes list, rather than fully replacing their files each time.