Immich Docker Compose Services Explained Server Machine Learning Database and Redis
Your Immich install is not one program — it is four containers working as a team. Understanding who does what turns scary error messages into simple directions: search broken means one container, uploads stuck means another.
✍️ Technical Anshu🐳 Docker / Linux Server⏱️ 6 minute read
🎥 Watch the video first if you have not installed yet — this guide explains the moving parts behind that install
Most people run docker compose up -d, see four containers start, and never ask what they are. That works — until the day something misbehaves. Then the difference between a five-minute fix and a weekend of random reinstalling is simply knowing which container owns which job. Here is the whole team, decoded.
👆 Example status panel — four containers, four separate jobs. When something breaks, this list tells you which quarter of the system to inspect.
1
immich-server — the Brain Everyone Sees
This is the container you actually talk to. It serves the web interface on port 2283, runs the API the mobile apps connect to, receives uploads, builds the timeline, manages users, albums and sharing links, and coordinates every background job.
If the page will not load or the app cannot connect, this container is suspect number one
Check it with docker logs immich_server — the name on your system may vary slightly; docker compose ps shows the exact names
It is also the container that gets replaced on every update — your photos are never inside it, which is exactly why updates are safe when done properly
2
immich-machine-learning — the Eyes That Work at Night
Face detection, face recognition, and the smart search that finds 'beach' or 'birthday cake' without any tags — all of it runs in this separate container. It downloads its AI models once into a cache volume and then grinds through your library as a background job.
Photos appear in the timeline before they are searchable — the server stores them instantly; the learning container catches up later
On a modest CPU, a big first library can keep this container busy for many hours. That is normal, not a fault
If faces and search stop improving while uploads work fine, restart or inspect only this container — the rest of Immich is healthy
It is deliberately separate so you can run it on a different, stronger machine later, or pause it without touching your photo server
3
The Database — PostgreSQL Holds the Meaning of Your Library
Your photo files sit in folders. But which photo is in which album, who is in it, where it was taken, what the search index says — that knowledge lives in the PostgreSQL database container, which uses a vector extension so smart search can compare faces and images mathematically.
This is why a backup of only the photo files is not a backup of your Immich — the organisation would be gone
The database folder (your DB_DATA_LOCATION) must live on a local disk, ideally an SSD — the official documentation says network shares are not supported for it, and database files on network storage are a known corruption route
Never delete, move or 'clean up' this folder by hand. If it is damaged, restore it from a backup — do not experiment on the only copy of your library's brain
4
Redis — the Messenger You Will Never Think About
Redis is the smallest and quietest member: an in-memory message queue. When the server needs a thumbnail generated, a video transcoded or a face scanned, it posts the job through Redis and a worker picks it up.
You will almost never configure it — it has no data worth backing up, because its contents are just jobs in flight
Its classic symptom is subtle: uploads succeed but thumbnails or jobs seem stuck forever. A glance at docker compose ps showing Redis down explains the whole mystery
Because it holds nothing permanent, restarting it is safe and is a legitimate first troubleshooting step
5
The Troubleshooting Map — Symptom to Container
Page or app will not connect → server container, then your network and port 2283
Uploads work, faces and search frozen → machine learning container and its job queue in Administration → Jobs
Photos on disk but missing or wrong in the timeline → database container — and your last backup becomes very important
Everything loads but background work never finishes → Redis, then the server logs
All four down → it is not Immich at all: check Docker itself, disk space, and whether the machine rebooted without Docker starting
One more habit worth building: before changing anything, run docker compose ps and read the logs of the one suspect container. Ten minutes of reading beats two hours of reinstalling.
🔴 Golden rule of the four-container design: your photos and database live in folders and volumes outside the containers. Containers are disposable; the data folders are not. Any "fix" that involves deleting the upload folder or the postgres folder is not a fix — it is data loss.
🎥 Watch the Complete Process in the Video
See the four containers start together in the install video — then come back here when you want to know what each one does.
Can I delete the machine learning container to save RAM?
You can disable machine learning in the administration settings, and Immich will still store and serve photos — but face recognition and smart search will stop. Deleting the container from the compose file is not the supported way to do it; use the settings, so you can switch it back on later without editing files.
Why does Immich need a special PostgreSQL instead of a normal one?
Smart search compares faces and images as mathematical vectors, and that needs a vector extension inside PostgreSQL. The official compose file therefore uses a database image with that extension built in. Swapping in a plain PostgreSQL image breaks search and can break upgrades — another reason to use the official files unchanged.
One container keeps restarting. Where do I look first?
Read its logs before touching anything: docker logs followed by the container name, or docker compose logs. A restart loop almost always prints its reason — a wrong password in the .env file, a missing folder, or a full disk are the three classics.
This guide is based on the Technical Anshu video linked above • Stuck on a step? Ask in the video comments — that is where answers come fastest 🙏