imagegenius/docker-immich: Immich in a Single Container, With Postgres and Redis Left Outside

One container instead of Immich's server, machine learning and microservices split

Upstream Immich is normally deployed as several containers: a server, a machine learning process, a database and a cache, wired together in a compose file. This repository collapses the Immich side of that into a single image, so the container you start contains the web server, the API and the machine learning runtime. The README describes it as a "Monolithic (Single) Docker Container for Immich", and the topics list on the repository includes minimal and monolithic alongside docker, self-hosted and photos. The intended audience is someone who already has PostgreSQL and Redis or Valkey running somewhere on their network and does not want a second database container appearing next to every application they host. The image is built for amd64 and arm64, which matters if you run Immich on a Raspberry Pi or an ARM NAS. It is not a fork of Immich itself. It is a packaging layer, and the version numbers track upstream releases.

What the image actually contains, and what it refuses to contain

The four published tags differ by what is compiled in. latest is Ubuntu with machine learning on CPU. noml is the same base with machine learning disabled, which the README describes as a smaller image. cuda adds NVIDIA CUDA and is amd64 only. openvino adds Intel OpenVINO and is also amd64 only. That is the entire variant matrix, and it tells you the project's position: the database and the cache are deliberately outside the image. The requirements section is explicit that PostgreSQL must be version 14 to 17 with the VectorChord extension, and it points at ghcr.io/immich-app/postgres as a way to avoid installing that extension by hand. Valkey or Redis is either external or provided through a Docker mod. The compose example in the README shows three services, not one: immich, valkey and postgres14. Anyone expecting a genuinely single-container deployment will be disappointed, because the title describes the Immich application layer only. The image also carries the machine learning model cache inside the /config volume, which the parameter table puts at roughly 1.5GB with default settings. That is disk you have to plan for before the first start, not after.

Environment variables are the whole configuration surface

There is no config file to edit. Everything arrives as environment variables, which is consistent with the LinuxServer.io style that imagegenius images follow. The required set is PUID, PGID, TZ, DB_HOSTNAME, DB_USERNAME, DB_PASSWORD, DB_DATABASE_NAME and REDIS_HOSTNAME. Optional keys cover DB_PORT, REDIS_PORT, REDIS_PASSWORD, SERVER_HOST, SERVER_PORT, MACHINE_LEARNING_HOST, MACHINE_LEARNING_PORT, MACHINE_LEARNING_WORKERS and MACHINE_LEARNING_WORKER_TIMEOUT. The README notes that SSL Postgres connections are configured through DB_URL rather than a set of separate TLS variables. Three volumes are defined: /config for application config and the model cache, /photos for the Immich library, and /libraries for external libraries to track. The README's existing libraries section says to mount the folder at /libraries, or at /libraries/<user> for multi-user setups, though the supplied text cuts off there. If you have an existing photo tree you do not want copied, that mount point is the one that matters, and the per-user subdirectory form is worth reading in full on the repository before you point it at anything.

Getting Redis into the container without a second service

The Docker mod route is the interesting part of the design. Setting DOCKER_MODS=imagegenius/mods:universal-redis and REDIS_HOSTNAME=localhost causes a Redis instance to be installed and started inside the same container, which removes the need for a separate valkey service in your compose file. This is a real convenience for people running a single small host, and it is also the point where the monolithic approach starts to cost something. A Redis process inside the Immich container shares its memory limit, its restart policy and its logs. When the container restarts, the cache restarts with it. The README does not describe how persistence is handled for that embedded Redis, so if your use of Immich depends on cache durability, the external Valkey service in the compose example is the safer arrangement. The mod system is inherited from the LinuxServer.io ecosystem rather than invented here, which means the mechanism is familiar to anyone who has used those images, but it also means the mod is a separate artefact with its own release cycle.

Hardware acceleration flags differ by vendor and by tag

For Intel, the README says to mount /dev/dri into the container. For OpenVINO specifically it adds a second step: verify CPU support against the OpenVINO system requirements page, then add --device-cgroup-rule='c 189:* rmw' and mount /dev/bus/usb. That USB device rule is not obvious and is easy to omit, which would leave OpenVINO unable to see the hardware it was built for. For NVIDIA, the sequence is to install the container toolkit, then run with either --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all or --gpus=all. Note that the cuda tag is amd64 only, so an ARM host cannot use it regardless of what GPU is attached. The openvino tag is likewise amd64 only. If you are on arm64 and want acceleration, the README's material does not describe an option, and the plain or noml tags are what remain. The machine learning worker count and timeout are exposed as variables, which is the only tuning surface for ML throughput that the documentation offers.

The upgrade path is the real cost of the monolithic build

This image is not built by the Immich maintainers. The version tags are the project's own scheme, and the release list shows how that plays out: v2.7.5-ig458 and noml-v2.7.5-ig370 sit alongside a 2026.0.0 entry that GitHub marks as an archived release. The ig suffix is a build counter, not an Immich version, which means two images with the same upstream Immich version can contain different packaging. Pinning ghcr.io/imagegenius/immich:2.7.5 or ghcr.io/imagegenius/immich:2.7.5-cuda gives you a reproducible image, but it also means you are the one watching for upstream Immich releases and deciding when to move. Upstream Immich has historically required database migrations between some versions, and because the database lives outside this container, a botched upgrade leaves you restoring Postgres rather than rolling back a container. The README does not document a downgrade procedure or a migration checklist. That absence is the strongest argument for the upstream compose deployment if you value having the vendor's own upgrade notes describe the thing you are running. The licence is GPL-3.0, which is the same family as the upstream project; if you redistribute a modified image, the obligations that come with that are yours to check, and this article is not legal advice.

When the upstream compose file is the better answer

The obvious alternative is Immich's own docker-compose deployment, which ships the server, machine learning, Postgres and Redis as separate services maintained by the Immich team. The difference is not cosmetic. In the upstream arrangement, the database image is built and published by the project, the machine learning container can be scaled or replaced independently, and release notes describe exactly the components you are running. Here, you get a single Immich container and you supply the rest. That is a genuine simplification for a homelab where Postgres already exists, and a genuine complication when something breaks, because the boundary between the image and your database is where the debugging happens. A second alternative, if the goal is simply fewer moving parts, is to run Immich's server container against a managed or shared Postgres and skip the monolith entirely; you keep the vendor's image and still avoid running a database container per application. The monolith wins on container count. It loses on provenance and on upgrade documentation.

Editorial conclusion

Adopt this if you already run PostgreSQL and Valkey elsewhere, want one Immich container to manage, and are comfortable pinning a semver tag such as ghcr.io/imagegenius/immich:2.7.5 rather than tracking latest. Do not adopt it if you want Immich's own compose file to be the reference, if you have no external Postgres, or if you need the project's own release notes to describe the image you are pulling. Before deploying, verify the Postgres server is version 14 to 17 with VectorChord available, confirm the /config volume has room for the roughly 1.5GB machine learning model cache, and decide between the plain, noml, cuda and openvino tags based on whether you have an NVIDIA GPU, an Intel iGPU, or neither.

Official sources

1. imagegenius/docker-immich on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases