Cara Self-Host Immich dengan RAM 6 GB

Apa yang Anda bangun

Immich adalah layanan pencadangan foto dan video mandiri (self-hosted) — pengganti nyata untuk Google Photos. Layanan ini memiliki aplikasi ponsel yang mengunggah galeri kamera Anda di latar belakang, fitur timeline, album, pengenalan wajah, dan pencarian berbasis machine learning yang dapat menemukan kata kunci seperti "beach" atau orang tertentu tanpa perlu melakukan tagging secara manual. Anda menjalankannya pada VPS milik sendiri, file asli tetap berada di disk Anda, dan tidak ada pihak lain yang memindai file tersebut untuk keperluan iklan.

Instalasi menggunakan empat container dari file Docker Compose bawaan proyek ini. Proses tersebut membutuhkan waktu sepuluh menit. Bagian tersulit ada pada sisa panduan ini: container machine-learning membutuhkan memori besar pada server kecil, file asli menghabiskan ruang disk dengan cepat, aplikasi seluler menolak server HTTP biasa, dan Immich sering merilis perubahan yang bersifat breaking changes sehingga docker compose pull yang ceroboh dapat menyebabkan database gagal berjalan. Tangani empat hal tersebut dengan serius agar Immich berjalan stabil. Jika diabaikan, Anda akan membuang waktu akhir pekan Anda.

Prasyarat, dan kendala yang nyata

• RAM: dokumentasi resmi menyatakan minimum 6 GB dan rekomendasi 8 GB — anggap 4 GB ditambah swap sebagai batas minimum mutlak. Kontainer immich-server dan Postgres membutuhkan sumber daya yang kecil. Kontainer immich-machine-learning adalah yang paling berat — kontainer ini memuat model CLIP dan pengenalan wajah ke dalam RAM untuk membangun indeks pencarian, dan pada mesin dengan 2 GB, kernel akan menghentikan prosesnya. Tambahkan swap meskipun Anda memiliki 4 GB.
• Disk: siapkan kapasitas untuk seluruh pustaka Anda, ditambah cadangan. Foto asli disalin sepenuhnya, ditambah Immich menghasilkan thumbnail dan gambar pratinjau (sekitar 10–20% tambahan). Koleksi foto sebesar 200 GB membutuhkan volume 300 GB. Postgres jauh lebih kecil jika dibandingkan.
• CPU: VPS KVM modern apa pun dapat digunakan, tetapi ML pada CPU berjalan lambat. Pengindeksan smart-search untuk impor besar dapat berjalan selama berjam-jam di latar belakang. Hal ini normal; proses ini tidak memerlukan GPU.
• Nama domain yang diarahkan ke VPS. Aplikasi seluler sangat menyarankan endpoint HTTPS, dan Anda memerlukan reverse proxy di depannya. Konfigurasi ini serupa dengan instansi self-hosted Nextcloud dengan Docker, TLS, dan backup — Immich adalah padanan server foto untuk server file tersebut.
• Docker dan plugin Compose sudah terinstal — Docker Engine ditambah plugin Compose v2 dari repositori apt resmi Docker, persis seperti yang dibahas dalam panduan dasar Docker Compose kami.

Langkah 1: Tambahkan swap sebelum hal lainnya

Kegagalan Immich yang paling umum pada VPS kecil adalah container ML terkena OOM-kill. Berikan ruang bagi kernel untuk bekerja terlebih dahulu.

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

free -h sekarang harus menunjukkan baris Swap: sebesar 4.0Gi. Hal ini tidak akan mempercepat ML, tetapi mencegah container berhenti saat proses indexing pada mesin 4 GB.

Step 2: Ambil compose dan env resmi — gunakan milik mereka, bukan salinan

Immich menetapkan versi layanan dan, yang terpenting, citra database di dalam file yang mereka sediakan. Jangan gunakan file compose dari blog (termasuk blog ini) sebagai sumber utama. Unduh aset rilis berikut:

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

File ini berasal dari rilis bertanda (tagged release), sehingga referensi citra akan sesuai. File compose mendefinisikan empat layanan, dan penting untuk mengetahui fungsi masing-masing sebelum Anda melakukan perubahan:

• immich-server (ghcr.io/immich-app/immich-server, container immich_server) — API dan web UI, berjalan pada port 2283. Layanan ini melakukan mount unggahan Anda ke /data.
• immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, container immich_machine_learning) — Pencarian CLIP dan pengenalan wajah. Menyimpan cache model yang diunduh dalam volume model-cache. Layanan ini membutuhkan memori besar.
• database (container immich_postgres) — Postgres dengan ekstensi vektor VectorChord, yang menjalankan pencarian kemiripan. Tag citra dikunci menggunakan digest langsung di dalam file compose, contohnya ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... Pengaturan lama menggunakan pgvecto.rs; dukungan tersebut telah dihapus pada Immich v3.0, sehingga semua instalasi saat ini menggunakan VectorChord. Jangan mengubah tag ini secara manual.
• redis (container immich_redis) — instansi Valkey/Redis untuk antrean tugas (job queues).

Langkah 3: Konfigurasi .env — tempat penyimpanan foto dan database Anda

Buka .env dan atur empat hal. Semua pengaturan di bawah garis penanda tidak perlu diubah.

# 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

Dua aturan untuk menghindari masalah. UPLOAD_LOCATION harus mengarah ke disk besar Anda — jika Anda memasang volume data di kemudian hari, atur ini ke jalur mount-nya sejak awal, karena memindahkannya nanti berarti harus memindahkan thumbnail dan memperbarui jalur aset. Dan DB_DATA_LOCATION harus berada di disk lokal: Postgres akan mengalami korupsi data pada share NFS atau SMB, sebagaimana dinyatakan dalam dokumentasi. Jika Anda hanya menggunakan huruf dan angka pada DB_PASSWORD, Anda dapat menghindari jenis bug escaping pada connection-string.

Step 4: Menjalankan pertama kali dan membuat pengguna admin

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

Hasil yang benar adalah empat kontainer, semuanya running dan akhirnya healthy:

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

up pertama akan mengunduh beberapa gigabyte citra, jadi tunggu prosesnya selesai. Pantau progres dengan sudo docker compose logs -f immich-server; server akan mencatat bahwa ia mendengarkan pada port 2283 setelah siap. Sekarang buka http://YOUR_SERVER_IP:2283 di browser. Kunjungan pertama akan menampilkan wizard Getting Started — akun pertama yang Anda buat adalah admin. Gunakan kata sandi yang kuat; akun ini mengelola pengaturan server, manajemen pengguna, dan konfigurasi ML yang akan Anda butuhkan nanti.

Langkah 5: Aplikasi seluler dan pencadangan latar belakang

Instal "Immich" dari App Store atau Play Store. Pada layar login, Anda akan diminta memasukkan Server Endpoint URL. Masukkan URL lengkap termasuk skemanya, contohnya https://photos.example.com (aplikasi akan menambahkan /api secara otomatis). Login menggunakan akun yang baru saja Anda buat, lalu buka layar Backup pada aplikasi, pilih album yang ingin dicadangkan (biasanya Camera dan Screenshots), dan aktifkan Background backup. Pencadangan latar belakang pada iOS dibatasi oleh OS — unggahan saat aplikasi terbuka (foreground) akan selalu berjalan, sedangkan unggahan latar belakang (background) hanya berjalan saat OS mengizinkan.

Banyak pengguna mengalami kendala pada tahap ini, jadi baca Langkah 6 sebelum mencoba memperbaiki aplikasi secara manual.

Langkah 6: HTTPS melalui reverse proxy — dan aturan full-URL

Aplikasi seluler memerlukan HTTPS. Gunakan reverse proxy di depan port 2283 untuk melakukan terminasi TLS. Jika Anda sudah menjalankan beberapa kontainer, Traefik dengan TLS otomatis untuk banyak aplikasi Docker adalah opsi yang paling rapi — satu blok label akan mengarahkan photos.example.com ke kontainer immich-server dan mengambilkan sertifikat untuk Anda. Jika Anda lebih memilih nginx, panduan Let's Encrypt dengan Certbot dan nginx akan memberikan Anda sertifikat dan blok proxy_pass http://127.0.0.1:2283;. Satu pengaturan proxy sangat penting untuk Immich: tingkatkan batas ukuran unggahan, karena video ponsel berukuran besar. Pada nginx, pengaturannya adalah client_max_body_size 50000M; di dalam blok server — nilai default 1 MB akan menolak unggahan video dengan 413 Request Entity Too Large.

Aturan yang diterapkan aplikasi: endpoint harus dapat dijangkau dan, dalam praktiknya, harus menggunakan HTTPS. Endpoint http://, atau IP langsung tanpa menyertakan port, adalah penyebab munculnya pesan kesalahan "the app cannot reach the server" — dibahas sebagai kegagalan spesifik di bawah ini.

Step 7: External libraries vs uploads — mengimpor struktur foto yang sudah ada

Ada dua cara foto masuk ke Immich, dan keduanya berbeda.

• Uploads adalah aset milik Immich. Aplikasi atau pengunggah web menyalin file ke dalam UPLOAD_LOCATION. Immich dapat mengubah nama, memindahkan, dan menghapus file tersebut.
• External libraries adalah impor baca-saja (read-only) dari file yang sudah ada di folder pada server Anda — seperti struktur Pictures lama atau ekspor NAS. Immich mengindeks file tersebut di lokasi aslinya dan menampilkannya di timeline, tetapi tidak pernah mengubah atau menghapus file asli.

Untuk mengimpor struktur yang sudah ada, pasang (mount) folder tersebut secara read-only ke dalam kontainer server. Edit docker-compose.yml di bawah immich-server: dan tambahkan volume:

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

Penggunaan :ro menjamin Immich tidak akan pernah dapat menyentuh file asli. Buat ulang kontainer dengan sudo docker compose up -d, lalu pada UI web buka avatar Anda → Administration → External Libraries → Create Library, pilih pengguna pemilik, klik Add di bawah Folders, dan masukkan jalur kontainer — /mnt/media/photos, bukan jalur host /srv/photos. Klik Scan. Menggunakan jalur host alih-alih jalur kontainer adalah kesalahan utama pada external-library; pemindaian tidak akan menemukan apa pun dan melaporkan nol aset.

Step 8: Kedisiplinan upgrade yang dibutuhkan Immich

Bagian ini membedakan instalasi Immich yang berjalan lancar dengan yang rusak. Immich merilis pembaruan dengan cepat dan tidak memberikan perbaikan ke versi lama (backport) atau mendukung downgrade. Mengikuti tag v3 yang bersifat floating akan merusak database Anda. Kedisiplinan yang diperlukan:

1. Tetapkan versi tertentu. Atur IMMICH_VERSION ke tag spesifik seperti v3.0.2, jangan gunakan v3 yang selalu mengambil v3.x terbaru.
2. Baca catatan rilis setiap kali sebelum melakukan upgrade. Perubahan yang merusak (breaking changes) — terutama pada database atau ekstensi vektor — disebutkan di sana. Rilis v3.0 adalah contoh nyata: rilis tersebut menghapus pgvecto.rs sepenuhnya, sehingga pengguna ekstensi lama harus menyelesaikan migrasi VectorChord (diperkenalkan pada v1.133) sebelum bisa melakukan upgrade.
3. Cadangkan database terlebih dahulu (Step 9). Lakukan selalu, terutama jika catatan rilis menyebutkan tentang database.
4. Unduh juga file compose yang baru. IMMICH_VERSION hanya menetapkan versi untuk image server dan ML. Image Postgres ditetapkan melalui digest di dalam docker-compose.yml, sehingga versi yang membutuhkan ekstensi database baru akan menyertakan file compose baru. Unduh ulang kedua aset rilis, terapkan kembali nilai .env Anda, lalu lakukan upgrade.
5. Perbarui aplikasi seluler di waktu yang hampir bersamaan. Server hanya mendukung versi mayor yang sesuai, dan aplikasi hanya mendukung versi mayor saat ini dan versi sebelumnya. Server yang versinya lebih tinggi dari aplikasi akan menampilkan Your app major version is not compatible with the server! pada ponsel hingga aplikasi diperbarui, jadi cara paling aman adalah memperbarui aplikasi terlebih dahulu.

Perintah aktual setelah file baru tersedia:

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

Step 9: Backup — dump database PLUS file asli, dan uji coba

Backup Immich terdiri dari dua komponen, dan salah satunya saja tidak berguna. Database menyimpan struktur album, wajah, indeks pencarian, dan pemetaan dari aset ke file. Direktori originals menyimpan foto asli. Melakukan restore salah satunya saja akan menghasilkan foto tanpa organisasi atau kerangka kosong yang merujuk ke file yang hilang.

Lakukan dump database dengan pg_dump dari dalam kontainer Postgres — khusus untuk database immich, bukan seluruh 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

Kemudian backup UPLOAD_LOCATION — seluruh struktur /opt/immich/library, terutama subfolder library/, upload/, dan profile/ — menggunakan restic, rsync, atau borg ke mesin lain atau object storage. Lakukan backup database terlebih dahulu sebelum file, agar dump tidak merujuk ke foto yang belum disalin oleh backup file. Library eksternal harus di-backup secara terpisah di lokasi aslinya; Immich tidak memilikinya.

Sekarang bagian yang sering dilewati: uji coba restore. Restore harus dijalankan pada stack baru yang servernya belum pernah dijalankan, pada image Postgres yang ekstensi vector-nya kompatibel dengan dump — itulah alasan mengapa Anda tidak boleh sembarangan menggunakan tag image DB. Pada mesin kosong dengan compose dan .env yang sama, hapus semua data lama, jalankan hanya database, lalu muat 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

Penulisan ulang sed pada search_path bersifat wajib pada database VectorChord — jika dilewati, proses restore akan terhenti di tengah jalan. Setelah stack berjalan kembali dengan file originals yang sudah ada, buka web UI: jika foto dan album Anda muncul, backup Anda berhasil. Jika Anda belum pernah melakukan ini, Anda tidak memiliki backup — Anda hanya memiliki harapan.

Mode kegagalan, dengan string yang akan Anda lihat

Kontainer ML terkena OOM-kill. sudo docker compose logs immich-machine-learning berhenti tiba-tiba, docker compose ps menunjukkan Restarting, dan kode keluar adalah 137. sudo dmesg | grep -i oom mengonfirmasinya: Out of memory: Killed process ... (python3). Pekerjaan search dan face kemudian terhenti. Penyebabnya adalah RAM tidak cukup untuk model. Solusi, secara berurutan: tambahkan swap (Langkah 1); berikan RAM lebih besar pada VPS; atau, jika benar-benar tidak bisa, nonaktifkan ML di Administration → Settings → Machine Learning Settings dengan mematikan Smart Search dan Facial Recognition — Anda tetap memiliki cadangan dan album, tetapi kehilangan fitur pencarian berbasis konten. Menghapus layanan immich-machine-learning dari file compose memiliki efek yang sama.

Postgres menolak untuk berjalan setelah pembaruan. Log server berulang dengan baris seperti 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. — atau, pada stack lama, The pgvecto.rs extension is not available in this Postgres instance.. Penyebabnya adalah citra database yang versi ekstensinya lebih lama daripada versi data yang telah diperbarui, hampir selalu karena mengedit tag citra secara manual atau memulihkan dump yang lebih baru ke citra yang lebih lama. Solusinya adalah menggunakan citra Postgres yang sesuai — ambil file compose dari rilis yang sesuai dengan database Anda, jangan lakukan downgrade, dan lakukan pemulihan hanya pada citra yang kompatibel.

Aplikasi seluler tidak dapat menjangkau server. Layar login menampilkan kesalahan koneksi / Server is not reachable setelah Anda memasukkan URL. Tiga penyebab: Anda mengetik http:// padahal proxy hanya melayani https://; Anda terhubung langsung ke backend tetapi tidak menyertakan port, sehingga mencoba example.com (port 443) alih-alih example.com:2283; atau reverse proxy tidak meneruskan /api. Perbaiki dengan memasukkan URL https://photos.example.com lengkap dan pastikan URL tersebut dapat dimuat di browser ponsel terlebih dahulu. Jika browser berfungsi tetapi aplikasi tidak, proxy menghapus path atau sertifikat bersifat self-signed — aplikasi menolak sertifikat yang tidak terpercaya.

Disk penuh saat proses impor. Unggahan mulai gagal, thumbnail menjadi kosong, dan log menunjukkan ENOSPC: no space left on device atau, dari Postgres, could not extend file ... No space left on device. df -h menunjukkan volume UPLOAD_LOCATION mencapai 100%. Inilah alasan mengapa Anda harus menentukan ukuran disk sebelum mengimpor pustaka besar. Pulihkan dengan memasangkan volume yang lebih besar, menghentikan stack, memindahkan UPLOAD_LOCATION ke dalamnya, memperbarui .env, dan memulai kembali — atau perluas disk yang ada jika penyedia Anda mengizinkannya. Postgres dapat mengalami kemacetan jika disk penuh, jadi kosongkan ruang dan mulai ulang kontainer database sebelum berasumsi terjadi korupsi data.

FAQ

Berapa RAM dan disk yang dibutuhkan Immich?

Persyaratan resmi Immich adalah minimum 6 GB RAM dan 4 GB dengan swap adalah batas praktis untuk pustaka kecil, sedangkan 8 GB sangat disarankan — konfigurasikan swap dalam kondisi apa pun, karena container machine-learning menyebabkan lonjakan penggunaan. Untuk disk, siapkan kapasitas sebesar ukuran total pustaka Anda ditambah sekitar 10–20% untuk thumbnail dan pratinjau yang dihasilkan pada penyimpanan lokal — jangan pernah menempatkan direktori data Postgres di network share. Jika Anda masih mempertimbangkan layanan lain, panduan layanan self-host tahun 2026 membandingkan penggunaan sumber daya Immich dengan layanan lainnya.

Bisakah saya menjalankan Immich tanpa GPU?

Bisa. Container machine-learning dapat berjalan menggunakan CPU — GPU hanya mempercepat pengindeksan smart-search dan transcoding video jika menggunakan varian image yang tepat. Pada CPU, pengindeksan awal untuk pustaka besar dapat memakan waktu berjam-jam di latar belakang, tetapi tidak mengganggu proses backup atau penjelajahan. Jika perangkat Anda terlalu kecil untuk ML, Anda dapat menonaktifkan Smart Search dan Facial Recognition di pengaturan admin dan tetap menggunakan fitur lainnya.

Bagaimana cara memperbarui Immich dengan aman?

Pin IMMICH_VERSION ke tag spesifik seperti v3.0.2, baca release notes sebelum setiap pembaruan, dan lakukan backup database terlebih dahulu. Karena image Postgres dipaku di dalam docker-compose.yml dan bukan melalui IMMICH_VERSION, unduh ulang file compose dan example.env dari versi target Anda, terapkan kembali nilai konfigurasi Anda, lalu jalankan docker compose pull && docker compose up -d. Jangan biarkan versi berjalan secara otomatis (floating) — Immich menyertakan perubahan yang bersifat breaking changes dan tidak mendukung downgrade.

Apa saja yang harus saya backup?

Dua hal secara bersamaan: pg_dump dari database immich dan seluruh direktori originals UPLOAD_LOCATION. Database menyimpan album, wajah, dan pemetaan aset ke file; direktori menyimpan foto asli, dan proses restore membutuhkan keduanya ditambah image database dengan ekstensi vektor yang kompatibel. Lakukan dump database terlebih dahulu, kemudian salin file, dan uji coba restore pada perangkat percobaan setidaknya satu kali — backup yang tidak diuji bukanlah backup.

Bagaimana cara mengimpor folder foto yang sudah ada?

Mount folder tersebut sebagai volume tambahan (misalnya - /srv/photos:/mnt/media/photos:ro) ke dalam container immich-server dengan mode read-only, buat ulang container, lalu di Administration → External Libraries buatlah sebuah library dan tambahkan path container /mnt/media/photos. Immich mengindeks file di lokasi aslinya dan tidak akan memodifikasi atau menghapus file tersebut. Kesalahan paling umum adalah memasukkan path host alih-alih path container, yang menyebabkan pemindaian tidak menemukan data apa pun.