VPS üzerinde Jellyfin kurulumu ve kullanımı

Ne inşa ediliyor

Bir VPS üzerinde Jellyfin medya sunucusu: tek bir container, üç volume ve filmleriniz ile dizileriniz için blok depolama diskine sahip, her türlü tarayıcıdan veya Jellyfin uygulamasından erişilebilen bir yapı. Kurulum, on beş satırlık bir compose dosyasıdır. Sonrasında karşılaşılan hatalar iki nedenden kaynaklanır: container'ın okuyamadığı dosya izinleri ve GPU bulunmayan bir VPS'den video transcoding yapmasının istenmesi. Bu kılavuz, sorunların büyük çoğunluğu bu iki noktada toplandığı için vaktinin çoğunu bunlara ayırmaktadır.

Jellyfin ücretsiz ve tamamen açık kaynaklıdır; hesap gerektirmez, ücretli özellik barındırmaz ve telemetri içermez. Bu özellikleri sayesinde 2026 yılında self-host edilmesi gerekenler listelerinde yer alır. Sahip olduğunuz medyayı oynatır. İçerik sağlamaz; bu kılavuz içerik edinme üzerine değildir.

Herhangi bir şey kiralamadan önce transcoding gerçekliği

Satın alacağınız ürünü değiştireceği için önce bunu okuyun. Bir medya sunucusu, oynat düğmesine bastığınızda iki işlemden birini yapar. Direct play, dosyayı olduğu gibi aktarır: VPS, diskten baytları okur ve ağ üzerinden gönderir; bu işlem neredeyse hiç CPU tüketmez. Transcoding, videoyu anlık olarak yeniden kodlar — yeni çözünürlük, yeni codec veya gömülü altyazılar — ve bu işlem tamamen CPU yüküdür.

Tipik bir VPS'de GPU bulunmaz. Bu nedenle her transcoding işlemi libx264/libx265 ile CPU üzerinde çalışır ve yazılımsal kodlama maliyetlidir. Tek bir 1080p H.264 transcoding işlemi birkaç paylaşımlı vCPU'yu doyuma ulaştırabilir; 4K veya HEVC transcoding işlemi genellikle gerçek zamanlı hıza yetişemez, bu nedenle oynatma durur ve sürekli tamponlama (buffering) gerçekleşir. Donanımsal transcoding — Intel iGPU veya Nvidia kartı olan bir ev bilgisayarında bu işlemi ucuz kılan özellik — sağlayıcınız GPU örnekleri kiralamadığı sürece sizin için mevcut değildir.

Bu nedenle bir VPS üzerindeki tüm strateji şudur: transcoding işleminden kaçının. Kitaplığınızı istemcilerinizin yerel olarak oynatabileceği codec bileşenlerinde tutun — H.264 video, AAC veya AC3 ses, MP4 veya MKV kapsayıcısı içinde — ve direct-play yapabilen istemci uygulamaları seçin: Android TV, iOS ve Roku için yerel Jellyfin uygulamaları, ayrıca Infuse, Kodi ve masaüstü Jellyfin Media Player. Bunu yaparsanız VPS hiçbir zaman ffmpeg kullanmaz ve mütevazı bir 2 vCPU makinesi aynı anda birkaç kişiye yayın yapabilir. Transcoding planlarsanız çok daha büyük ve pahalı bir makineye ihtiyacınız olur ve bu durumda bile 4K risklidir.

Bant genişliği hesaplamasını de yapın, çünkü diğer sürpriz budur. Direct play, dosyayı kendi bitrate değeriyle gönderir. Sıkıştırılmış bir 1080p dosyası 8-12 Mbps hızında çalışır; bir 1080p Blu-ray remux 20-30 Mbps; 4K HDR 40-80 Mbps hızındadır. 10 Mbps hızındaki dosyaları doğrudan oynatan üç kişi, VPS'nizden 30 Mbps sürekli yükleme (upload) gerektirir. Planınızdaki iki değeri kontrol edin: port hızı (30 Mbps upstream gönderebilir mi?) ve aylık veri transfer kotası. İki saatlik 10 Mbps bir film yaklaşık 9 GB veri tüketir; bu durumda aylık 1 TB kotalı bir paket, ayda yüzden biraz fazla film — günde üç veya dört film — demektir; 4K izleyen bir hane halkı, dört ila sekiz kat daha yüksek bitrate ile kotayı çok daha hızlı tüketir.

Ön Koşullar

• root veya sudo yetkisine sahip, Docker ve Compose eklentisi yüklü, yeni bir Ubuntu 24.04 KVM VPS.
• Medya dosyaları için kütüphane boyutunuza uygun bir block-storage hacmi (aşağıdaki boyutlandırma kısmına bakınız). VPS ile birlikte gelen küçük root diski medya dosyaları için uygun değildir.
• Genel HTTPS erişimi isteniyorsa bir alan adı veya tüm yapının özel kalması isteniyorsa aynı VPS üzerinde WireGuard VPN.
• Yasal olarak yayınlama hakkına sahip olduğunuz medya içerikleri — kendi kopyalarınız, kendi kayıtlarınız veya sahip olduğunuz dosyalar.

Önce blok depolama birimini bağlayın

Hacmi sağlayıcınızın panelinden ekleyin, ardından cihazı bulun ve bağlayın. Cihaz adını lsblk üzerinden öğrenin; bu cihaz /dev/sdb veya /dev/vdb gibi bir isim olacaktır, asla root diski değildir.

lsblk
sudo mkfs.ext4 /dev/sdb          # ONLY on a new, empty volume — this ERASES it
sudo mkdir -p /mnt/media
sudo blkid /dev/sdb              # copy the UUID shown for this device

Cihazı /dev/sdb yerine UUID kullanarak bağlayın; çünkü yeniden başlatma sırasında cihaz harfleri değişebilir ve yanlış diski biçimlendirme veya bağlama riski oluşur. /etc/fstab dosyasına bir satır ekleyin:

UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  /mnt/media  ext4  defaults,nofail  0  2

sudo mount -a
df -h /mnt/media

nofail önemlidir: bu parametre olmadan, blok hacmi ayrılırsa sistem açılışta hata verir ve acil durum kabuğuna (emergency shell) düşer. Buradaki en büyük hata, içinde veri bulunan bir hacim üzerinde mkfs.ext4 komutunu çalıştırmaktır; bu işlem verileri siler. Sadece yeni hacimleri biçimlendirin; eğer disk üzerinde halihazırda bir kütüphane varsa, doğrudan fstab satırına geçin.

Medya dosyalarını Jellyfin formatına uygun düzenleyin

Jellyfin, meta verileri klasör ve dosya isimlerine göre eşleştirir. Yanlış düzenleme yapılması durumunda filmler afişsiz ve isimsiz olarak görünür veya bölümler yanlış serilerle eşleşir. Üç temel kural bulunmaktadır: her film, eşleşen bir dosya adına sahip olan kendi Name (Year) klasöründe yer almalıdır; sezon klasörleri S01 yerine Season 01 olarak adlandırılmalıdır; bölüm dosyaları S01E01 formatını kullanmalıdır; ve özel bölümler Season 00 klasörüne konulmalıdır.

/mnt/media
├── Movies
│   ├── Blade Runner (1982)
│   │   └── Blade Runner (1982).mkv
│   └── Arrival (2016)
│       └── Arrival (2016).mkv
└── Shows
    └── Severance (2022)
        ├── Season 01
        │   ├── Severance - S01E01.mkv
        │   └── Severance - S01E02.mkv
        └── Season 00
            └── Severance - The Lexington Letter.mkv

Filmlerdeki (Year) kullanımı dekorasyon amaçlı değildir; yeniden çevrimlerin ayırt edilmesini sağlayarak eşleştiricinin doğru başlığı bulmasına yardımcı olur. Movies ve Shows klasörlerini ayrı üst düzey klasörler olarak tutun; çünkü her biri belirli bir içerik türüne ait bir Jellyfin kütüphanesi oluşturur ve bunların karıştırılması meta veri sağlayıcısının hata yapmasına neden olur.

İzinler: kütüphanelerin boş görünmesinin bir numaralı nedeni

İnsanların bir akşamını boşa harcamasına neden olan yanlış inanış şudur: Resmi jellyfin/jellyfin imajı PUID/PGID ortam değişkenlerini desteklemez. Bu değişkenler LinuxServer.io imajına (lscr.io/linuxserver/jellyfin) aittir. Resmi imajda kullanıcıyı compose dosyasındaki user: anahtarı ile kontrol edersiniz; eğer bu anahtar eksikse konteyner root olarak çalışır. Hangi imaj kullanılırsa kullanılsın kural aynıdır: Konteynerin çalıştığı uid/gid, tüm medya dizinlerini okuyabilmeli ve bu dizinlerin içine girebilmelidir.

Standart bir Ubuntu sistemindeki ilk root olmayan kullanıcı olan 1000 uid/gid ile çalıştıracağız. Kendi değerlerinizi doğrulayın ve sahipliği ayarlayın:

id                                  # confirm your user is uid=1000 gid=1000
sudo chown -R 1000:1000 /mnt/media
sudo find /mnt/media -type d -exec chmod 755 {} \;
sudo find /mnt/media -type f -exec chmod 644 {} \;
mkdir -p ~/jellyfin/config ~/jellyfin/cache
sudo chown -R 1000:1000 ~/jellyfin

Dizinlerin sadece okuma değil, execute (yürütme) bitine (755 içindeki x) ihtiyacı vardır; bu bit olmadan konteyner, dizin içeriğini listeleyebilse bile klasöre giriş yapamaz. Tüm bir kütüphaneyi boş gösteren tuzak üst dizindir: Eğer konteynerin uid değeri mount edilen dizinin içine giremiyorsa, /media/Movies veya /media/Shows dizinlerine asla ulaşamaz ve loglarda Access to the path ... is denied hatası ile birlikte tüm kütüphane aniden boş görünür. Okunamayan her bir medya klasörü loglanır ve atlanır; bu nedenle root olarak kopyalanan dosya grupları kütüphanede sessizce kaybolur. Bu yüzden tek bir klasörü düzeltmek yerine, chown işlemini özyinelemeli (recursively) yaparız ve her dizin için execute bitini ayarlarız.

docker-compose dosyası

services:
  jellyfin:
    image: jellyfin/jellyfin:10
    container_name: jellyfin
    user: "1000:1000"
    restart: unless-stopped
    ports:
      - "127.0.0.1:8096:8096"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /mnt/media:/media:ro
    environment:
      - JELLYFIN_PublishedServerUrl=https://jellyfin.example.com

Satır satır inceleme: user: "1000:1000", yukarıdaki sahiplik ayarlarıyla eşleşecek şekilde dosya izinlerini belirler. /config; hesaplar, kütüphaneler, meta veriler ve izleme durumu dahil olmak üzere tüm sunucuyu barındırır; bu nedenle yazılabilir olmalıdır ve yedeklenen birim budur. /cache geçici çalışma alanıdır. Medya bağlaması (mount) bilerek :ro (salt okunur) olarak ayarlanmıştır: Jellyfin, kapak görsellerini ve meta verileri varsayılan olarak /config altına kaydeder; bu sayede kütüphaneye yazma işlemi yapmasına gerek kalmaz. Salt okunur mod, dosyaları yanlışlıkla silinmeye veya hatalı bir eklentiye karşı korur. Port, bilerek 127.0.0.1 adresine bağlanmıştır — Jellyfin'in web girişi düz HTTP kullandığından, 8096 portu halka açık internete açılmaz. JELLYFIN_PublishedServerUrl, sunucunun yerel otomatik keşif için kullandığı adrestir — bir LAN UDP yayınıdır; bu sayede internet üzerindeki istemciler bu yayını görmez ve sadece uygulamaya yazdığınız URL'yi kullanır. Bu adresi, istemcilere bildirilmesi gereken adres olarak ayarlayın; uzak cihazlarda bu URL'nin manuel olarak girilmesi gerekecektir.

Compose dizininden çalıştırın:

docker compose up -d
docker logs -f jellyfin

İlk çalıştırma: kurulum sihirbazı ve kütüphaneleriniz

Port localhost'a bağlı olduğundan, bir güvenlik duvarı açmak yerine sihirbazlara dizüstü bilgisayarınızdan bir SSH tüneli üzerinden erişin:

ssh -L 8096:127.0.0.1:8096 you@your-vps-ip

Şimdi http://localhost:8096 adresine gidin. Sihirbaz sırasıyla dil seçimini ve ardından güçlü bir şifreye sahip bir admin kullanıcısı oluşturulmasını sağlar. Bu hesap sunucunuzdur, bu nedenle geçici bir şifre kullanmayın. İlk kütüphanenizi ekleyin: içerik türü olarak Movies seçin, hedef olarak /media/Movies (host yolu değil, konteyner içindeki yol) adresini gösterin ve Shows için /media/Shows adresini kullanarak işlemi tekrarlayın. İşlemi tamamladığınızda Jellyfin tarama yapacaktır. Küçük bir kütüphane için bir veya iki dakika içinde afişlerin ve başlıkların dolması doğru sonuçtur. Kütüphaneleri daha sonra Dashboard → Libraries menüsü altından ekleyebilir veya düzenleyebilirsiniz; taramayı zorlamak için Scan All Libraries seçeneğini kullanın.

Herhangi bir transcoding işlemine ihtiyaç duyuyorsanız, Dashboard → Playback → Transcoding menüsünü açın ve transcode geçici yolunu /cache/transcodes olarak ayarlayın. Bu sayede geçici dosyalar /config alanını şişirmek yerine cache volume üzerinde depolanır. Donanım hızlandırma (hardware acceleration) ayarını None olarak bırakın; hızlandırma yapacak bir GPU bulunmamaktadır.

Uzaktan erişim: TLS reverse proxy veya VPN kullanımı

Jellyfin'e dışarıdan erişmek için iki güvenli yöntem ve kaçınılması gereken bir güvensiz yöntem bulunmaktadır. Güvensiz yöntem, 8096 portunu doğrudan internete açmaktır: giriş bilgileri açık metin olarak iletilir ve port birkaç saat içinde brute-force saldırısına maruz kalır.

Seçenek A — TLS reverse proxy. Jellyfin'i Docker uygulamaları için otomatik TLS sağlayan Traefik arkasındaki bir alt alan adına veya Certbot tarafından verilen Let's Encrypt sertifikası ile nginx arkasına yerleştirin. Jellyfin, gerçek zamanlı güncellemeler için WebSockets kullanır; bu nedenle proxy, upgrade header bilgilerini iletmelidir. Traefik bunu otomatik olarak yapar; nginx için bu bilgiler açıkça belirtilmelidir ve upgrade işleminin gerçekleşmesi için upstream tarafında HTTP/1.1 gereklidir:

location / {
    proxy_pass http://127.0.0.1:8096;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Yerel otomatik keşfin doğru URL'yi duyurması için JELLYFIN_PublishedServerUrl değerini https:// adresine ayarlayın — uzak uygulamalar onlara verdiğiniz adresi kullanır — ve giriş denemelerine karşı brute-force saldırılarını yavaşlatmak için fail2ban ekleyin. Sunucu herkese açık hale geldiğinde, kesintilerden izleyicilerden önce haberdar olmak için Uptime Kuma'yı ilgili URL'ye yönlendirin.

Seçenek B — VPN ile özel tutun. 8096 portunu hiçbir şekilde yayınlamayın; Jellyfin'e yalnızca aynı makinede sonlanan bir WireGuard tüneli üzerinden erişin. Bir ev kullanımı için bu en basit güvenli seçimdir — sertifika gerekmez, kamuya açık maruziyet yoktur ve brute-force yüzeyi oluşmaz. Konteynırı tünel adresine veya localhost'a bağlayın ve VPN üzerinden bağlanın. Tünel kurulumu için Özel bir VPS için WireGuard VPN kurulumu kısmına bakın.

Depolama boyutu ve yedeklemeler

Bütçeyi dosya sayısına göre değil, kaliteye göre belirleyin. Sıkıştırılmış 1080p filmler her biri 4-15 GB arasıdır; 1080p remux 20-40 GB; bir sezon 1080p TV dizisi 15-40 GB; 4K içeriklerin her biri 40-100 GB arasıdır. Birkaç yüz film ve bazı diziden oluşan bir kütüphane için 2-4 TB hacim gereklidir; blok hacmini bir kez fazla kapasiteyle yapılandırmak, daha sonra veri taşımaktan daha ekonomiktir.

/config tüm sunucu durumunu içerir, bu nedenle yedeklenmesi gereken tek şey budur. Snapshot alın veya durdurup tar ile paketleyin ve kopyayı cihaz dışında saklayın:

docker compose down
sudo tar czf jellyfin-config-$(date +%F).tgz -C ~/jellyfin config
docker compose up -d

/cache ve transcode klasörü geçicidir. /mnt/media üzerindeki medyayı ayrı olarak yedekleyin veya yeniden dönüştürülebilir olarak kabul edin; boyutlar nedeniyle çoğu kişi ikinci seçeneği tercih eder. Güncellemeler docker compose pull && docker compose up -d şeklindedir; yukarıdaki :10 etiketi 10.x ana sürümü içinde kalır, bu nedenle bir sonraki ana sürüme geçiş bilinçli bir etiket düzenlemesi gerektirir; bu işlemi yapmadan önce Jellyfin sürüm notlarını inceleyin, çünkü kütüphane şeması göçleri ana sürümlerde gerçekleşir.

Hata modları ve göreceğiniz metinler

Tarama sonrası kütüphane boş görünüyor. Dashboard → Logs (veya ~/jellyfin/config/log/log_*.log) üzerindeki günlük şu metni gösterir:

System.UnauthorizedAccessException: Access to the path '/media/Movies' is denied.

Konteynerin uid değeri bu yolu okuyamaz. Sebep: medya dosyalarının root veya user: değerinizden farklı bir uid tarafından sahiplenilmesi, bir dizinin execute bitinin eksik olması veya ana mount noktasının bu uid tarafından geçilemez olması. Çözüm: chown -R 1000:1000 /mnt/media, dizinler 755, dosyalar 644 ve ardından yeniden tarama yapın.

Oynatma sırasında CPU kullanımı ve tamponlama (buffering) oluşuyor. docker stats jellyfin, CPU kullanımının çekirdek sayınızın katı kadar (yaklaşık %100) olduğunu gösterir ve Dashboard → Playback oturumu Transcode olarak listelerken hız 1.0x değerinin altındadır. İstemci direct-play yapmıyor; bu nedenle VPS, gerçek zamanlı hızdan daha yavaş CPU-transcoding yapıyor ve veri kaybediyor. Sebep: desteklenmeyen bir codec veya container, altyazı yakma (burn-in) veya HDR tone-mapping. Çözüm: direct-play destekleyen bir istemciye geçin, kaynakları H.264/AAC formatında tutun, burn-in işlemine zorlayan image altyazılar (PGS/VOBSUB) yerine text altyazılar (SRT) kullanın ve 4K HDR içeriği sadece CPU kullanan bir sistemden tamamen uzak tutun.

"No compatible streams are available." Tam mesaj genellikle "This client isn't compatible with the media and the server isn't sending a compatible media format." şeklindedir. İstemci kaynağı reddetti ve fallback transcode işlemi de başlatılamadı. Sebep: hatalı bir ffmpeg komutu, okunamaz bir dosya veya kullanıcının profilinin video dönüştürmeyi engellemesi. Çözüm: Dashboard → Logs altındaki ffmpeg satırını okuyun, dosyanın oynatılıp oynatılamadığını teyit edin, transcode işlemine bağlıysanız kullanıcının oynatma izinlerini kontrol edin ve tarayıcı codec sorunlarını elemek için ikinci bir istemci deneyin.

Filmlerin afişi yok veya yanlış afiş görünüyor. Metadata eşleşmedi. Sebep: filmin kendi Name (Year) klasöründe olmaması, bir sezon klasörünün Season 01 yerine S01 olarak adlandırılması, bölümlerin S01E01 formatında olmaması veya yıl bilgisinin eksik olması. Çözüm: yukarıdaki düzene göre yeniden adlandırın, ardından Refresh metadata → Replace all işlemini yapın veya doğru TMDB/TVDB girişini sabitlemek için tek bir öğe üzerinde Identify özelliğini kullanın.

FAQ

Bir VPS, GPU olmadan video transcode edebilir mi?

Evet, ancak yalnızca CPU ile yapılır ve bu maliyetlidir. Tek bir 1080p yazılımsal transcode işlemi birkaç vCPU'yu doyuma ulaştırabilir; 4K veya HEVC genellikle gerçek zamanlı hıza yetişemez, bu nedenle oynatma sırasında tamponlama (buffering) oluşur. En iyi yöntem transcode işleminden kaçınmaktır: Kütüphanenizi H.264/AAC formatında tutun ve doğrudan oynatma (direct-play) özelliğine sahip istemci uygulamaları kullanın; böylece VPS yalnızca byte akışı sağlar. Bir GPU instance'ı yalnızca anlık transcode işlemine gerçekten ihtiyacınız varsa kiralayın.

Tarama yaptıktan sonra Jellyfin kütüphanem neden boş görünüyor?

Neredeyse her zaman izin (permission) sorunudur. Resmi jellyfin/jellyfin imajı, ayarladığınız user: (veya root) kullanıcısı olarak çalışır; eğer dosyalar bu uid tarafından okunabiliyor değilse, tarama günlükleri Access to the path ... is denied hatası verir ve dosyaları atlar. Sahipliği chown -R 1000:1000 /mnt/media ile düzeltin, dizinlere çalıştırma biti (755) verin ve yeniden tarama yapın. Ayrıca üst dizinleri de kontrol edin; eğer konteynerin uid'si /mnt/media dizinine erişemezse, kütüphane klasörlerine asla ulaşamaz ve her şey boş görünür. İkinci en yaygın neden, klasör yapısının Jellyfin'in beklediği formatla eşleşmemesidir.

Jellyfin'e uzaktan ve güvenli bir şekilde nasıl erişirim?

İki iyi seçenek mevcuttur. Giriş ve akış işlemlerinin şifrelenmesi için uygulamayı bir alt alan adında (subdomain) TLS reverse proxy arkasına yerleştirin ve fail2ban ekleyin; 8096 portunu asla doğrudan dış dünyaya açmayın, çünkü bu port şifrenizi açık metin olarak gönderir. Veya uygulamayı tamamen özel tutun ve yalnızca bir VPN üzerinden erişin; bu, bir ev ağı için en basit güvenli seçimdir. Uygulamalara doğrudan genel adresi (public address) verin; otomatik keşif (autodiscovery) yerel ağ yayınıdır, bu nedenle internet üzerinden gelen istemcilere ulaşmaz.

Bir Jellyfin VPS'i ne kadar disk ve bant genişliğine ihtiyaç duyar?

Disk ihtiyacı kaliteye bağlıdır: Sıkıştırılmış her 1080p film için 4-15 GB, her remux için 20-40 GB ve 4K için 40-100 GB planlayın; bu nedenle çoğu kütüphane için 2-4 TB bir block volume gereklidir. Bant genişliği, doğrudan oynatma (direct-play) bit hızı tarafından belirlenir; 1080p akış başına 8-12 Mbps, 4K için ise çok daha fazlası gerekir. Port hızınızın eş zamanlı izleyici sayısını karşıladığından emin olun ve aylık veri transfer sınırını takip edin. Transcode yapmayı planlıyorsanız CPU payı ekleyin; doğrudan oynatma planlıyorsanız çekirdek sayısından ziyade bant genişliğine öncelik verin.

VPS üzerinde Jellyfin çalıştırmak yasal mı?

Jellyfin'in kendisi ücretsiz ve açık kaynaklı bir yazılımdır ve çalıştırılması tamamen yasaldır. Önemli olan içeriktir: Yalnızca sahip olduğunuz veya lisanslı olduğunuz medyaları akış olarak sunun; kendi disk kopyalarınız, kayıtlarınız veya kullanım hakkına sahip olduğunuz dosyalar. Jellyfin herhangi bir medya ile birlikte gelmez ve herhangi bir medya elde etme yolu sağlamaz; o, halihazırda sahip olduğunuz bir kütüphane için oynatıcıdır.