Jellyfin Docker ve HTTPS ile nasıl kurulur

Jellyfin ücretsiz ve açık kaynaklı bir medya sunucusudur. Filmlerinizi, dizilerinizi ve müziğinizi düzenler, kapak görsellerini ve meta verileri getirir ve her şeyi web arayüzüne, telefon, TV ve set üstü kutu uygulamalarına aktarır. Bir üretici hesabı veya ücretli paket yoktur.

Bu rehber Jellyfin'i Docker Compose ile resmi Docker imajı jellyfin/jellyfin üzerinden çalıştırır. 8096 numaralı web portunu localhost'ta tutar, kurulum sihirbazını bir SSH tüneli üzerinden tamamlar, Jellyfin'i Caddy ile HTTPS üzerinden yayınlar, medyayı rsync ile yükler ve GPU'suz bir sunucuda dönüştürmenin (transcoding) neden önemli olduğunu öğrenirsiniz. Rehber ayrıca yedeklemeyi, güncellemeyi ve alternatif olarak resmi Debian ve Ubuntu deposunu anlatır.

Adım 1 — Klasörleri oluşturun

Jellyfin bir config klasörüne, bir cache klasörüne ve medyanıza ihtiyaç duyar. Uygulamayı /opt/jellyfin içinde, medyayı ise /srv/media içinde veya oraya bağlanmış ayrı bir veri diskinde tutun:

sudo mkdir -p /opt/jellyfin/config /opt/jellyfin/cache
sudo mkdir -p /srv/media/movies /srv/media/shows /srv/media/music
sudo chown -R $USER:$USER /opt/jellyfin /srv/media
id -u
id -g

Son iki komut kullanıcı ve grup kimliklerinizi yazdırır; bunlar genellikle 1000 olur. Konteyner, Jellyfin belgelerinin önerdiği gibi root yerine bu kimliklerle çalışır; böylece bu klasörleri ek izin gerekmeden okuyup yazabilir.

Adım 2 — Compose dosyasını yazın

/opt/jellyfin/compose.yaml dosyasını oluşturun. Dosya resmi örneği izler ve internetteki bir sunucu için üç değişiklik içerir: konteyner sizin kullanıcınızla çalışır, 8096 numaralı port yalnızca localhost'ta yayınlanır ve yalnızca yerel ağlar için tasarlanan 7359/udp keşif portu çıkarılmıştır:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    user: "1000:1000"
    ports:
      - "127.0.0.1:8096:8096/tcp"
    volumes:
      - /opt/jellyfin/config:/config
      - /opt/jellyfin/cache:/cache
      - type: bind
        source: /srv/media
        target: /media
        read_only: true
    restart: unless-stopped

id başka değerler yazdırdıysa 1000:1000 değerini değiştirin. Medya klasörü salt okunur bağlanır; böylece Jellyfin dosyalarınızı asla değiştiremez veya silemez. Jellyfin'in kapak görsellerini medyanın yanına kaydetmesini veya arayüzden öğe silmesini istiyorsanız read_only: true satırını kaldırın.

latest etiketi ana sürüm değişiklikleri dahil en yeni kararlı sürümü izler. Daha fazla denetim için bir ana sürüm veya ana.ara sürüm etiketine sabitleyin; konteyner belgeleri etiket düzenini açıklar, Docker Hub ise güncel etiketleri listeler.

Adım 3 — Jellyfin'i başlatın

cd /opt/jellyfin
docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8096

docker compose ps konteyneri çalışıyor ve bir dakika sonra healthy olarak göstermelidir. curl komutu bir bağlantı hatası yerine HTTP yanıt başlıklarını yazdırmalıdır. Aksi hâlde logu docker compose logs -f jellyfin ile okuyun.

Adım 4 — Kurulum sihirbazını SSH tüneli üzerinden tamamlayın

Sihirbaz bitene kadar Jellyfin'e ulaşan herkes yönetici hesabını oluşturabilir. Bu işi Caddy sunucuyu yayınlamadan önce bir tünel üzerinden yapın. Kendi bilgisayarınızda şunu çalıştırın:

ssh -L 8096:127.0.0.1:8096 admin@203.0.113.10

http://localhost:8096 adresini açın ve sihirbazı izleyin:

1. Bu istemci için dil seçin.
2. Güçlü bir parolayla yönetici hesabını oluşturun.
3. Medya kütüphanelerini ekleyin: bir içerik türü, görünen ad ve klasör seçin; örneğin filmler için /media/movies, diziler için /media/shows. Bu adımı atlayıp kütüphaneleri sonra da ekleyebilirsiniz.
4. Tercih edilen meta veri dilini ve bölgeyi ayarlayın.
5. Ağ ayarları: Allow remote access to this server seçeneğini açık bırakın, otomatik port eşlemeyi kapalı tutun. Bu özellik bir veri merkezi sunucusunda olmayan ve gerekmeyen UPnP'ye dayanır.

Adım 5 — Jellyfin'i Caddy ile HTTPS üzerinden yayınlayın

Web portlarını açın ve /etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin. Bu, Jellyfin'in Caddy belgesindeki temel örnektir:

media.example.com {
    reverse_proxy 127.0.0.1:8096
}

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

443 numaralı porta hem TCP hem UDP için izin vermek istemcilerin HTTP/3 kullanmasını sağlar. Geçerli bir sertifikayla HTTP yanıtı almalısınız.

Jellyfin X-Forwarded-For başlığına yalnızca tanıdığı proxy'lerden güvenir; aksi hâlde her istemci proxy'nin adresiyle görünür. Port Docker tarafından yayınlandığı için Caddy'den gelen istekler konteynere Compose ağının ağ geçidi (gateway) adresinden ulaşır. Bu adresi bulun:

docker network inspect jellyfin_default | grep Gateway

Bu adresi, örneğin 172.18.0.1, Dashboard → Networking → Known proxies altına ekleyin, kaydedin ve konteyneri docker compose restart ile yeniden başlatın. İstemciler artık Jellyfin uygulamalarında https://media.example.com adresiyle bağlanır.

Adım 6 — Medyanızı yükleyin

Medyayı bilgisayarınızdan SSH üzerinden, yarıda kalan aktarımları sürdüren ve yalnızca değişen dosyaları gönderen rsync ile kopyalayın:

rsync -avP ~/Videos/Movies/ admin@203.0.113.10:/srv/media/movies/

SSH anahtarlarını destekleyen grafik SFTP istemcileri de çalışır. Jellyfin, klasörler ve dosyalar belgelerindeki adlandırma düzenini izlediğinde (örneğin her film için adı ve yılı içeren bir klasör) içerikleri en güvenilir biçimde tanır. Yüklemeden sonra Dashboard → Libraries altında bir tarama başlatın veya zamanlanmış taramayı bekleyin.

Dönüştürme ve donanım hızlandırma

Jellyfin bir dosyayı dört yolla sunabilir. Direct Play dosyayı değiştirmeden gönderir ve sunucuya neredeyse hiç yük bindirmez. Remux yalnızca kapsayıcı biçimini değiştirir, Direct Stream yalnızca sesi dönüştürür, Transcode ise videoyu yeniden kodlar ve açık ara en ağır yöntemdir. Panel, etkin her akışın hangi yöntemi kullandığını gösterir.

Çoğu sanal sunucuda GPU yoktur; bu nedenle tüm video dönüştürmeleri CPU üzerinde çalışır. Jellyfin'in donanım rehberi HEVC, VP9 ve AV1 dönüştürmenin modern CPU'larda bile çok zorlu olduğu ve HDR ton eşlemenin her zaman bir GPU gerektirdiği konusunda uyarır. Böyle bir sunucuda:

• çoğu oturumun doğrudan oynatma kullanması için medyayı oynatıcılarınızın desteklediği biçimlerde saklayın;
• pahalı oturumları kullanıcı başına sınırlayın: Dashboard → Users altında bir kullanıcıyı açın ve profilin Media Playback bölümünde Allow audio/video playback that requires transcoding seçeneğini kaldırın;
• bir akış çalışırken CPU'yu docker stats jellyfin ile izleyin.

Donanım hızlandırma, dönüştürmeyi desteklenen bir GPU'ya taşır. Jellyfin NVIDIA NVENC, Intel Quick Sync, VAAPI, AMD AMF ve Rockchip RKMPP'yi destekler; resmi imaj Jellyfin'in FFmpeg derlemesiyle birlikte gelir. Desteklenen GPU'lu bir sunucuya ihtiyacınız vardır ve cihazı, Jellyfin'in donanım hızlandırma belgesinde anlatıldığı gibi konteynere aktarmanız gerekir. Desteklenen NVIDIA GPU'lu donanım için GPU sunucuları sayfasına bakın.

Yedekleme ve geri yükleme

Resmi imajda config klasörü hem Jellyfin'in verilerini (veritabanı, kullanıcılar, izleme geçmişi, meta veriler) hem de yapılandırmasını tutar. Cache klasörü yeniden oluşturulabilir ve yedek gerektirmez. Medyanızı ayrıca yedekleyin; genellikle çok daha büyüktür ve nadiren değişir.

Yerleşik yedekler. 10.11'den beri Dashboard → Backups → Create Backup veritabanını ve isteğe bağlı olarak meta verileri, altyazıları ve trickplay görsellerini içeren bir zip arşivi yazar. Bunun için en az 5 GB boş alan bırakın. Arşivler Jellyfin veri klasörünün backups klasörüne, bu kurulumda /opt/jellyfin/config içine yazılır; aynı sekme bir geri yükleme düğmesi de sunar.

Tam kopya. Veritabanı kullanımda olmasın diye konteyneri durdurun, config klasörünü arşivleyin ve konteyneri yeniden başlatın:

sudo mkdir -p /opt/backups
cd /opt/jellyfin
docker compose stop
sudo tar czf /opt/backups/jellyfin-config-$(date +%F).tar.gz -C /opt/jellyfin config
docker compose start

Arşivi ve gerekirse medyanızı rsync ile başka bir makineye kopyalayın. Geri yüklemek için Jellyfin'i durdurun, mevcut klasörü kenara taşıyın ve yedeği açın. Yedeği oluşturan Jellyfin sürümünü kullanın:

cd /opt/jellyfin
docker compose down
sudo mv config config.old
sudo tar xzf /opt/backups/jellyfin-config-2026-10-09.tar.gz -C /opt/jellyfin
docker compose up -d

Jellyfin güncelleme

Güncellemeden önce GitHub'daki sürüm notlarını okuyun. Ana sürümler, geri yükleme yapmadan geri alınamayan veritabanı geçişleri içerebilir; notlar desteklenen yükseltme yollarını ve önceden kaldırılması gereken eklentileri listeler. Tam bir yedek alın, ardından yeni imajı çekin:

cd /opt/jellyfin
docker compose pull
docker compose up -d
docker image prune

Bir etikete sabitlediyseniz önce onu compose.yaml içinde değiştirin. Docker'ın kendisini apt ile güncel tutun.

Alternatif — resmi depodan kurulum

Jellyfin, Debian ve Ubuntu için de (Debian 12 ve 13 ile Ubuntu 24.04 ve 26.04 dahil) amd64, arm64 ve armhf üzerinde paketler yayınlar. Resmi kurulum betiği sisteminizi kontrol eder, /var/lib ve /tmp içinde en az 2 GiB boş alan ister, Jellyfin'in imza anahtarını /etc/apt/keyrings/jellyfin.gpg konumuna ekler, depoyu /etc/apt/sources.list.d/jellyfin.sources dosyasına yazar ve sunucuyu, web istemcisini ve Jellyfin'in FFmpeg'ini getiren jellyfin paketini kurar. Belgelerde gösterildiği gibi çalıştırmadan önce doğrulayın ve okuyun:

curl -s https://repo.jellyfin.org/install-debuntu.sh -O
curl -s https://repo.jellyfin.org/install-debuntu.sh.sha256sum -O
sha256sum -c install-debuntu.sh.sha256sum
less install-debuntu.sh
sudo bash install-debuntu.sh

sha256sum mutlaka install-debuntu.sh: OK yazmalıdır. Yerel servis 8096 numaralı portta tüm adreslerde dinler; porta izin vermediğiniz sürece ufw onu engeller ve yukarıdaki Caddy bloğu değişmeden çalışır. Veriler /var/lib/jellyfin, yapılandırma ise /etc/jellyfin içinde durur; ikisini de servis durmuşken (sudo systemctl stop jellyfin) yedekleyin. Güncellemeler sudo apt update && sudo apt upgrade ile gelir.

Sorun giderme

Kütüphaneler taramadan sonra boş kalıyor

Jellyfin medyayı konteynerin içinde /srv/media altında değil, /media altında görür. docker exec jellyfin ls /media/movies ile kontrol edin. Klasör boşsa veya erişim reddediliyorsa compose.yaml içindeki bind mount yolunu ya da dosya izinlerini sudo chown -R 1000:1000 /srv/media ile düzeltin.

Oynatma takılıyor ve CPU yüzde 100'de

Akış dönüştürülüyor. Oynatma yöntemini panelde kontrol edin. Dosyanın codec'lerini destekleyen bir istemci kullanın, istemcide akış kalitesini düşürün veya yukarıda anlatıldığı gibi o kullanıcı için dönüştürmeyi kapatın.

Tüm istemciler aynı IP adresiyle görünüyor

Caddy'nin adresi Known proxies listesinde değil; bu yüzden Jellyfin iletilen başlıkları yok sayıyor. Adım 5'teki ağ geçidi adresini ekleyin ve konteyneri yeniden başlatın.

Başlangıçta /config için Permission denied hataları

Klasörler user: satırındakinden farklı bir kullanıcıya ait. Compose dosyanızdaki kimliklerle sudo chown -R 1000:1000 /opt/jellyfin/config /opt/jellyfin/cache çalıştırın, ardından docker compose up -d komutunu verin.

Config klasörünü taşıdıktan veya geri yükledikten sonra sunucu başlamıyor

Son sürümler, daha önce kurulmuş bir sunucunun veritabanı eksik veya boşsa onu başlatmayı reddeder. /config bağlantısının yeni ve boş bir klasörü değil, geri yüklenen verilerinizi içeren klasörü gösterdiğinden emin olun.

Sonraki adımlar

• Telefonunuzdaki fotoğrafları aynı sunucuya Immich ile yedekleyin.
• Site blokları ve sertifikalar hakkında daha fazlasını Caddy reverse proxy olarak nasıl kurulur rehberinde öğrenin.
• Compose dosya biçimini Docker Compose temelleri rehberinde anlayın.
• Medya akışı için sunucuları Jellyfin hosting sayfasında karşılaştırın.
• İstemciler, eklentiler ve adlandırma için Jellyfin belgelerini okuyun.