How to Install Immich on a VPS with Docker Compose

Immich is a self-hosted photo and video management platform with automatic mobile uploads, albums, sharing, facial recognition, search and a web timeline. It feels familiar to anyone who has used a commercial cloud photo library, but the server and stored media remain under your control.

The useful part is not merely getting the containers to start. A dependable installation needs enough memory for imports, fast local storage for PostgreSQL, HTTPS for the mobile apps, monitored disk space and a backup that includes both the database and the media library. This guide covers that complete path on an Ubuntu VPS.

Immich VPS Requirements

Immich's current official requirements specify at least 2 CPU cores and 6 GB RAM, with 4 cores and 8 GB RAM recommended. A smaller 4 GB server can run without machine-learning features, but it leaves little room during large imports.

Original media is only part of the storage calculation. Thumbnails and transcoded video typically add another 10-20% to the library. PostgreSQL should remain on local SSD storage; Immich explicitly advises against putting its database files on a network share.

For a HYEHOST deployment, choose a Cloud VPS with at least 8 GB RAM for a normal household library. If the originals will outgrow the VPS disk, mount additional storage at the operating-system level while keeping the database on SSD. Wolverhampton HDD add-on storage can suit large media libraries, but it is not a substitute for an independent backup.

Prepare Ubuntu and Docker

Deploy a clean Ubuntu 24.04 LTS VPS, add an SSH key, then connect as root:

ssh root@203.0.113.10
apt update && apt full-upgrade -y
apt install -y ca-certificates curl wget openssl

Install Docker Engine from Docker's official repository by following our Docker installation guide. Confirm that the current Compose plugin is available:

docker --version
docker compose version

Immich requires the space-separated docker compose command. The older docker-compose package is deprecated and unsupported.

Install Immich with the Official Compose Files

Create a dedicated directory and download the files published with the latest Immich release:

mkdir -p /opt/immich
cd /opt/immich
wget -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

Open the environment file:

nano /opt/immich/.env

Set the media path, database path, timezone and a random alphanumeric database password:

UPLOAD_LOCATION=/srv/immich/library
DB_DATA_LOCATION=/var/lib/immich-postgres
TZ=Europe/London
IMMICH_VERSION=v3
DB_PASSWORD=replace_with_a_long_random_alphanumeric_password

Create the directories before starting the stack:

mkdir -p /srv/immich/library /var/lib/immich-postgres
chmod 700 /var/lib/immich-postgres

If Nginx will provide HTTPS on the same server, edit the published port in docker-compose.yml from 2283:2283 to:

ports:
  - "127.0.0.1:2283:2283"

This keeps Immich reachable by the local reverse proxy without publishing its application port directly to the internet. Start the containers:

cd /opt/immich
docker compose up -d
docker compose ps
docker compose logs --tail=100

The database, server and machine-learning containers should settle into a healthy state. If a service repeatedly restarts, read its logs before changing random settings; memory pressure, an invalid path and an unsuitable password are common causes.

Put Immich Behind Nginx and HTTPS

Create an A record such as photos.example.com pointing to the VPS. HYEHOST HYE DNS can manage the zone, DNSSEC and API-driven record changes from the same panel as your infrastructure.

Install Nginx and Certbot:

apt install -y nginx certbot python3-certbot-nginx

Create /etc/nginx/sites-available/immich:

server {
    listen 80;
    listen [::]:80;
    server_name photos.example.com;

    client_max_body_size 0;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;

    location / {
        proxy_pass http://127.0.0.1:2283;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the site, test the configuration and request the certificate:

ln -s /etc/nginx/sites-available/immich /etc/nginx/sites-enabled/immich
nginx -t
systemctl reload nginx
certbot --nginx -d photos.example.com

Visit https://photos.example.com and create the first administrator account immediately. Use a unique password and do not leave a fresh registration page unattended on a public address.

Connect the Mobile App and Start Backups Carefully

Install the official Immich mobile app, enter the complete HTTPS server URL and sign in. On the backup screen, select the albums or camera folders you want uploaded.

• Begin with a small album to confirm uploads, thumbnails and playback.
• Choose whether mobile data may be used before starting a large library.
• Keep the phone charging during the first import.
• Do not delete another photo backup until an Immich restore has been tested.

Large first imports create thumbnail, metadata, face-recognition and video-transcoding jobs. High CPU use during this phase is expected. Watch the Administration jobs page and avoid changing several performance settings at once.

Design Storage Before the Library Grows

Keep the roles distinct:

• PostgreSQL: local SSD at DB_DATA_LOCATION.
• Originals and uploads: the filesystem mounted at UPLOAD_LOCATION.
• Thumbnails and encoded video: generated data beneath the upload location.
• Backups: another server, object store or physical device.

Monitor available space at the upload path. A full filesystem can interrupt uploads and database operations long before anyone notices the timeline behaving oddly:

df -h /srv/immich/library /var/lib/immich-postgres
docker system df

Do not run broad Docker cleanup commands on a production server without understanding what they remove. Named volumes and images may belong to services outside Immich.

Back Up the Database and Every Media Directory

A snapshot of the Compose file is not a photo backup. A recoverable Immich installation needs both a PostgreSQL dump and the files stored beneath UPLOAD_LOCATION. The database contains users, albums, metadata and the relationships that make the library usable.

Create a compressed database dump using the values from your .env file:

mkdir -p /srv/backups/immich
docker exec -t immich_postgres pg_dump \
  --clean --if-exists \
  --dbname=immich \
  --username=postgres | gzip > /srv/backups/immich/immich-$(date +%F).sql.gz

Then copy the dump and the whole Immich media tree off the VPS with a tool such as Restic, BorgBackup or Kopia. Immich's restore process expects the media folders and database to describe the same point in time, so schedule them together and retain several generations.

Test the process on a fresh temporary installation. A backup is only proven when you can restore it, sign in and open original photos and videos.

Update Immich Without Turning the Library into a Test Environment

Immich develops quickly. Read the official upgrade notes, update mobile clients and take a current backup before changing the server version. The server and mobile app should use compatible major versions.

cd /opt/immich
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100

Pin IMMICH_VERSION deliberately instead of treating every release notification as an instruction to update immediately. Downgrades are not supported, which makes a tested backup and a short maintenance window more valuable than speed.

Immich Security Checklist

• Use SSH keys and keep the operating system patched.
• Expose only SSH, HTTP and HTTPS; bind port 2283 to localhost.
• Use a unique administrator password and review user accounts.
• Keep PostgreSQL private and on local SSD storage.
• Protect the domain with HTTPS before connecting mobile apps.
• Monitor disk capacity, failed logins, container health and backup age.
• Back up originals and PostgreSQL off-server.
• Read release notes before upgrades and test restores regularly.

Frequently Asked Questions

Can Immich replace Google Photos?

It can provide automatic mobile backup, a timeline, albums, sharing and search on infrastructure you control. It does not remove the operational work: you must maintain the server, monitor storage and protect the library with independent backups.

Can Immich run on a 4 GB VPS?

It can run with machine learning disabled, but the official minimum is 6 GB RAM and 8 GB is recommended. Large imports are much smoother with additional memory.

Can I put the Immich database on network storage?

No. Immich recommends local SSD storage for PostgreSQL and explicitly states that network shares are unsupported for the database files.

Does a VPS snapshot replace an Immich backup?

No. Snapshots are useful before upgrades, but the dependable plan is an application-aware PostgreSQL dump plus a separate copy of every media directory, stored away from the VPS.

Build the Recovery Plan Before Trusting It with Memories

Immich is an excellent self-hosted photo platform because it makes a private library pleasant to use, not merely possible. The first Compose command is the easy bit. The installation becomes dependable when the database stays on SSD, the public service uses HTTPS, storage growth is monitored and both media and metadata can be restored elsewhere.

Start with a small test album, prove mobile uploads, take a backup and perform a restore. Once that works, the rest of the library has somewhere trustworthy to go.

Official Resources

• Immich Docker Compose installation
• Immich system requirements
• Immich backup and restore
• Immich upgrade guide
• HYEHOST Cloud VPS