Immich Docker Compose ve HTTPS ile nasıl kurulur

Immich, kamera rulonuzu kendiliğinden yedekleyen mobil uygulamalara sahip, self-hosted bir fotoğraf ve video yönetim aracıdır. Albümler, paylaşım, zaman çizelgesi ve ayrı bir makine öğrenmesi konteynerinin sağladığı yüz tanıma ile akıllı arama sunar.

Bu rehber Immich'i, resmi belgelerde olduğu gibi Immich'in en son GitHub sürümüne eklenen dosyalarla Docker Compose kullanarak kurar. 2283 numaralı web portunu localhost'ta tutar, yönetici hesabını bir SSH tüneli üzerinden oluşturur, Immich'i Caddy ile HTTPS üzerinden yayınlar ve hem veritabanının hem de fotoğraf kütüphanesinin yedeklerini kurarsınız. Ayrıca geri yüklemeyi, güncellemeyi ve donanım hızlandırmanın nerede devreye girdiğini öğrenirsiniz.

Adım 1 — Resmi dosyaları indirin

Bir proje klasörü oluşturun ve en son sürümden docker-compose.yml ile example.env dosyalarını indirin. Resmi rehber immich-app adlı bir klasör kullanır; bu kütüphane Docker uygulamalarını /opt altında tutar:

sudo mkdir -p /opt/immich
sudo chown $USER:$USER /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
ls -la

docker-compose.yml ve .env dosyalarını görmelisiniz. Compose dosyası dört servis tanımlar: immich-server, immich-machine-learning, redis (bir Valkey imajı) ve database (VectorChord eklentili PostgreSQL).

Adım 2 — .env dosyasını yapılandırın

Önce rastgele bir veritabanı parolası belirleyin. Immich özel karakter ve boşluk içermeyen, yalnızca harf ve rakamlardan oluşan bir parola ister; bu yüzden onaltılık (hex) bir dize idealdir. Ardından dosyayı koruyun ve açın:

sed -i "s/^DB_PASSWORD=.*/DB_PASSWORD=$(openssl rand -hex 24)/" .env
chmod 600 .env
nano .env

Değişkenleri gözden geçirin. TZ satırının başındaki # işaretini kaldırın ve saat diliminizi ayarlayın. Sonuç kendi parolanız ve saat diliminizle şuna benzemelidir:

UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres
TZ=Etc/UTC
IMMICH_VERSION=v3
DB_PASSWORD=generated-by-openssl
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

• UPLOAD_LOCATION yüklemeleri, küçük resimleri, dönüştürülmüş videoları ve otomatik veritabanı dökümlerini tutar. Ayrı bir veri diskiniz varsa yeterli alanı olan o diski gösterin.
• DB_DATA_LOCATION PostgreSQL dosyalarını tutar. Onu yerel SSD depolamada tutun; ağ paylaşımları desteklenmez.
• IMMICH_VERSION=v3 en son v3 sürümünü izler. Tam bir sürüme sabitlemek için değeri sürümler sayfasındaki bir etikete ayarlayın; örneğin bu rehber yazılırken en son sürüm olan v3.3.1.

Adım 3 — 2283 numaralı portu localhost'ta tutun

Compose dosyası web portunu '2283:2283' olarak yayınlar; Docker bunu ufw'den bağımsız olarak tüm adreslerde açar. Yalnızca Caddy'nin ulaşabilmesi için portu localhost'a bağlayın:

sed -i "s/- '2283:2283'/- '127.0.0.1:2283:2283'/" docker-compose.yml
grep -n "2283" docker-compose.yml

grep çıktısı 127.0.0.1:2283:2283 göstermelidir. docker-compose.yml dosyasını daha yeni bir sürüm dosyasıyla her değiştirdiğinizde bu düzenlemeyi tekrarlayın.

Adım 4 — Immich'i başlatın

docker compose up -d
docker compose ps
curl -I http://127.0.0.1:2283

İlk başlatma birkaç imaj çeker ve birkaç dakika sürer. docker compose ps; immich_server, immich_machine_learning, immich_redis ve immich_postgres konteynerlerini çalışıyor ve kısa bir süre sonra healthy olarak listelemelidir. curl komutu HTTP 200 yanıtı döndürür. Bir sorun olursa logları docker compose logs -f immich-server ile okuyun.

Adım 5 — Yönetici hesabını SSH tüneli üzerinden oluşturun

Kaydolan ilk kullanıcı yönetici olur. Bu hesabı Immich internetten erişilebilir olmadan önce oluşturun. Kendi bilgisayarınızda bir tünel açın:

ssh -L 2283:127.0.0.1:2283 admin@203.0.113.10

Tarayıcıda http://localhost:2283 adresine gidin, Getting Started seçeneğini seçin ve güçlü bir parolayla yönetici hesabını oluşturun. Aile üyeleri veya arkadaşlar için hesapları daha sonra Administration → Users altında Create user ile ekleyin. Diskte okunabilir klasörler istiyorsanız Administration → Settings → Storage Template altında depolama şablonunu açın; varsayılan desen dosyaları önce yıla, sonra tarihe göre sıralar ve özgün dosya adını korur.

Administration → Settings → Notification Settings altında bir SMTP sunucusu ayarladığınızda Immich yeni kullanıcılara, albüm davetlerine ve paylaşılan albüm güncellemelerine e-posta gönderir; örneğin smtp.example.com sunucusu, 587 numaralı port ve STARTTLS kullanın.

Adım 6 — Immich'i Caddy ile HTTPS üzerinden yayınlayın

Henüz yapmadıysanız ufw'de web trafiğine izin verin ve /etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin:

photos.example.com {
    reverse_proxy 127.0.0.1:2283
}

Immich bir adresin kökünden sunulmalıdır; alt yollar desteklenmez. Reverse proxy belgesi büyük yüklemelere ve uzun zaman aşımlarına izin verilmesini ister. Caddy varsayılan olarak istek boyutunu sınırlamaz ve resmi Caddy örneği tam olarak bu bloğu kullanır. Bunun yerine Nginx kullanıyorsanız Immich'in ayarlarını (client_max_body_size 50000M ve 600 saniyelik zaman aşımları) Nginx reverse proxy ve Certbot rehberiyle uygulayın.

Caddy'yi yeniden yükleyin ve sonucu kontrol edin:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo systemctl reload caddy
curl -I https://photos.example.com

Geçerli bir sertifikayla HTTP 200 yanıtı almalısınız. Immich mobil uygulamasında sunucu adresi olarak https://photos.example.com girin, giriş yapın, yedekleme ekranını açın, albümleri seçin ve yedeklemeyi açın.

Yedekleme ve geri yükleme

Immich durumunu iki yerde tutar: veritabanı (kullanıcılar, albümler, kişiler, meta veriler) ve yükleme konumu (fotoğrafların ve videoların kendisi). İkisini de, ayrıca .env ve docker-compose.yml dosyalarını yedekleyin.

Otomatik veritabanı dökümleri. Immich varsayılan olarak her gün saat 02:00'de bir veritabanı dökümü yazar ve son 14 dökümü UPLOAD_LOCATION/backups içinde, burada /opt/immich/library/backups klasöründe saklar. Zamanlamayı Administration → Settings → Database Dump Settings altında değiştirin. Bu dökümler fotoğraf içermez.

Elle döküm. Her güncellemeden önce bir döküm alın:

sudo mkdir -p /opt/backups
sudo chown $USER:$USER /opt/backups
docker exec -t immich_postgres pg_dump --clean --if-exists --dbname=immich --username=postgres | gzip > /opt/backups/immich-db-$(date +%F).sql.gz
cp /opt/immich/.env /opt/immich/docker-compose.yml /opt/backups/

Kütüphane. Yükleme konumundaki library, upload ve profile klasörleri özgün içeriği tutar; Immich backups, thumbs ve encoded-video dahil yükleme konumunun tamamını yedeklemeyi önerir. Onu yalnızca değişiklikleri aktaran rsync ile başka bir sunucuya kopyalayın:

sudo rsync -aAX --delete /opt/immich/library/ backup@198.51.100.20:/backups/immich-library/

Geri yükleme. Immich web arayüzünde Administration → Maintenance → Restore database backup altında bir geri yükleme ve yeni bir kurulumun karşılama ekranında Restore from backup seçeneği sunar. Komut satırından yapmak için kütüphaneyi yükleme konumuna geri kopyalayın, ardından boş bir veritabanıyla başlayan resmi yöntemi izleyin:

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

Yedeği, onu oluşturan Immich sürümüne geri yükleyin; sürüm düşürme desteklenmez.

Immich güncelleme

Önce sürüm notlarını okuyun: geriye dönük uyumsuz değişiklikler GitHub'da duyurulur ve ana sürümlerle sınırlı tutulmaya çalışılır. Elle bir veritabanı dökümü alın, ardından konteynerleri çekip yeniden oluşturun:

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

IMMICH_VERSION değerini tam bir etikete sabitlediyseniz çekmeden önce onu .env içinde değiştirin. Aynı ara sürüm içinde bile sürüm düşürme desteklenmez. Immich, büyük bir sunucu yükseltmesinden önce mobil uygulamaları güncellemenizi önerir. Yeni bir ana sürüm çıktığında docker-compose.yml ve .env dosyalarınızı yeni sürümün dosyalarıyla karşılaştırın ve compose dosyasını değiştirirseniz 127.0.0.1 bağlamasını yeniden uygulayın.

Makine öğrenmesi ve donanım hızlandırma

immich-machine-learning konteyneri yüz tanıma ve akıllı aramayı sağlar. CPU üzerinde çalışır ve modellerini ilk kullanımda model-cache volume'una indirir. Az RAM'li bir sunucuda makine öğrenmesini yönetim ayarlarından kapatıp Immich'in geri kalanını kullanmaya devam edebilirsiniz.

Çoğu sanal sunucuda GPU yoktur; bu nedenle makine öğrenmesi ve video dönüştürme CPU üzerinde çalışır. Bu çalışır, ancak büyük kütüphanelerde daha uzun sürer. Immich, sürümdeki iki ek dosya üzerinden makine öğrenmesi (CUDA, ROCm, OpenVINO, ARM NN, RKNN) ve dönüştürme (NVENC, Quick Sync, VAAPI, RKMPP) için donanım hızlandırmayı destekler:

cd /opt/immich
wget -O hwaccel.ml.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml
wget -O hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml

NVIDIA için belgeler, hesaplama yeteneği (compute capability) 5.2 veya üzeri bir GPU, 545 veya daha yeni bir sürücü ve NVIDIA Container Toolkit gerektirir. Ardından makine öğrenmesi imaj etiketine -cuda sonekini ekler ve docker-compose.yml içindeki extends bölümünün yorumunu kaldırırsınız. Desteklenen NVIDIA GPU'lu bir sunucu için GPU sunucuları sayfasına bakın.

Sorun giderme

Konteynerler yeniden başlıyor ve loglarda start_interval geçiyor

Docker Engine'iniz 25 sürümünden eski. Güncel Docker Engine'i Docker'ın deposundan kurun; geçici çözüm olarak belgeler database bölümündeki start_interval satırını yorum satırı yapmanıza izin verir.

unknown shorthand flag: 'd' in -d

docker compose eklentisi eksik veya eski olduğu için Docker komutu anlamıyor. Compose eklentisini Docker'ın deposundan kurun ve eski docker-compose programını kullanmayın.

Büyük videoların yüklenmesi alan adı üzerinden başarısız oluyor ama tünelden çalışıyor

Reverse proxy istek boyutunu sınırlıyor veya zaman aşımına uğruyor. Caddy'de varsayılan olarak böyle sınırlar yoktur; Nginx için Immich'in reverse proxy belgesindeki client_max_body_size ve zaman aşımı değerlerini ayarlayın. Alan adının önünde yüklemeleri sınırlayan bir CDN proxy'si olmadığını da kontrol edin.

Veriler taşındıktan sonra veritabanı konteyneri başlamıyor

Veritabanı klasörü bir ağ paylaşımında veya Unix sahiplik ve izinlerini desteklemeyen bir dosya sisteminde. DB_DATA_LOCATION klasörünü yerel bir ext4 veya ZFS dosya sistemine, tercihen SSD'ye geri taşıyın ve gerekirse bir dökümden geri yükleyin.

Yüz tanıma veya akıllı arama hiç bitmiyor

docker compose logs immich-machine-learning çıktısına bakın. Bellek yetersizliği (out-of-memory) nedeniyle sonlandırılan süreçler RAM'in az olduğunu gösterir; bellek ekleyin veya makine öğrenmesini kapatın. amd64 üzerinde x86-64-v2 desteği olmayan bir CPU, v3 makine öğrenmesi imajını çalıştıramaz.

Sonraki adımlar

• Compose dosya biçimini Docker Compose temelleri rehberinde öğrenin.
• Site blokları ve sertifikalar hakkında daha fazlasını Caddy reverse proxy olarak nasıl kurulur rehberinde okuyun.
• Fotoğraflarınızın yanına Nextcloud All-in-One ile dosya eşitleme ekleyin.
• Fotoğraf kütüphaneleri için sunucuları Immich hosting sayfasında karşılaştırın.
• Harici kütüphaneler, OAuth ve daha fazlası için Immich belgelerini okuyun.