Deployn

Install Immich with Docker Compose: Setup Guide for Version 3

Install Immich with Docker Compose and set it up: admin account, Caddy reverse proxy, app and backup. The Google Photos alternative for a VPS or NAS.

Install Immich with Docker Compose: Setup Guide for Version 3 hero image
Contents
Tested with
Immich 3.3.6Docker 29.9Ubuntu 24.04
Last checked on

You know what? Privacy isn’t just a buzzword anymore—it’s a necessity. And when it comes to storing your precious memories—those candid family photos, those goofy videos of your dog—trusting a third-party cloud service can feel like handing over your diary to a stranger. That’s where Immich steps in, offering a self-hosted, open-source alternative to services like Google Photos or iCloud. Think of it as your very own private vault for photos and videos, one that you control entirely.

But is it worth the effort? Let’s break it down together.

Why Immich Stands Out (And Why You Should Care)

Immich wasn’t born out of some corporate boardroom brainstorming session. Nope. It started with a dad—a guy named Alex Tran—who wanted a safe, private way to store photos of his newborn baby. No ads, no algorithms peeking at his pictures, no risk of data breaches. Just pure, unfiltered privacy. Fast forward to today, and Immich has grown into a powerhouse tool for managing photos and videos, complete with features that rival its big-name competitors.

Here’s what makes it special:

  • A sleek interface that feels eerily similar to Google Photos.
  • Automatic uploads from both Android and iOS devices.
  • Smart features like facial recognition and AI-powered search.
  • Full ownership and control over your data—no strings attached.

Honestly, who wouldn’t want that?

Setting Up Immich: Easier Than You Think

Before you panic about setting up a “self-hosted” solution, let me assure you—it’s not rocket science. Sure, there’s a bit of prep work involved, but if you’ve ever tinkered with Docker or set up a NAS (Network Attached Storage), you’re already halfway there.

What You’ll Need

First things first, here’s what you’ll need to get started:

  • A Server with Docker: This could be anything from a Synology NAS to an old PC running Ubuntu.
  • Some decent hardware specs: Ideally, 6GB of RAM and 4 CPU cores, though 4GB and 2 cores might scrape by if you’re on a budget. In my test (4 vCPUs, 8GB RAM), the four containers used about 1.7GB of RAM together while idle, and the Docker images add up to about 4.4GB.
  • Plenty of storage space: Photos and videos eat up space faster than you’d think. Plan accordingly.
  • Optional extras:
    • Reverse Proxy: A reverse proxy (e.g., Nginx Proxy Manager, Caddy, Traefik) for external access and domain usage.
    • DNS-Server: A DNS server (e.g., Adguard Home, Pi-Hole, Technitium) for internal forwarding.
    • VPN-Server: If the server is not on your own network, setting up a VPN server like WireGuard or OpenVPN is recommended.
    • SMTP EMail Address: An SMTP address can be used for notifications, e.g., a shared web hosting plan from Netcup.

Organizing Your Files

Before diving into the installation, take a moment to organize your folders. You’ll need two main directories:

  • data: Where your photos and videos will live.
  • db: For the PostgreSQL database.

For example:

Ubuntu Server
Terminalbash
cd ~
mkdir immich
cd immich
mkdir db data

Result:

Terminalbash
/home/user/immich
├── db
└── data

We can also create an empty docker-compose.yml file here, which we’ll need later.

Terminalbash
touch docker-compose.yml

or the data path, we only need the relative reference to the docker-compose.yml file. In this case, it would be ./db and ./data.

Synology NAS

On a Synology NAS, we can either create a new shared folder for Immich or use a shared folder for all Docker containers. In my configuration, I created a shared folder docker on my SSD and a shared folder dockerhdd on my HDD. In both, I create an immich folder and on the SSD, I additionally create the subfolder db and on the HDD, the subfolder data. This way, I can store the database on the SSD and the photos and videos on the HDD.

New Directory

Wherever the folders are created, the complete path can be found via the properties. This will be needed later for the Docker containers.

Path

Example result:

Terminalbash
/volume1/docker/
└── immich
    └── db

/volume2/dockerhdd/
└── immich
    └── data
Ugreen NAS

On a Ugreen NAS, we can simply create a new immich folder in the shared folder docker. In this folder, we then create the subfolders data and db.

New Directory

Of course, you can also create another shared folder. This is particularly useful if you want to store the database (db) on an SSD and the images and videos (data) on an HDD (Amazon affiliate link).

We need the full path, which we can find through the folder’s properties. This will be needed later for the Docker containers.

Path

Example result:

Terminalbash
/volume1/docker/
└── immich
    |── db
    └── data
# or
/volume1/docker/
└── immich
    └── db

/volume2/dockerhdd/
└── immich
    └── data

Firewall

To ensure that the created containers can communicate with each other, it is recommended to either allow the entire internal IP range or check the IP addresses used by the containers after installation if you have a restrictive firewall. Otherwise, the containers may not be able to communicate with each other.

Writing the Docker Compose File

Once your folders are ready, it’s time to write the docker-compose.yml file. This file tells Docker which containers to spin up and how they should interact. Here’s a quick rundown of the key components:

  • Valkey: Handles caching for faster performance.
  • PostgreSQL: The database engine, enhanced with the VectorChord extension for vector-based searches.
  • Immich Server: The brains of the operation.
  • Immich Machine: Powers AI-driven features like facial recognition.

Docker Compose File

First, we need the container commands to perform the installation.

Immich Docker Compose Generator

Generate a production-ready Docker Compose configuration for your self-hosted photo management

Please fix the following issues:

Configuration

Storage Settings

Network Settings

Security Settings

Version Settings

Generated Configuration

Production-ready Docker Compose file for Immich

Configuration Required

Complete the form above to generate your Docker Compose file

The images can be customized, but I advise against using latest or release as it can lead to problems if a new incompatible image is published. That is why the generator sets the tag v3: you get all updates of version 3, but never a new major version automatically. You can check on the container page to see which image is currently the newest.

Installation über Docker-Compose (Ubuntu Server)

The Docker-Compose code can be copied into the docker-compose.yml file. For the paths, relative paths (e.g., ./db) or absolute paths (e.g., /home/user/immich/db) can be used. The paths should lead to the previously created folders.

Then the containers can be started with the command docker compose up -d or sudo docker compose up -d. On the first start, Docker downloads the images, which takes a few minutes depending on your connection.

Use docker compose ps to check that all four containers are running. The STATUS column must show healthy for every container:

Terminalbash
docker compose ps --format 'table {{.Name}}\t{{.Image}}\t{{.Status}}'
NAME                      IMAGE                                             STATUS
immich                    ghcr.io/immich-app/immich-server:v3               Up 13 minutes (healthy)
immich-machine-learning   ghcr.io/immich-app/immich-machine-learning:v3     Up 13 minutes (healthy)
immich_db                 ghcr.io/immich-app/postgres:17-vectorchord0.5.3   Up 15 minutes (healthy)
immich_valkey             valkey/valkey:8                                   Up 15 minutes (healthy)

Right after the start, the Immich server briefly shows health: starting. That is normal. This is how you check that the server responds and which version is running:

Terminalbash
curl http://localhost:2283/api/server/ping
curl http://localhost:2283/api/server/version
{"res":"pong"}
{"major":3,"minor":3,"patch":6,"prerelease":null}

The server log shows the version as well. This command filters out the two important lines:

Terminalbash
docker compose logs immich | grep -E 'Initializing|listening'
immich  | Initializing Immich v3.3.6
immich  | [Nest] 25  - 11/04/2026, 8:30:18 PM     LOG [Api:Bootstrap] Immich Server is listening on http://[::1]:2283 [v3.3.6] [production]

On the very first start, the server also logs two warnings that the tables smart_search and face_search do not exist. The message itself says this is normal for a new instance. After that, Immich runs on port 2283, so at http://SERVER-IP:2283.

Installation über Portainer

Under Stacks, a new stack can now be added.

New Stack

If you can’t see this menu item, make sure you have selected the local environment and are running Portainer with the image portainer/portainer-ce and not portainer/portainer.

Here we insert the Docker Compose code.

Compose Datei in den Stack einfügen

Then the containers can be started. This may take a few minutes.

Container gestartet

Installation über Dockge

In Dockge, a new stack can be created. To do this, the Docker-Compose code is pasted into the text field and the stack is created. Then the containers can be started.

Neuer Stack

The initial installation can take a few minutes.

Reverse Proxy

To make Immich accessible via a domain like immich.domain.com, we set up a reverse proxy in the meantime.

Nginx Proxy

I enter the address of my Synology NAS and the port number chosen above. I can also use an access list to set whether only local access is possible.

If the Nginx Proxy Manager is on the NAS and the web server is in the same Docker network, you can enter the container name immich here and the port 2283.

Nginx Proxy Manager

If not, I enter the IP address of the server and the port number. The port number can be changed in the Docker-Compose file. The IP address is the internal IP address of the server.

After I’ve obtained the SSL certificate for the proxy host, I also add a few additional settings to the “Custom Nginx Configuration”.

client_max_body_size 50000M;
proxy_redirect off;

This ensures that larger files (50,000 MB) can also be uploaded to Immich.

Caddy Proxy

Alternatively, other proxy servers can be used. Especially if you’re using a different device for it, there are many options. With Caddy, this entry in the Caddyfile is enough for access from anywhere. The address and port 2283 are those of Immich:

caddy
immich.domain.de {
    reverse_proxy 192.168.1.123:2283
}

The DNS record for immich.domain.de must point to the server running Caddy. Caddy then gets the certificate from Let’s Encrypt on its own. I tried this with Caddy 2.11.7 on the test server: the certificate arrived within seconds (certificate obtained successfully), and https://immich.domain.de/api/server/ping returned {"res":"pong"}.

You don’t need an upload limit like in Nginx. Caddy does not limit the size of requests by default.

If Immich should only be reachable from the local network, you can block everything from outside:

caddy
immich.domain.de {
    @blocked not remote_ip private_ranges
    respond @blocked 403
    reverse_proxy 192.168.1.123:2283
}

First Login

Immich should now be accessible under the domain or the IP address of the server (with port 2283), for example at http://192.168.1.123:2283. On the first visit, a welcome screen appears. Click “Getting started” to begin the setup. The screenshots show the German interface; the English labels are given in the text.

Immich welcome screen

Create the Admin Account

The first user is automatically the administrator. This user can add additional users and change settings. Enter an email address, a password and a name, then click “Register”. You are signed in right away and the setup wizard starts.

Admin registration

Setup Wizard

A wizard then walks you through the basic settings. You can change all of them later in the settings:

  1. Theme: Light or dark.
  2. Language: The language of the interface.
  3. Server privacy: Here you can turn off the map feature (loads map tiles from tiles.immich.cloud) and the version check (queries version.immich.cloud). Both are on by default and optional.
  4. User privacy: Google Cast is off by default.
  5. Storage template: Defines which folders Immich sorts the files into. YYYY/MM/DD (year, month, day) is preselected. You can also choose “No template” or build your own structure.
  6. Backups: A note about the 3-2-1 rule: three copies, on two devices, one of them in another location.
  7. Mobile app: Links to the app stores and to the Obtainium configurator.

“Done” takes you to the photo overview. It stays empty until you upload something.

Upload Photos

With “Upload” at the top right, or by drag and drop, you upload photos and videos in the browser. I uploaded three test images. They show up in the timeline right away, sorted by capture date.

Uploaded photos in the timeline

Users and Storage Quota

In the administration, you can add more users under “Users” → “Create user”. You set an email address, a password and a name, and you can set a quota in GiB. Without a value it is unlimited. By default, the user has to change the password on first login. The “Administrator” switch gives them additional rights.

Create a new user

Email Notifications

If you have an SMTP address, you can also set up notifications. This is particularly useful if multiple users access Immich and share images. You find the setting under “Administration” → “Settings” → “Notification settings” → “Email”. For example, a web hosting plan from Netcup with an email inbox can be used here. Costs start at €2.17 per month.

Notification settings in the administration

Apps

Immich also offers apps for Android and iOS. These can be downloaded from the respective app stores. The apps are free and allow photos and videos to be uploaded directly from devices.

Immich App Android

Immich App iOS

On first start, the app asks for the address of your server. Enter the domain (https://immich.domain.com) or the IP address with port (http://192.168.1.123:2283) and sign in with your account.

Features:

  • Automatic Upload: New photos and videos are automatically uploaded.
  • Sharing and Collaboration: Albums can be shared with family and friends.

Updating Immich

For an update within version 3, two commands in the folder with the docker-compose.yml are enough:

Terminalbash
docker compose pull
docker compose up -d

To move from version 2 to version 3, change the tag of the two Immich images:

yaml
image: ghcr.io/immich-app/immich-server:v2
image: ghcr.io/immich-app/immich-server:v3
yaml
image: ghcr.io/immich-app/immich-machine-learning:v2
image: ghcr.io/immich-app/immich-machine-learning:v3

Then fetch the images with docker compose pull and restart with docker compose up -d. Back up your data first (see the next section) and read the notes on version 3. With version 3, Immich removed support for the old database extension pgvecto.rs. If you installed Immich before version 1.133.0 and have not yet switched to VectorChord, follow the migration guide first.

I tested the switch from 2.7.5 to 3.3.6 with a fresh installation without photos. The containers started without errors and the database image stayed the same. I did not try the update with a grown library.

Create Backup

For a complete backup, the folders data/upload and data/library (images and videos), data/profile (profile pictures) and data/backups (database dumps) should be secured. Immich regenerates data/thumbs and data/encoded-video when needed. After uploading the test images, the data folder looked like this in my test: backups, encoded-video, library, profile, thumbs and upload. Backing up can be done manually. Alternatively, it can be automated with a script or a backup tool like rsync or Duplicati.

An advantage (and simultaneously a disadvantage) of Immich is that the images are stored in a normal file system. This means that if something goes wrong and Immich no longer works, you can simply copy the images and restore them on another system (provided the images have not been deleted).

Conclusion

Immich should now be running. I appreciate any comments. Enjoy managing your images!

As an Amazon Associate I earn from qualifying purchases.

Share
XRedditEmail
Back to all posts

Changelog

  1. Switched to Immich 3 (image :v3), added the setup wizard with screenshots, corrected the folder names in the backup section, added terminal output and a section on updating from version 2.

More from this series

Comments