How to Deploy Immich on a VPS

copymkdir ~/immich && cd ~/immich

#Install Immich

Immich's official install is a Docker Compose stack. You download two files — the release docker-compose.yml and the matching example.env — into your directory, edit the env file, and bring it up:

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

Now edit the .env file. The two settings that matter most:

copynano .env

• UPLOAD_LOCATION — the host path where your originals live. Point this at your large/expandable disk (see sizing above). If you attached block storage mounted at, say, /mnt/photos, set UPLOAD_LOCATION=/mnt/photos/immich. This is the single most important line in the file; getting it wrong means your library lands on the wrong volume and moving it later is a chore.
• DB_PASSWORD — set a strong, unique password for the database. Don't leave the example value.

Leave the other defaults unless you have a reason to change them. Then start it:

copydocker compose up -d

The first up pulls several images and can take a few minutes. What you're bringing online is four cooperating containers:

• immich-server — the API and web UI (port 2283),
• immich-machine-learning — the model worker for face recognition and smart search,
• a Redis/Valkey cache — job queues and session state,
• a Postgres image with a vector extension — and this one is not optional.

Why the special database image matters: Immich stores ML embeddings — numerical fingerprints of faces and image content — and searches them with vector similarity. That needs a Postgres built with a vector extension (pgvecto.rs / VectorChord). You must use the Postgres image Immich ships in its compose file, not a plain postgres:16. Swapping in vanilla Postgres is a common mistake that leaves the server unable to start or search broken — the extension simply isn't there. Leave that service exactly as the release compose file defines it.

Confirm everything came up healthy:

copydocker compose ps
docker compose logs -f immich-server

When the server log settles, browse to http://YOUR_SERVER_IP:2283 for a first look — but don't stop here. You want HTTPS before you point a phone at it.

#HTTPS + domain

Serving over http://IP:2283 is fine for a first test, but you need real HTTPS before going further — and not just for tidiness. The mobile apps expect a secure connection to back up reliably, and you don't want your entire photo library traveling over plain HTTP. A reverse proxy in front of Immich terminates TLS and forwards to port 2283 internally.

The clean way to do this is Caddy, which issues and renews Let's Encrypt certificates automatically. Follow the companion guide, Automatic HTTPS with Caddy, and proxy your domain to Immich's port. First point an A record for your hostname (say photos.example.com) at the server's public IP, then the Caddyfile is essentially:

photos.example.com {
    reverse_proxy 127.0.0.1:2283
}

Caddy requests a certificate on first load (ports 80 and 443 must be reachable — which your firewall already allows), renews it automatically, and forwards traffic to Immich over localhost. Once DNS resolves and the certificate issues, load https://photos.example.com and you're ready to onboard.

#First-run setup

The first time you load Immich over your domain, it shows an onboarding screen.

Create your admin account immediately. As with any self-hosted app whose signup is open until the first user exists, whoever registers first owns the server — so do it the moment the install is reachable, before you walk away. Set a strong password; this account controls every library on the box.

Once you're in, the admin panel lets you set the server URL, storage template, and whether new users can self-register (turn that off unless you're inviting others). Then install the Immich app on your phone from the App Store or Play Store:

1. Open the app and enter your server URL — the full https://photos.example.com, the same address you use in the browser. This is why the reverse proxy and a valid certificate matter; the app connects to that HTTPS endpoint.
2. Log in with the account you just created.
3. Grant photo access and enable background backup. The app uploads your camera roll and keeps new photos flowing to the server automatically.

The first backup of a large existing library takes a while — it's uploading everything — and the ML container will churn through face detection and search indexing in the background afterward. That initial indexing pass is CPU- and memory-hungry; it's normal, and it settles once caught up.

#Backups

There are two things to back up, and skipping either one loses data you can't reconstruct.

1. The Postgres database. This holds all your metadata — albums, shared links, detected faces and people, search indexes, users. The originals on disk are useless without it; you'd have a folder of files and no timeline, no faces, no albums. Immich documents a database dump using pg_dumpall against its database container. A dump looks like:

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

Run that on a schedule (a cron job on the host) and — critically — copy the dump off the box to S3-compatible storage or another machine. A backup that only lives on the same server dies with the server. Follow Immich's current documentation for the exact dump/restore commands, since the database image and recommended flags can change between releases.

2. The UPLOAD_LOCATION folder. This is the actual originals — the photos and videos themselves. Back up that entire directory (an rsync to off-box storage, or your provider's block-storage snapshots) on its own schedule. The database points at these files; both halves have to survive together.

One habit worth building: test a restore. Spin the dump and a copy of the upload folder up somewhere and confirm the library actually comes back. An untested backup is a guess, and photos are the kind of data you only discover was un-restorable at the worst possible moment.

#Upgrades

Because Immich moves quickly, upgrades are a deliberate step, not a reflex.

Pin your version. Rather than tracking :latest, set an explicit release tag so you control exactly when you move. Immich's compose file uses the IMMICH_VERSION variable in .env for this — set it to a specific release (for example IMMICH_VERSION=v1.xxx.x) instead of release/latest. That way a docker compose pull doesn't silently jump you across a breaking change.

To upgrade, when you've decided to:

copycd ~/immich
# read the release notes for every version between yours and the target first
docker compose pull
docker compose up -d

Read the release notes before every upgrade, and back up first. Immich has occasionally shipped changes that require a migration step or a specific upgrade path — jumping several versions blind is how people get stuck. Move one release line at a time when a version calls for it, confirm the server comes back healthy (docker compose logs -f immich-server), and only then delete the old backup. If an upgrade goes sideways, your pre-upgrade database dump plus the untouched UPLOAD_LOCATION folder are your way back.

#Troubleshooting

Search or face recognition silently does nothing / the ML container keeps restarting. Almost always memory. The immich-machine-learning container needs room to load its models, and on an undersized box it gets OOM-killed the moment a job runs. Check with docker compose logs immich-machine-learning and docker stats — if it's dying under memory pressure, this is the single best argument for the 4 GB (6 GB comfortable) sizing above. Size up.

Server won't start after swapping the database image. If you replaced Immich's provided Postgres with a plain postgres image, the vector extension isn't present and the server can't initialize its schema. Restore the exact database service from the release docker-compose.yml. Immich needs its own vector-enabled Postgres — this is not interchangeable with stock Postgres.

no space left on device / backups and uploads start failing. The library filled the disk. Check df -h and confirm UPLOAD_LOCATION is pointing at your large volume, not the root filesystem. This is the most common Immich failure over time and the reason sizing leans on expandable storage — extend the block volume (trivial on Kamatera or via a Hetzner Volume) and Immich keeps going.

Mobile app won't connect or backup stalls. Confirm you entered the full https:// server URL and that the certificate is valid — a self-signed or expired cert makes the app refuse to sync. Load the same URL in a browser; if it warns about the certificate, fix the reverse proxy (see the Caddy guide) before blaming the app.

#Verification + next steps

You're done when you can: load Immich over HTTPS on your own domain, log in as admin, sign in from the mobile app and see a photo you just took auto-upload to the timeline, and confirm both a database dump and a copy of UPLOAD_LOCATION are landing in off-box storage.

From here, invite family members, build shared albums, and let the ML worker index faces in the background. The one thing that makes or breaks Immich over the long haul is the box underneath it — specifically the disk. Hetzner is the value pick when you can size a large disk up front; reach for Kamatera when you want to dial RAM precisely and grow block storage on demand as the library expands, which for a photo server it always will. See Best VPS for self-hosting for the ranked picks.