How to Self-Host Immich for Private Photo Backup

Cloud photo services are convenient until the free tier ends or the price changes. Immich is the self-hosted alternative that most closely matches the mobile experience: automatic upload from your phone, albums, face detection, and shared libraries, all on your own storage.

Foto: Vyacheslav Argenberg, CC BY 4.0, via Wikimedia Commons

Ringkasan singkat

• Use the official compose file, not a hand-written one.
• UPLOAD_LOCATION must sit on the big disk.
• Back up library and database — both are needed.
• HTTPS is required for reliable mobile upload.

This guide runs Immich with Docker Compose on Ubuntu, then covers the parts people forget: storage layout and backups.

Prerequisites

• Ubuntu server with Docker and Compose plugin.
• At least 20 GB free, plus room for your library.
• 4 GB RAM minimum; 8 GB is comfortable with machine learning enabled.
• IPv4 port 2283 available, or a reverse proxy.

1. Create the project folder

mkdir -p /opt/immich && cd /opt/immich

2. Get the official compose file

Immich ships a compose file and an environment file per release. Download both from the project's release page rather than writing them from memory — service names and image tags change between versions.

wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget https://github.com/immich-app/immich/releases/latest/download/example.env
mv example.env .env

3. Edit the environment

nano .env

UPLOAD_LOCATION=/opt/immich/library
DB_PASSWORD=CHANGE_ME_LONG_RANDOM
TZ=Asia/Jakarta
IMMICH_VERSION=release

UPLOAD_LOCATION is where original photos live. Put it on the largest disk you have, and note the path: it is the folder you must back up.

Diagram: Immich receiving uploads and writing to library, database, and ML worker

4. Start the stack

docker compose up -d
docker compose ps

Four services appear: the server, the machine learning worker, Redis, and PostgreSQL. The first start pulls images and takes a few minutes.

5. Create the admin account

Open http://SERVER_IP:2283. Register the first user — it becomes the administrator. Then install the mobile app from the Play Store or App Store, sign in with the server URL, and enable background upload.

6. Understand the storage

du -sh /opt/immich/library
ls /opt/immich/library

Two things are commonly mixed up:

• library — originals and generated thumbnails.
• database — metadata, albums, faces. It lives in a Docker volume, not in the library folder.

Backing up only library loses albums and faces. Backing up only the database loses the photos themselves. You need both.

7. Backups that actually restore

docker exec -t immich_postgres pg_dumpall --clean --if-exists --username=postgres \
  | gzip > /backup/immich-db-$(date +%F).sql.gz

Pair that dump with a copy of library, and test a restore into a separate folder. A photo archive you have never restored is a hope, not a backup.

8. Reverse proxy and HTTPS

Immich expects to be served over HTTPS for mobile uploads. Point a reverse proxy at 127.0.0.1:2283, forward the usual headers, and raise the upload size limit. Large videos will fail with 413 otherwise.

9. Reading an existing photo folder

External libraries let Immich index files in place instead of copying them. Register the path under Administration → External Libraries, scan it, and Immich builds thumbnails while leaving the originals untouched.

Pick one method per album. Importing the same photos both as an upload and as an external library produces duplicates that are tedious to untangle later.

10. Updating safely

cd /opt/immich
docker compose pull
docker compose up -d

Read the release notes before a major version. Take a database dump first; downgrades are not supported, and the database schema moves forward only.

11. Mobile upload pitfalls

Background upload is the feature people rely on, and the one that fails quietly. Three settings matter: allow the app to run in the background, disable battery optimisation for it, and choose whether uploads wait for Wi-Fi. On a metered connection the last setting decides whether a holiday album costs you a data bill.

Check Administration → Jobs after the first sync. If the queue is stuck, the usual cause is an expired token after changing the server URL.

Troubleshooting

Symptom	Cause	Fix
Page never loads	Stack still starting	docker compose logs -f
Uploads fail on phone	No HTTPS or low body limit	Reverse proxy with TLS, raise client_max_body_size
Machine learning container restarts	Not enough RAM	Disable ML or add memory
Photos not deduplicated	Uploaded through two paths	Use one import method per album
Disk full	Thumbnails plus originals	Plan for roughly 1.2–1.5× original size

FAQ

Is it stable enough for family photos?

It is actively developed and widely used, but fast-moving. Keep the backup routine before you migrate everything.

Can it read an existing folder of photos?

Yes, through external libraries. Immich reads them in place instead of copying, which is useful for an archive you already manage.

Does face detection run on the server?

Yes, in the machine learning container. It benefits from a GPU but works on CPU at lower speed.

How much space should I plan?

Roughly 1.2–1.5× the size of your originals, because thumbnails and transcoded videos are stored too.

Related guides:

• Running a Local LLM with Ollama and Open WebUI
• Self-Hosting Uptime Kuma for Server Monitoring
• Setting Up Tailscale on a VPS