Immich Self-Hosting: RAM 6 GB dan Upgrade Aman

Yang Anda bangun

Immich adalah layanan pencadangan foto dan video yang di-hosting sendiri, sebagai pengganti Google Photos yang sebenarnya. Immich memiliki aplikasi ponsel yang mengunggah camera roll Anda di latar belakang, timeline, album, pengenalan wajah, serta pencarian machine learning yang dapat menemukan “pantai” atau seseorang tanpa Anda perlu menambahkan tag apa pun. Anda menjalankannya pada VPS milik sendiri, file asli tetap tersimpan di disk Anda, dan tidak ada pihak yang memindainya untuk menjual sesuatu kepada Anda. Jika Anda masih membandingkannya dengan kandidat lain yang jelas, perbandingan PhotoPrism dan Immich kami menyajikan kebutuhan RAM minimum, aplikasi ponsel, dan perintah pencadangan keduanya secara berdampingan.

Instalasi ini terdiri dari empat container dari file Docker Compose milik project tersebut. Bagian itu selesai dalam sepuluh menit. Bagian lain dalam panduan ini adalah sumber masalahnya: container machine learning membutuhkan banyak memori pada mesin kecil, file asli cepat memenuhi disk, aplikasi seluler menolak server HTTP biasa, dan Immich cukup sering merilis perubahan yang merusak kompatibilitas sehingga docker compose pull yang dilakukan tanpa hati-hati dapat membuat database Anda tidak dapat dijalankan. Tangani keempat hal tersebut dengan serius, dan Immich akan sangat stabil. Abaikan, dan Anda akan kehilangan waktu sepanjang akhir pekan.

Prasyarat dan hal penting yang perlu diketahui

• RAM: dokumentasi resmi menyebutkan minimum 6 GB dan merekomendasikan 8 GB; anggap 4 GB ditambah swap sebagai batas minimum absolut. Container immich-server dan Postgres tidak terlalu membutuhkan sumber daya. Container immich-machine-learning paling banyak menggunakan RAM karena memuat model CLIP dan pengenalan wajah ke RAM untuk membuat indeks pencarian. Pada server dengan RAM 2 GB, kernel akan menghentikan container tersebut. Tambahkan swap meskipun RAM Anda 4 GB.
• Disk: tentukan ukurannya berdasarkan seluruh pustaka Anda, lalu tambahkan ruang cadangan. File asli disalin sepenuhnya. Immich juga membuat thumbnail dan gambar pratinjau, dengan tambahan sekitar 10–20%. Koleksi foto berukuran 200 GB memerlukan volume 300 GB. Dibandingkan itu, Postgres hanya membutuhkan sedikit ruang.
• CPU: KVM VPS modern apa pun sudah memadai, tetapi ML pada CPU berjalan lambat. Pengindeksan smart search untuk impor berukuran besar dapat berjalan selama berjam-jam di latar belakang. Ini normal. GPU tidak diperlukan.
• Nama domain yang diarahkan ke VPS. Aplikasi seluler sangat menyarankan endpoint HTTPS. Anda juga memerlukan reverse proxy di depannya. Bentuk setup ini sama dengan instance Nextcloud self-hosted dengan Docker, TLS, dan backup. Immich adalah pasangan untuk foto dari server file tersebut.
• Docker dan plugin Compose yang sudah terpasang. Gunakan Docker Engine serta plugin Compose v2 dari repositori apt milik Docker, persis seperti yang dibahas dalam panduan dasar Docker Compose kami.

Langkah 1: Tambahkan swap sebelum melakukan hal lain

Kegagalan Immich yang paling umum pada VPS kecil adalah container ML dihentikan oleh OOM. Sediakan ruang bagi kernel 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 seharusnya menampilkan baris Swap: sebesar 4.0Gi. Ini tidak akan membuat ML berjalan cepat, tetapi mencegah container berhenti saat proses pengindeksan berlangsung pada mesin dengan 4 GB RAM.

Langkah 2: Ambil file compose dan env resmi, gunakan file tersebut, bukan salinan

Immich menetapkan versi servicenya dan, yang terpenting, image databasenya di dalam file yang dirilis bersama software. Jangan menyalin file compose dari blog, termasuk blog ini, sebagai sumber acuan utama. Unduh aset rilis:

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 tersebut berasal dari rilis bertag, sehingga referensi image-nya sesuai. File compose mendefinisikan empat service. Sebelum mengubah apa pun, pahami fungsi masing-masing service:

• immich-server (ghcr.io/immich-app/immich-server, container immich_server), API dan UI web yang listening pada port 2283. Service ini melakukan mount direktori upload Anda ke /data.
• immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, container immich_machine_learning), untuk pencarian CLIP dan pengenalan wajah. Model yang diunduh disimpan dalam cache pada volume model-cache. Service ini paling banyak menggunakan memori.
• database (container immich_postgres), Postgres dengan ekstensi vektor VectorChord, yang menyediakan fungsi pencarian kemiripan. Tag image ditetapkan berdasarkan digest langsung di file compose, misalnya ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... Setup lama menggunakan pgvecto.rs; dukungan untuknya dihapus pada Immich v3.0, sehingga semua instalasi baru menggunakan VectorChord. Jangan mengubah tag ini secara manual.
• redis (container immich_redis), instance Valkey/Redis untuk antrean job.

Langkah 3: Konfigurasikan .env, tempat foto dan database Anda disimpan

Buka .env dan tetapkan empat hal. Semua bagian setelah baris yang ditandai tetap seperti semula.

# 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

Ada dua aturan yang dapat mencegah masalah. UPLOAD_LOCATION harus mengarah ke disk berkapasitas besar. Jika Anda menambahkan volume data nanti, tetapkan nilainya ke path mount volume tersebut sejak awal. Jika tidak, Anda harus memindahkan thumbnail dan memperbarui path aset. Selain itu, DB_DATA_LOCATION harus berada pada disk lokal. Postgres dapat mengalami kerusakan data jika menggunakan share NFS atau SMB, dan dokumentasi menyatakannya secara eksplisit. Jika Anda hanya menggunakan huruf dan digit dalam DB_PASSWORD, Anda dapat menghindari sejumlah masalah escaping pada connection string.

Langkah 4: Menjalankan untuk pertama kali dan membuat pengguna admin

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

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

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

up pertama mengunduh beberapa gigabyte image, jadi tunggu prosesnya. Pantau progres dengan sudo docker compose logs -f immich-server; server mencatat bahwa server sedang listen pada port 2283 setelah siap. Sekarang buka http://YOUR_SERVER_IP:2283 di browser. Kunjungan pertama menampilkan wizard Memulai, dan akun pertama yang dibuat menjadi admin. Tetapkan password yang kuat; akun ini mengelola pengaturan server, manajemen pengguna, serta konfigurasi ML yang akan Anda perlukan nanti.

Langkah 5: Aplikasi seluler dan pencadangan latar belakang

Instal "Immich" dari App Store atau Play Store. Pada layar login, aplikasi meminta Server Endpoint URL. Masukkan URL lengkap beserta skemanya, misalnya https://photos.example.com (aplikasi akan menambahkan /api sendiri). Login menggunakan akun yang baru saja Anda buat, lalu buka layar Backup pada aplikasi, pilih album yang ingin dicadangkan (biasanya Camera dan Screenshots), kemudian aktifkan Background backup. Pencadangan latar belakang di iOS dibatasi oleh sistem operasi. Upload saat aplikasi berada di latar depan selalu berjalan, sedangkan upload di latar belakang berlangsung saat diizinkan oleh sistem operasi.

Di sinilah banyak orang mengalami kendala. Karena itu, baca Langkah 6 sebelum mencoba memperbaiki masalah pada aplikasi.

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

Aplikasi mobile sangat memerlukan HTTPS. Tempatkan reverse proxy di depan port 2283 dan lakukan TLS termination di sana. Jika Anda sudah menjalankan beberapa container, Traefik dengan TLS otomatis untuk beberapa aplikasi Docker adalah pilihan yang paling rapi. Satu blok label merutekan photos.example.com ke container immich-server dan mengambil sertifikat untuk Anda. Jika Anda lebih memilih nginx, panduan Let's Encrypt dengan Certbot dan nginx akan memperoleh sertifikat dan blok proxy_pass http://127.0.0.1:2283;. Setelah proxy tersebut tersedia, penambahan service berikutnya biasanya hanya memerlukan subdomain baru. Dengan cara ini, frontend media seperti Halcyon, tampilan toko video era 90-an untuk Jellyfin dapat berjalan berdampingan dengan Immich pada server yang sama. Hal yang sama berlaku untuk HarnessRouter yang di-host sendiri untuk menempatkan Codex dan Claude Code di balik satu API. Service ini sengaja mengikat ke loopback dan baru dapat diakses setelah proxy melakukan TLS termination di depannya. Karena itu, ubah login default-nya sebelum mengarahkan subdomain ke service tersebut. Namun, tidak semua container perlu memiliki hostname publik. Tool yang hanya digunakan administrator, seperti pemindai keamanan open-kritt yang di-host sendiri, sebaiknya tidak ditempatkan di belakang proxy. Akses UI-nya melalui SSH tunnel hanya ketika diperlukan. Beberapa service tidak menggunakan proxy karena hanya mendukung HTTP. Server relay RustDesk yang di-host sendiri adalah contoh yang paling jelas. Service ini mendengarkan beberapa port TCP dan UDP mentah serta memerlukan aturan firewall, bukan subdomain. Ada satu pengaturan proxy yang penting untuk Immich: naikkan batas ukuran upload karena video dari ponsel berukuran besar. Pada nginx, pengaturan tersebut adalah client_max_body_size 50000M; di dalam server block. Nilai default 1 MB menolak upload video dengan 413 Request Entity Too Large.

Aturan yang diterapkan aplikasi: endpoint harus dapat dijangkau dan, dalam praktiknya, harus menggunakan HTTPS. Endpoint http://, atau alamat IP langsung tanpa port, menyebabkan pesan "aplikasi tidak dapat menjangkau server". Kegagalan ini dibahas sebagai jenis kegagalan khusus di bawah.

Langkah 7: Pustaka eksternal vs. upload, mengimpor pohon foto yang sudah ada

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

• Upload adalah aset yang dikelola Immich. Aplikasi atau pengunggah web menyalin file ke UPLOAD_LOCATION. Immich dapat mengganti nama, memindahkan, dan menghapusnya.
• Pustaka eksternal adalah impor hanya-baca untuk file yang sudah berada di folder pada server Anda, pohon Pictures lama, atau ekspor NAS. Immich mengindeks file tersebut di lokasi aslinya dan menampilkannya di linimasa, tetapi tidak pernah mengubah atau menghapus file asli.

Untuk mengimpor pohon yang sudah ada, mount pohon tersebut secara hanya-baca ke dalam container 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

:ro menjamin bahwa Immich tidak akan pernah dapat menyentuh file asli. Buat ulang container 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, lalu masukkan path container, /mnt/media/photos, bukan path host /srv/photos. Klik Scan. Menggunakan path host, bukan path container, adalah kesalahan nomor satu pada pustaka eksternal; pemindaian tidak menemukan apa pun dan melaporkan nol aset.

Langkah 8: Disiplin upgrade yang dituntut Immich

Bagian ini membedakan Immich yang berjalan baik dari Immich yang rusak. Immich merilis versi baru dengan cepat dan tidak melakukan backport perbaikan atau mendukung downgrade. Mengikuti tag v3 yang berubah-ubah secara membabi buta pada akhirnya akan merusak database Anda. Kebiasaan yang sama, yaitu menetapkan versi lalu membaca catatan rilis, sebaiknya diterapkan pada setiap container yang berjalan lama di server. Karena itu, agent KiroCrew self-hosted ditetapkan ke satu tag yang diketahui berfungsi baik dan tidak dibiarkan berpindah sendiri saat restart berikutnya. Disiplinnya:

1. Tetapkan versi. Pastikan IMMICH_VERSION berisi tag konkret seperti v3.0.2, bukan v3 yang selalu mengambil v3.x terbaru.
2. Baca catatan rilis setiap kali sebelum melakukan upgrade. Perubahan yang tidak kompatibel, terutama perubahan pada database atau ekstensi vector, dicantumkan di sana. Rilis v3.0 adalah contoh yang jelas: rilis tersebut menghapus pgvecto.rs sepenuhnya. Akibatnya, pengguna yang masih memakai ekstensi lama harus menyelesaikan migrasi VectorChord, yang diperkenalkan sejak v1.133, sebelum dapat melakukan upgrade.
3. Cadangkan database terlebih dahulu (Langkah 9). Selalu lakukan ini, terutama jika catatan rilis menyebutkan database.
4. Ambil juga file compose yang baru. IMMICH_VERSION hanya menetapkan image server dan ML. Image Postgres ditetapkan berdasarkan digest di dalam docker-compose.yml. Karena itu, versi yang memerlukan ekstensi database yang lebih baru akan merilis file compose baru. Unduh ulang kedua aset rilis, terapkan kembali nilai .env Anda, lalu lakukan upgrade.
5. Perbarui klien mobile pada waktu yang hampir bersamaan. Server hanya berkomunikasi dengan major version yang sesuai, sedangkan aplikasi mendukung major version saat ini dan versi sebelumnya. Jika server sudah menggunakan versi yang lebih baru daripada aplikasi, ponsel akan menampilkan Your app major version is not compatible with the server! sampai aplikasi diperbarui. Karena itu, sebaiknya perbarui aplikasi terlebih dahulu.

Perintah sebenarnya, setelah file baru tersedia:

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

Langkah 9: Cadangan, dump database DAN file asli, lalu uji

Cadangan Immich terdiri dari dua hal, dan salah satunya tidak berguna tanpa yang lain. Database menyimpan struktur album, wajah, indeks pencarian, serta pemetaan antara aset dan file. Direktori originals menyimpan foto yang sebenarnya. Jika hanya salah satunya yang dipulihkan, Anda akan mendapatkan foto tanpa organisasi atau struktur kosong yang menunjuk ke file yang hilang.

Buat dump database dengan pg_dump dari dalam container Postgres, khususnya 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

Selanjutnya, cadangkan UPLOAD_LOCATION, yaitu seluruh tree /opt/immich/library, terutama subfolder library/, upload/, dan profile/, menggunakan restic, rsync, atau borg ke mesin lain atau object storage. Cadangkan database terlebih dahulu, lalu file, agar dump tidak pernah merujuk ke foto yang belum disalin oleh cadangan file. Cadangkan external libraries secara terpisah dari sumber aslinya; Immich tidak memilikinya.

Sekarang bagian yang sering dilewati semua orang: uji pemulihan. Pemulihan harus dijalankan pada stack fresh yang server-nya belum pernah dijalankan, menggunakan image Postgres dengan ekstensi vector yang kompatibel dengan dump. Karena itu, jangan pernah menentukan tag image DB secara sembarangan. Pada scratch box dengan compose yang sama dan .env, hapus state 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 search_path oleh sed wajib dilakukan pada database VectorChord. Jika langkah ini dilewati, pemulihan berhenti di tengah proses. Setelah stack kembali berjalan dengan originals Anda di tempatnya, buka web UI. Jika foto dan album Anda tersedia, cadangan tersebut berfungsi. Jika Anda belum pernah melakukan pengujian ini, Anda tidak memiliki cadangan. Anda hanya memiliki harapan.

Mode kegagalan, dengan string yang akan Anda lihat

Container ML dihentikan karena kehabisan memori (OOM-killed). sudo docker compose logs immich-machine-learning berakhir tiba-tiba, docker compose ps menampilkan Restarting, dan kode keluarnya adalah 137. sudo dmesg | grep -i oom mengonfirmasinya: Out of memory: Killed process ... (python3). Pekerjaan pencarian dan pengenalan wajah kemudian terhenti. Penyebabnya adalah RAM yang terlalu sedikit untuk model tersebut. Solusi, sesuai urutan: tambahkan swap (Step 1); tambah RAM VPS; atau, jika benar-benar tidak memungkinkan, nonaktifkan ML melalui Administration → Settings → Machine Learning Settings dengan mematikan Smart Search dan Facial Recognition. Anda tetap memiliki backup dan album, tetapi kehilangan pencarian berdasarkan isi. Menghapus service immich-machine-learning dari file compose memberikan efek yang sama.

Postgres tidak mau start setelah upgrade. Log server berulang kali menampilkan 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 yang lebih lama, The pgvecto.rs extension is not available in this Postgres instance.. Penyebabnya adalah image database yang versi extension-nya lebih lama daripada versi tempat data Anda di-upgrade. Hal ini hampir selalu terjadi karena tag image diubah secara manual atau dump yang lebih baru dipulihkan ke image yang lebih lama. Solusinya adalah menggunakan image Postgres yang sesuai, mengambil file compose dari release yang sesuai dengan database Anda, tidak melakukan downgrade, dan hanya memulihkan data ke image yang kompatibel.

Aplikasi mobile tidak dapat menjangkau server. Layar login menampilkan connection error / Server is not reachable setelah Anda memasukkan URL. Ada tiga kemungkinan penyebab: Anda memasukkan http://, padahal proxy hanya melayani https://; Anda terhubung langsung ke backend tetapi tidak menyertakan port, sehingga aplikasi mencoba example.com (port 443), bukan example.com:2283; atau reverse proxy tidak meneruskan /api. Masukkan URL https://photos.example.com lengkap dan pastikan URL tersebut dapat dimuat terlebih dahulu melalui browser di ponsel. Jika browser dapat mengaksesnya tetapi aplikasi tidak, proxy mungkin menghapus path atau sertifikatnya self-signed sehingga aplikasi menolak sertifikat yang tidak tepercaya.

Disk kehabisan ruang saat import berlangsung. Upload mulai gagal, thumbnail menjadi kosong, dan log menampilkan ENOSPC: no space left on device atau, dari Postgres, could not extend file ... No space left on device. df -h menunjukkan bahwa volume UPLOAD_LOCATION telah terisi 100%. Karena itu, tentukan ukuran disk sebelum mengimpor library besar. Untuk memulihkan kondisi ini, pasang volume yang lebih besar, hentikan stack, pindahkan UPLOAD_LOCATION ke volume tersebut, perbarui .env, lalu start kembali. Anda juga dapat memperbesar disk yang ada jika provider Anda mengizinkannya. Postgres dapat macet jika disk penuh. Kosongkan ruang dan restart container database sebelum menyimpulkan bahwa data telah rusak.

FAQ

Berapa RAM dan ruang disk yang dibutuhkan Immich?

Persyaratan resmi Immich adalah RAM minimum 6 GB dan RAM yang direkomendasikan 8 GB. RAM 4 GB dengan swap merupakan batas praktis untuk pustaka kecil. Konfigurasikan swap dalam kedua kondisi tersebut karena container machine learning adalah bagian yang mengalami lonjakan penggunaan RAM. Untuk disk, siapkan kapasitas sebesar seluruh pustaka ditambah sekitar 10–20% untuk thumbnail dan pratinjau yang dibuat secara otomatis. Gunakan penyimpanan lokal. Jangan pernah menempatkan direktori data Postgres pada network share. Jika Anda masih menentukan layanan lain yang akan dijalankan, panduan layanan yang dapat di-self-host pada 2026 membandingkan penggunaan sumber daya Immich dengan layanan lain.

Apakah Immich dapat dijalankan tanpa GPU?

Ya. Container machine learning dapat berjalan dengan baik menggunakan CPU. GPU hanya mempercepat pengindeksan pencarian cerdas dan, dengan varian image yang sesuai, transcoding video. Dengan CPU, pengindeksan awal pustaka besar dapat memerlukan waktu berjam-jam di latar belakang. Namun, proses ini tidak menghambat backup atau penelusuran. Jika mesin Anda terlalu kecil untuk menjalankan ML, nonaktifkan Smart Search dan Facial Recognition pada pengaturan administrator. Fitur lainnya tetap dapat digunakan.

Bagaimana cara meng-upgrade Immich dengan aman?

Tetapkan IMMICH_VERSION ke tag tertentu seperti v3.0.2. Baca catatan rilis sebelum setiap upgrade dan buat backup database terlebih dahulu. Karena image Postgres ditetapkan di dalam docker-compose.yml, bukan melalui IMMICH_VERSION, unduh ulang file compose dan example.env dari rilis target Anda. Terapkan kembali nilai konfigurasi Anda, lalu jalankan docker compose pull && docker compose up -d. Jangan biarkan versi berubah tanpa pengawasan. Immich merilis perubahan yang dapat menyebabkan inkompatibilitas dan tidak mendukung downgrade.

Apa saja yang harus saya backup?

Dua hal harus dibackup bersama: pg_dump dari database immich dan seluruh direktori originals UPLOAD_LOCATION. Database menyimpan album, wajah, serta pemetaan aset ke file. Direktori tersebut menyimpan foto yang sebenarnya. Proses restore memerlukan keduanya, serta image database dengan ekstensi vector yang kompatibel. Buat dump database terlebih dahulu, kemudian salin file. Uji restore pada mesin pengujian setidaknya sekali. Backup yang belum diuji bukanlah backup.

Bagaimana cara mengimpor folder foto yang sudah ada?

Mount folder tersebut secara read-only ke dalam container immich-server sebagai volume tambahan, misalnya - /srv/photos:/mnt/media/photos:ro. Buat ulang container. Kemudian, pada Administration → External Libraries, buat library dan tambahkan path container /mnt/media/photos. Immich mengindeks file di lokasi tersebut dan tidak pernah mengubah atau menghapusnya. Kesalahan yang paling umum adalah memasukkan path host, bukan path container. Akibatnya, pemindaian tidak menemukan apa pun.