Host Immich on Your Own VPS

Update the system, install Docker, then create a dedicated mount point for media, for example /mnt/photos, separate from the system disk. Enable at least 2 GB of swap for the machine learning service.

Download the docker-compose.yml and the example.env file from the Immich repository with wget. Rename it to .env, then set UPLOAD_LOCATION=/mnt/photos, the database password and DB_DATA_LOCATION to a persistent volume.

Since version 3.0.0, the stack starts immich-server, immich-machine-learning and database (PostgreSQL with pgvector). Redis is no longer a separate service — it is embedded in the Immich server. The pgvecto.rs extension has been removed: do not use the old database image ghcr.io/immich-app/postgres, which has been replaced by the official PostgreSQL 17 image with pgvector.

Run docker compose up -d and wait for the large ML images to download. Open port 2283 internally, then create the administrator account via the web wizard before inviting other users.

Place Caddy in front of the server: photos.yourcompany.com { reverse_proxy immich-server:2283 }. Increase the proxy's maximum upload size (client_max_body_size on Nginx) because videos can be large, otherwise mobile uploads fail.

Install Immich from the App Store or the Play Store, enter https://photos.yourcompany.com as the server URL, sign in, then enable automatic camera roll backup to continuously replicate your new photos.

Run docker network inspect immich_default and check whether both immich-server and immich-machine-learning appear in the Containers list. If one is missing, review the networks field in your docker-compose.yml: both services must reference the same network.

Run dmesg | grep -i oom to see whether the kernel killed a process. Each OOM kill entry names the container and the amount of memory requested. An empty result does not rule out an OOM if the system has rebooted since the incident.

Run docker logs immich-machine-learning --tail 50 to review the last lines. A clean shutdown or a model-loading error will show up here more clearly than a silent kernel OOM kill.

If the network is correct and RAM is sufficient, restart only this service with docker compose restart immich-machine-learning and watch whether jobs resume within the next few minutes using docker logs -f immich-machine-learning.

Before any upgrade, export the database with docker exec -t immich_postgres pg_dumpall -c -U postgres > backup_immich_before_v3.sql. Also keep your UPLOAD_LOCATION folder. A failed HNSW migration halfway through without a backup leaves the database in an inconsistent state.

Edit docker-compose.yml to use version v1.132.3 (exact tag) on both immich-server and immich-machine-learning. Run docker compose pull && docker compose up -d. Let the server start completely and verify that background jobs resume without errors in docker logs immich-server.

v3 uses the official PostgreSQL 17 image with pgvector, not the custom ghcr.io/immich-app/postgres image. In the docker-compose.yml provided with v3, the database service points to the official postgres:17-bookworm image with the pgvector extension. Use the official v3 compose file and do not reuse the v2 file.

Replace the tags with v3.0.0 and pull the images: docker compose pull && docker compose up -d. The HNSW migration starts automatically on first launch. During this phase, the server remains available but smart search and facial recognition are suspended. Follow progress in docker logs -f immich-server: a Finished migration line confirms completion. On a library of 50,000 photos, expect between 10 and 30 minutes depending on the number of vCPUs allocated.

Open the web interface, go to Administration → Jobs and confirm that no jobs are in an error state. If any Smart Search or Face Detection tasks are stalled, restart them from the interface. The new HNSW vectors are computed once: subsequent imports are indexed normally.