immich self-host guide ram at upgrade tips

What you are building

Immich is a self-hosted photo and video backup service — a real replacement for Google Photos. It has a phone app that uploads your camera roll in the background, a timeline, albums, face recognition and machine-learning search that finds "beach" or a person without you ever tagging anything. You run it on a VPS you own, the original files stay on your disk, and nobody scans them to sell you things.

The install is four containers from the project's own Docker Compose file. That part takes ten minutes. The rest of this guide is where the pain lives: the machine-learning container is memory-hungry on a small box, originals eat disk fast, the mobile app refuses a plain-HTTP server, and Immich ships breaking changes often enough that a careless docker compose pull can leave your database unable to start. Treat those four things seriously and Immich is rock-solid. Ignore them and you will lose a weekend.

Mga Prerequisites, at ang mga dapat tandaan

• RAM: ang official docs ay nagsasabing 6 GB minimum at 8 GB recommended — ituring ang 4 GB plus swap bilang absolute floor. Mababa lang ang resource usage ng immich-server at Postgres containers. Ang immich-machine-learning container ang malakas kumain ng memory — niloload nito ang CLIP at face-recognition models sa RAM para sa pagbuo ng search indexes, at sa 2 GB na machine, maaaring i-kill ito ng kernel. Magdagdag ng swap kahit mayroon kang 4 GB.
• Disk: i-size ito para sa buong library mo, plus extra. Ang iyong mga original files ay kokopyahin nang buo, plus ang Immich ay gagawa ng mga thumbnails at preview images (mga 10–20% na dagdag). Ang 200 GB na photo collection ay nangangailangan ng 300 GB na volume. Maliit lang ang Postgres kumpara rito.
• CPU: kahit anong modern KVM VPS ay ayos na, pero mabagal ang ML sa CPU. Ang smart-search indexing ng malaking import ay maaaring tumagal ng ilang oras sa background. Normal ito; hindi nito kailangan ng GPU.
• Isang domain name na naka-point sa VPS. Mas gusto ng mobile app ang HTTPS endpoint, at mainam na gumamit ng reverse proxy sa harap nito. Ang setup na ito ay katulad ng self-hosted Nextcloud instance na may Docker, TLS, at backups — ang Immich ang photo counterpart ng files server na iyon.
• Docker at ang Compose plugin na naka-install — Docker Engine plus ang Compose v2 plugin mula sa official Docker apt repository, gaya ng nakasaad sa aming Docker Compose basics guide.

Step 1: Magdagdag ng swap bago ang lahat

Ang pinakakaraniwang sanhi ng pag-fail ng Immich sa maliliit na VPS ay ang pag-OOM-kill sa ML container. Bigyan muna ang kernel ng extra memory space.

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

Dapat nang ipakita ng free -h ang isang Swap: line na 4.0Gi. Hindi nito bibilis ang ML, pero pipigilan nito ang pag-crash ng container habang nag-i-index sa 4 GB na machine.

Step 2: Kunin ang official compose at env — gamitin ang sa kanila, hindi ang kopya

Naka-pin ng Immich ang mga service version nito at, higit sa lahat, ang database image nito sa loob ng mga files na kasama sa release. Huwag gumamit ng compose file mula sa blog (kasama na ito) bilang source of truth. I-download ang mga release assets:

sudo mkdir -p /opt/immich && cd /opt/immich
sudo wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
sudo wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Galing ang mga ito sa tagged release, kaya tugma ang mga image reference. Ang compose file ay nagtatakda ng apat na services, at makakatulong na malaman ang gamit ng bawat isa bago magsimula:

• immich-server (ghcr.io/immich-app/immich-server, container immich_server) — ang API at web UI, na nakikinig sa port 2283. I-momo-mount nito ang iyong mga upload sa /data.
• immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, container immich_machine_learning) — CLIP search at face recognition. I-ca-cache ang mga downloaded models sa isang model-cache volume. Ito ang service na malakas kumain ng memory.
• database (container immich_postgres) — Postgres na may VectorChord vector extension, na nagpapatakbo ng similarity search. Ang image tag ay naka-pin gamit ang digest sa loob mismo ng compose file, halimbawa ay ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... Ang mga lumang setup ay gumagamit ng pgvecto.rs; tinanggal ang suporta para dito sa Immich v3.0, kaya ang anumang i-install mo ngayon ay VectorChord. Huwag na huwag i-edit nang manual ang tag na ito.
• redis (container immich_redis) — isang Valkey/Redis instance para sa mga job queue.

Step 3: I-configure ang .env — kung saan nakaimbak ang iyong mga litrato at database

Buksan ang .env at i-set ang apat na bagay. Huwag baguhin ang lahat ng nasa ibaba ng marked line.

# Where original uploads are stored on the host
UPLOAD_LOCATION=/opt/immich/library

# Where the Postgres data lives. NEVER put this on an NFS/network share.
DB_DATA_LOCATION=/opt/immich/postgres

# "v3" is a floating tag that tracks the latest v3.x. Pin a full tag like
# v3.0.2 instead — then you upgrade on purpose, not by surprise.
IMMICH_VERSION=v3.0.2

# Change this to a long random string. Letters and digits only.
DB_PASSWORD=REPLACE_WITH_A_LONG_RANDOM_STRING

# Set your timezone so timestamps and "on this day" line up
TZ=Europe/London

###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Dalawang panuntunan para maiwasan ang problema. Dapat nakaturo ang UPLOAD_LOCATION sa iyong malaking disk — kung magkakabit ka ng data volume sa hinaharap, i-set ito sa mount path nito agad, dahil ang paglipat nito pagkatapos ay nangangailangan ng paglilipat ng mga thumbnail at pag-update ng mga asset path. At dapat nasa local disk ang DB_DATA_LOCATION: nagkakaroon ng corruption ang Postgres sa NFS o SMB share, ayon sa dokumentasyon. Kung gagamit ka lamang ng mga letra at digit sa DB_PASSWORD, maiiwasan mo ang mga connection-string escaping bugs.

Step 4: Unang pagtakbo at paggawa ng admin user

cd /opt/immich
sudo docker compose up -d
sudo docker compose ps

Ang tamang resulta ay apat na container, lahat ay running at kalaunan ay healthy:

NAME                      STATUS
immich_machine_learning   Up (healthy)
immich_postgres           Up (healthy)
immich_redis              Up (healthy)
immich_server             Up (healthy)

Ang unang up ay magda-download ng ilang gigabytes na mga image, kaya maghintay. I-monitor ang progress gamit ang sudo docker compose logs -f immich-server; ilalabas ng server sa logs na nakikinig ito sa port 2283 kapag handa na ito. Ngayon, buksan ang http://YOUR_SERVER_IP:2283 sa isang browser. Ang unang pagbisita ay magpapakita ng Getting Started wizard — ang unang account na gagawin mo ang magiging admin. Magtakda ng malakas na password; ang account na ito ang may kontrol sa server settings, user management, at sa ML configuration na kakailanganin mo mamaya.

Step 5: Ang mobile app at background backup

I-install ang "Immich" mula sa App Store o Play Store. Sa login screen, hihingin ang Server Endpoint URL. I-enter ang buong URL kasama ang scheme, halimbawa https://photos.example.com (ang app na ang magdadagdag ng /api). Mag-log in gamit ang account na ginawa mo, pagkatapos ay buksan ang Backup screen ng app, piliin ang mga album na gustong i-protect (karaniwan ay Camera at Screenshots), at i-enable ang Background backup. Ang background backup sa iOS ay nililimitahan ng OS — laging gumagana ang foreground uploads, habang ang background uploads ay nangyayari lamang kapag pinayagan ng OS.

Dito madalas nagkakaproblema ang mga user, kaya basahin muna ang Step 6 bago subukang ayusin ang app.

Step 6: HTTPS via a reverse proxy — at ang full-URL rule

Kailangan ng mobile app ang HTTPS. Maglagay ng reverse proxy sa harap ng port 2283 para i-terminate ang TLS doon. Kung gumagamit ka na ng maraming container, ang Traefik na may automatic TLS para sa maraming Docker apps ang pinakamalinis na opsyon — isang label block lang ang magro-route sa photos.example.com papunta sa immich-server container at kukuha ng certificate para sa iyo. Kung mas gusto mo ang nginx, ang Let's Encrypt gamit ang Certbot at nginx guide ang magbibigay sa iyo ng certificate at proxy_pass http://127.0.0.1:2283; block. May isang proxy setting na mahalaga para sa Immich: itaas ang upload size limit dahil malalaki ang video mula sa phone. Sa nginx, ito ay ang client_max_body_size 50000M; sa loob ng server block — ang default na 1 MB ay magreresulta sa 413 Request Entity Too Large kapag nag-upload ng video.

Ang rule na sinusunod ng app: dapat reachable ang endpoint at, sa praktikal na aspeto, dapat itong HTTPS. Ang mga http:// endpoint, o ang direktang IP na walang port, ang sanhi ng error na "the app cannot reach the server" — tatalakayin ito bilang isang partikular na failure sa ibaba.

Step 7: External libraries vs uploads — pag-import ng existing na photo tree

May dalawang paraan para makapasok ang mga litrato sa Immich, at magkaiba ang mga ito.

• Ang Uploads ay mga asset na pagmamay-ari ng Immich. Kinokopya ng app o web uploader ang file sa UPLOAD_LOCATION. Maaaring i-rename, ilipat, at i-delete ng Immich ang mga ito.
• Ang External libraries ay read-only na import ng mga file na nasa folder na sa iyong server — gaya ng lumang Pictures tree o NAS export. I-i-index ng Immich ang mga ito sa kanilang lokasyon at ipapakita sa timeline, pero hindi nito babaguhin o buburahin ang mga original na file.

Para mag-import ng existing na tree, i-mount ito nang read-only sa server container. I-edit ang docker-compose.yml sa ilalim ng immich-server: at magdagdag ng volume:

  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
      - /srv/photos:/mnt/media/photos:ro

Sinisiguro ng :ro na hindi kailanman mababago ng Immich ang mga original na file. I-recreate ang container gamit ang sudo docker compose up -d, pagkatapos ay pumunta sa web UI sa iyong avatar → Administration → External Libraries → Create Library, piliin ang owning user, i-click ang Add sa ilalim ng Folders, at ilagay ang container path — /mnt/media/photos, hindi ang host path na /srv/photos. I-click ang Scan. Ang paggamit ng host path sa halip na container path ang pinakamadalas na pagkakamali sa external-library; walang mahahanap ang scan at magpapakita ng zero assets.

Step 8: The upgrade discipline Immich demands

This is the part that separates a happy Immich from a broken one. Immich ships fast and does not backport fixes or support downgrades. Blindly tracking the floating v3 tag will eventually break your database. The discipline:

1. Pin a version. Keep IMMICH_VERSION set to a concrete tag like v3.0.2, not the floating v3 that always pulls the newest v3.x.
2. Read the release notes every single time before upgrading. Breaking changes — especially database or vector-extension changes — are called out there. The v3.0 release is the obvious example: it removed pgvecto.rs outright, so anyone still on the old extension had to finish the VectorChord migration (introduced back in v1.133) before they could move up.
3. Back up the database first (Step 9). Always, but doubly so when the notes mention the database.
4. Take the new compose file too. IMMICH_VERSION only pins the server and ML images. The Postgres image is pinned by digest inside docker-compose.yml, so a version that needs a newer database extension ships a new compose file. Re-download both release assets, re-apply your .env values, then upgrade.
5. Update your mobile clients around the same time. The server only speaks its matching major version, and the app supports the current and previous major. A server that has jumped ahead of the app shows Your app major version is not compatible with the server! on the phone until you update it, so it is safest to update the app first.

The actual commands, once you have the new files in place:

cd /opt/immich
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune

Step 9: Backups — isang database dump AT ang mga orihinal, at i-test ito

Ang backup ng Immich ay binubuo ng dalawang bagay, at hindi gagana ang isa kung wala ang isa pa. Ang database ang naglalaman ng album structure, mga mukha, search indexes, at ang map mula sa asset patungo sa file. Ang originals directory ang naglalaman ng mga mismong litrato. Kapag nag-restore ka ng isa nang wala ang isa pa, ang resulta ay mga litratong walang organisasyon o isang empty shell na nakaturo sa mga missing files.

I-dump ang database gamit ang pg_dump mula sa loob ng Postgres container — ang immich database partikular, hindi ang buong cluster:

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

Pagkatapos ay i-backup ang UPLOAD_LOCATION — ang buong /opt/immich/library tree, lalo na ang mga library/, upload/, at profile/ subfolders nito — gamit ang restic, rsync, o borg patungo sa ibang machine o object storage. Unahin ang database bago ang mga file, para hindi mag-reference ang dump sa isang litrato na hindi pa nakokopya ng file backup. Ang mga external library ay dapat i-backup nang hiwalay sa kanilang tunay na source; hindi sila pagmamay-ari ng Immich.

Ngayon ang bahagi na madalas laktawan ng lahat: i-test ang restore. Ang restore ay dapat patakbo sa isang fresh na stack na hindi pa kailanman na-start, sa isang Postgres image na ang vector extension ay compatible sa dump — ito ang dahilan kung bakit hindi dapat basta-basta ang pagpili ng DB image tag. Sa isang scratch box na may kaparehong compose at .env, burahin ang anumang lumang state, i-start lamang ang database, at pagkatapos ay i-load ang dump:

cd /opt/immich
sudo docker compose down -v
sudo docker compose pull
sudo docker compose create
sudo docker start immich_postgres
sleep 10
gunzip --stdout immich-db-2026-07-15.sql.gz |
  sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" |
  sudo docker exec -i immich_postgres psql --dbname=immich --username=postgres --single-transaction --set ON_ERROR_STOP=on
sudo docker compose up -d

Ang sed rewrite ng search_path ay hindi optional sa isang VectorChord database — kapag hindi ito isinama, mag-a-abort ang restore sa gitna ng proseso. Kapag bumalik na ang stack na may kasamang originals, buksan ang web UI: kung nandoon ang iyong mga litrato at album, gumagana ang iyong backup. Kung hindi mo pa ito nasusubukan, wala kang backup — umaasa ka lang.

Failure modes, with the strings you will see

Ang ML container ay OOM-killed. Biglang hihinto ang sudo docker compose logs immich-machine-learning, ipapakita ng docker compose ps na Restarting ito, at ang exit code ay 137. Kinukumpirma ito ng sudo dmesg | grep -i oom: Out of memory: Killed process ... (python3). Mag-i-stall ang search at face jobs. Sanhi ito ng kulang na RAM para sa mga models. Mga solusyon, ayon sa pagkakasunod-sunod: magdagdag ng swap (Step 1); dagdagan ang RAM ng VPS; o, kung hindi talaga kaya, i-disable ang ML sa Administration → Settings → Machine Learning Settings sa pamamagitan ng pag-off ng Smart Search at Facial Recognition — mananatili ang iyong mga backup at albums, pero mawawala ang search-by-content. Ang pagtanggal sa immich-machine-learning service mula sa compose file ay may parehong epekto.

Ayaw mag-start ng Postgres pagkatapos ng upgrade. Mag-lo-loop ang server log sa linyang gaya ng The database currently has VectorChord 0.5.3 activated, but the Postgres instance only has 0.4.2 available. This most likely means the extension was downgraded. — o, sa mga lumang stack, The pgvecto.rs extension is not available in this Postgres instance.. Sanhi ito ng database image na ang extension version ay mas luma kaysa sa upgraded na data, kadalasan dahil sa manual na pag-edit ng image tag o pag-restore ng mas bagong dump sa isang lumang image. Ang fix ay gamitin ang Postgres image na tugma — kunin ang compose file mula sa release na tugma sa iyong database, huwag mag-downgrade, at mag-restore lamang sa isang compatible na image.

Hindi ma-reach ng mobile app ang server. Magpapakita ang login screen ng connection error / Server is not reachable pagkatapos i-enter ang URL. Tatlong sanhi: na-type mo ang http:// kung saan https:// lang ang sineserve ng proxy; kumonekta ka nang direkta sa backend pero hindi isinama ang port, kaya sinubukan nito ang example.com (port 443) sa halip na example.com:2283; o hindi pino-forward ng reverse proxy ang /api. Ayusin ito sa pamamagitan ng pag-enter ng buong https://photos.example.com URL at siguraduhing gumagana ito sa browser ng phone muna. Kung gumagana ang browser pero hindi ang app, tinatanggal ng proxy ang path o self-signed ang certificate — hindi tinatanggap ng app ang mga untrusted certs.

Naubusan ng disk habang nag-i-import. Magsisimulang mag-fail ang uploads, magiging blanko ang mga thumbnail, at ipakikita sa logs ang ENOSPC: no space left on device o, mula sa Postgres, could not extend file ... No space left on device. Ipakikita ng df -h na ang UPLOAD_LOCATION volume ay nasa 100%. Ito ang dahilan kung bakit dapat i-size muna ang disk bago mag-import ng malaking library. I-recover ito sa pamamagitan ng pag-attach ng mas malaking volume, paghinto sa stack, paglipat ng UPLOAD_LOCATION dito, pag-update sa .env, at muling pag-start — o i-expand ang kasalukuyang disk kung pinapayagan ng iyong provider. Maaaring ma-wedge ang Postgres kapag napuno ito, kaya mag-clear muna ng space at i-restart ang database container bago mag-assume ng corruption.

FAQ

Gaano karaming RAM at disk ang kailangan ng Immich?

Ang official requirements ng Immich ay minimum na 6 GB RAM at recommended na 8 GB — ang praktikal na floor para sa maliit na library ay 4 GB kasama ang swap. Siguraduhing naka-configure ang swap dahil ang machine-learning container ang nagdudulot ng spikes sa resource usage. Para sa disk, i-budget ang kabuuang laki ng iyong library plus humigit-kumulang 10–20% para sa mga generated thumbnails at previews sa local storage — huwag ilalagay ang Postgres data directory sa isang network share. Kung nagdedesisyon ka pa kung ano ang iba pang i-run, ang guide sa kung ano ang i-self-host sa 2026 ay nagpapakita ng footprint ng Immich kumpara sa ibang services.

Maaari ko bang i-run ang Immich nang walang GPU?

Oo. Kayang tumakbo ng machine-learning container sa CPU — pinapabilis lamang ng GPU ang smart-search indexing at ang video transcoding (kung gamit ang tamang image variant). Sa CPU, maaaring abutin ng ilang oras sa background ang initial index ng malaking library, pero hindi nito maba-block ang backups o browsing. Kung masyadong maliit ang iyong machine para sa ML, maaari mong i-disable ang Smart Search at Facial Recognition sa admin settings habang pinapanatili ang lahat ng iba pang feature.

Paano ang ligtas na pag-upgrade ng Immich?

I-pin ang IMMICH_VERSION sa isang specific na tag gaya ng v3.0.2, basahin ang release notes bago ang bawat upgrade, at i-back up muna ang database. Dahil ang Postgres image ay naka-pin sa loob ng docker-compose.yml sa halip na sa IMMICH_VERSION, i-download muli ang compose file at ang example.env mula sa iyong target release at i-apply muli ang iyong mga values, pagkatapos ay i-run ang docker compose pull && docker compose up -d. Huwag hayaang mag-float ang version nang walang kontrol — ang Immich ay may mga breaking changes at hindi sumusuporta sa downgrades.

Ano ba ang eksaktong dapat i-back up?

Dalawang bagay nang magkasama: isang pg_dump ng immich database at ang buong UPLOAD_LOCATION originals directory. Ang database ang naglalaman ng mga album, mukha, at ang asset-to-file mapping; ang directory naman ang naglalaman ng mga aktwal na litrato. Ang restore ay nangangailangan ng parehong ito plus isang database image na may compatible na vector extension. Unahin ang database dump bago ang file copy, at i-test ang restore sa isang scratch box nang kahit isang beses — ang backup na hindi na-test ay hindi maituturing na backup.

Paano i-import ang aking existing na photo folder?

I-mount ang folder bilang read-only sa loob ng immich-server container bilang isang extra volume (halimbawa - /srv/photos:/mnt/media/photos:ro), i-recreate ang container, pagkatapos ay pumunta sa Administration → External Libraries para gumawa ng library at i-add ang container path na /mnt/media/photos. I-i-index ng Immich ang mga file sa mismong lokasyon nito at hindi kailanman binabago o binubura ang mga ito. Ang pinakakaraniwang pagkakamali ay ang paglalagay ng host path sa halip na container path, na nagiging sanhi para walang mahanap na files ang scan.