JupyterLab bir Linux sunucusuna systemd ve HTTPS ile nasıl kurulur

JupyterLab, Project Jupyter'in not defterleri, kod, terminaller ve veri dosyaları için web tabanlı çalışma ortamıdır. Bir sunucuda veri analizi ve makine öğrenmesi için kalıcı bir çalışma alanı sunar: dizüstü bilgisayarınızı kapattığınızda uzun işler çalışmaya devam eder, not defterleri verinin yanında ve bir GPU sunucusunda GPU'nun yanında durur.

Bu rehber JupyterLab'i ayrı bir jupyter kullanıcısına ait bir Python sanal ortamına pip ile kurar, özetlenmiş (hash) bir parola ayarlar ve sunucuyu yalnızca 127.0.0.1 üzerinde dinleyen bir systemd servisi olarak çalıştırır. Ardından ona bir SSH tüneli üzerinden erişir veya Caddy ile HTTPS üzerinden yayınlarsınız. GPU çerçeveleri, eklentiler, ek çekirdekler (kernel), yedekleme ve güncellemeler bunu izler. JupyterLab tek kullanıcılı bir sunucudur; rehber sonunda ekipler için The Littlest JupyterHub'a yönlendirir.

Adım 1 — Ayrı bir kullanıcı ve sanal ortam oluşturun

sudo yetkisi olmayan ayrı bir kullanıcı, bir not defterinin veya yerleşik terminalin sunucuda yapabileceklerini sınırlar. Python araçlarını kurun, kullanıcıyı oluşturun ve sanal ortamı o kullanıcı olarak hazırlayın:

sudo apt update
sudo apt install python3 python3-venv
sudo useradd --create-home --shell /bin/bash jupyter
sudo -u jupyter -H python3 -m venv /home/jupyter/venv
sudo -u jupyter -H /home/jupyter/venv/bin/pip install --upgrade pip
sudo -u jupyter -H /home/jupyter/venv/bin/pip install jupyterlab
sudo -u jupyter -H mkdir -p /home/jupyter/notebooks
sudo -u jupyter -H /home/jupyter/venv/bin/jupyter lab --version

Son komut kurulan sürümü yazar, örneğin 4.6.4. Sanal ortama kurmak JupyterLab'i ve kütüphanelerinizi Ubuntu ile Debian'ın apt ile yönettiği sistem Python'undan ayrı tutar. jupyter kullanıcısını asla sudo veya docker gruplarına eklemeyin.

Adım 2 — Bir parola belirleyin

Jupyter Server varsayılan olarak belirteç (token) ile kimlik doğrulama kullanır. Uzun süre çalışan bir sunucu için parola daha pratiktir; parola ayarlandığında belirteç doğrulaması varsayılan olarak açılmaz. Resmi komutu jupyter kullanıcısı olarak çalıştırın ve uzun bir parolayı iki kez girin:

sudo -u jupyter -H /home/jupyter/venv/bin/jupyter server password

Komut /home/jupyter/.jupyter/jupyter_server_config.json dosyasına parolanın yalnızca özetini kaydeder. Parolayı daha sonra değiştirmek, sunucu yeniden başlatıldıktan sonra mevcut oturumları geçersiz kılar.

Adım 3 — Sunucuyu yapılandırın

Dinleme adresi, port ve not defteri klasörüyle /home/jupyter/.jupyter/jupyter_server_config.py dosyasını oluşturun:

sudo -u jupyter -H tee /home/jupyter/.jupyter/jupyter_server_config.py <<'EOF'
c.ServerApp.ip = "127.0.0.1"
c.ServerApp.port = 8888
c.ServerApp.open_browser = False
c.ServerApp.root_dir = "/home/jupyter/notebooks"
c.ServerApp.local_hostnames = ["localhost", "jupyter.example.com"]
c.ServerApp.trust_xheaders = True
EOF

Ayarların görevi:

• ip = "127.0.0.1" sunucuyu tüm genel arayüzlerden uzak tutar; varsayılan değer de localhost olsa da bunu açıkça yazmak sizi sonraki bir düzenlemeye karşı korur.
• root_dir, JupyterLab'in dosya tarayıcısında gösterdiği ve yeni not defterlerini kaydettiği klasördür.
• Jupyter varsayılan olarak Host başlığı yerel makineyi göstermeyen istekleri engeller (allow_remote_access değeri False); bu DNS rebinding saldırılarına karşı korur. local_hostnames, Caddy alan adınızı kabul edilen adlara ekler; jupyter.example.com değerini kendi alan adınızla değiştirin veya yalnızca SSH tüneli kullanıyorsanız satırı silin.
• trust_xheaders, Jupyter'in istemci adresini ve şemayı Caddy'nin eklediği X-Forwarded-* başlıklarından okumasını sağlar.

Adım 4 — JupyterLab'i bir systemd servisi olarak çalıştırın

sudo tee /etc/systemd/system/jupyterlab.service <<'EOF'
[Unit]
Description=JupyterLab
After=network.target

[Service]
Type=simple
User=jupyter
Group=jupyter
WorkingDirectory=/home/jupyter/notebooks
ExecStart=/home/jupyter/venv/bin/jupyter lab
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now jupyterlab

Servisin çalıştığını ve yalnızca loopback üzerinde dinlediğini kontrol edin:

systemctl status jupyterlab --no-pager
ss -tln | grep 8888
curl -I http://127.0.0.1:8888/lab

ss çıktısında 127.0.0.1:8888 görünmeli, curl ise giriş sayfasına bir 302 yönlendirmesi döndürmelidir. Loglara journalctl -u jupyterlab -f ile ulaşabilirsiniz.

Adım 5 — JupyterLab'e bağlanın

Seçenek A: SSH tüneli

Tünel alan adı, sertifika veya açık port gerektirmez ve en gizli seçenektir. Kendi bilgisayarınızda şunu çalıştırın:

ssh -L 8888:127.0.0.1:8888 youruser@203.0.113.10

Oturumu açık tutun, tarayıcıda http://localhost:8888 adresine gidin ve Adım 2'deki parolayla giriş yapın.

Seçenek B: Caddy ile HTTPS

/etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin, Caddy'yi yeniden yükleyin ve ufw'yi SSH ile web trafiğiyle sınırlı tutun:

jupyter.example.com {
    reverse_proxy 127.0.0.1:8888
}

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

https://jupyter.example.com adresini açın. Çekirdekler tarayıcıyla WebSocket üzerinden konuşur; Caddy bunları kendiliğinden ve okuma zaman aşımı olmadan aktarır, böylece uzun süren hücreler bağlantılarını korur. Nginx kullanıyorsanız Nginx ve Certbot rehberini izleyin ve Upgrade ile Connection başlıklarını iletin; Traefik de çalışır. Çalıştığınız adresleri biliyorsanız siteyi Caddy'de bir remote_ip eşleştiricisiyle bu adreslere sınırlayın.

Adım 6 — NVIDIA GPU kullanın (isteğe bağlı)

Bir GPU sunucusunda önce NVIDIA sürücüsünü kurun ve nvidia-smi ile doğrulayın. Ardından çerçevenizin CUDA derlemesini JupyterLab sanal ortamına kurun. PyTorch için PyTorch kurulum seçicisini açın, Linux, Pip, Python ve önerdiği CUDA sürümünü seçin ve gösterdiği pip install komutunu jupyter kullanıcısı olarak /home/jupyter/venv/bin/pip ile çalıştırın. Sonucu kontrol edin:

nvidia-smi
sudo -u jupyter -H /home/jupyter/venv/bin/python -c "import torch; print(torch.cuda.is_available())"

PyTorch GPU'yu kullanabiliyorsa ikinci komut True yazar. Yeni paketler kurduktan sonra çalışan çekirdekleri yeniden başlatın.

Adım 7 — Eklentiler ve ek çekirdekler ekleyin

JupyterLab eklentilerinin çoğu önceden derlenmiş Python paketleridir: onları pip ile aynı sanal ortama kurun, servisi yeniden başlatın ve etkin olanları listeleyin. Örnek, projenin Git eklentisini kurar; bu eklenti sunucuda git de ister (sudo apt install git):

sudo -u jupyter -H /home/jupyter/venv/bin/pip install jupyterlab-git
sudo systemctl restart jupyterlab
sudo -u jupyter -H /home/jupyter/venv/bin/jupyter labextension list

JupyterLab belgeleri, bir eklenti kurmanın onun sunucuda, çekirdekte ve tarayıcıda rastgele kod çalıştırmasına izin verdiği konusunda uyarır; yalnızca güvendiğiniz eklentileri kurun. JupyterLab 4'ten beri yerleşik Extension Manager eklentileri PyPI'dan kurar. Tarayıcıdan yeni kurulumlara izin vermeden kurulu eklentileri göstermek için servisin ExecStart satırını /home/jupyter/venv/bin/jupyter lab --LabApp.extension_manager=readonly olarak değiştirin, ardından sudo systemctl daemon-reload çalıştırıp servisi yeniden başlatın.

Bir projeye kendi kütüphanelerini vermek için ikinci bir sanal ortam oluşturun ve IPython belgelerindeki komutla onu bir çekirdek olarak kaydedin:

sudo -u jupyter -H python3 -m venv /home/jupyter/envs/project
sudo -u jupyter -H /home/jupyter/envs/project/bin/pip install ipykernel
sudo -u jupyter -H /home/jupyter/envs/project/bin/python -m ipykernel install --user --name project --display-name "Python (project)"

Yeni çekirdek, tarayıcı yenilendikten sonra JupyterLab başlatıcısında görünür.

Yedekleme ve geri yükleme

Çalışmalarınız /home/jupyter/notebooks içinde; ayarlar, parola özeti ve çalışma alanı düzenleri ise /home/jupyter/.jupyter içinde durur. Ortamı kopyalamak yerine yeniden kurabilmek için paket listesini de kaydedin:

sudo mkdir -p /opt/backups
sudo -u jupyter -H sh -c '/home/jupyter/venv/bin/pip freeze > /home/jupyter/requirements.txt'
sudo tar czf /opt/backups/jupyter-$(date +%F).tar.gz -C /home/jupyter notebooks .jupyter requirements.txt

Yeni bir sunucuya geri yüklemek için kullanıcıyı ve ortamı oluşturmak üzere Adım 1'i tekrarlayın, arşivi açın ve paketleri yeniden kurun, ardından Adım 4'teki servisi oluşturun:

sudo tar xzf /opt/backups/jupyter-2026-10-09.tar.gz -C /home/jupyter
sudo chown -R jupyter:jupyter /home/jupyter
sudo -u jupyter -H /home/jupyter/venv/bin/pip install -r /home/jupyter/requirements.txt

Ek çekirdekler oluşturduysanız arşive .local/share/jupyter dizinini de ekleyin. Büyük veri kümeleri ayrı yedeklere ait olabilir; her durumda yedekleri sunucunun dışına kopyalayın.

JupyterLab güncelleme

Yeni sürüm için JupyterLab değişiklik günlüğünü okuyun, yedek alın, ardından sanal ortam içinde yükseltip servisi yeniden başlatın:

sudo -u jupyter -H /home/jupyter/venv/bin/pip install --upgrade jupyterlab
sudo systemctl restart jupyterlab
sudo -u jupyter -H /home/jupyter/venv/bin/jupyter lab --version

Eklentileri de aynı şekilde yükseltin. Python sürümünü değiştiren büyük bir işletim sistemi yükseltmesinden sonra sanal ortam çalışmaz hale gelir: /home/jupyter/venv dizinini silin, Adım 1'deki gibi yeniden oluşturun ve pip install -r /home/jupyter/requirements.txt ile paketleri yeniden kurun.

Bir ekip JupyterHub'a ihtiyaç duyduğunda

JupyterLab tek bir kullanıcıyı doğrular ve her şeyi tek bir Linux hesabı olarak çalıştırır. Birkaç kişinin aynı sunucuda kendi girişine, dosyalarına ve kaynak sınırlarına ihtiyacı varsa JupyterHub kullanın. Jupyter projesinin The Littlest JupyterHub (TLJH) dağıtımı bu durum için resmi seçenektir. Belgelerine göre amd64 veya arm64 üzerinde güncel uzun süreli destekli Debian ve Ubuntu sürümlerini desteklemeyi hedefler, en az 1 GB RAM ve root erişimi ister, kişisel bilgisayara kurulmamalıdır ve bir Docker konteyneri içinde desteklenmez. TLJH'yi bu rehberdeki kurulumun yanına değil, kendi rehberini izleyerek yeni bir sunucuya kurun.

Sorun giderme

Caddy arkasında Blocking request with non-local 'Host'

Jupyter alan adınızı yerel olmayan bir ana makine adı olarak reddediyor. Alan adını tarayıcıya yazdığınız biçimiyle birebir jupyter_server_config.py içindeki c.ServerApp.local_hostnames listesine ekleyin ve sudo systemctl restart jupyterlab çalıştırın.

Parolayı değiştirdikten sonra Invalid credentials

jupyter server password komutundan sonra servisi yeniden başlatın ve komutu sudo -u jupyter -H ile jupyter kullanıcısı olarak çalıştırdığınızdan emin olun; aksi halde özet başka bir kullanıcının ev dizinine yazılmıştır.

Çekirdek ölüyor veya sürekli yeniden başlıyor

Genellikle sunucunun belleği bitmiş ve çekirdek süreci sonlandırılmıştır. sudo dmesg | grep -i -E 'killed process|out of memory' ve journalctl -u jupyterlab ile kontrol edin, ardından bir seferde daha az veri yükleyin veya daha fazla RAM'i olan bir sunucuya geçin.

Connection lost veya çekirdek durumu Connecting olarak kalıyor

WebSocket bağlantısı başarısız oluyor. Caddy bunu kendiliğinden halleder; Nginx kullanıyorsanız Upgrade ve Connection başlıklarını ekleyin. Jupyter Server belgelerinin belirttiği gibi tarayıcının proxy otomatik algılaması da WebSocket'leri bozabilir.

torch.cuda.is_available() False döndürüyor

Ya NVIDIA sürücüsü eksik (nvidia-smi başarısız oluyor) ya da yalnızca CPU derlemesi kurulmuş. PyTorch'u seçicideki CUDA komutuyla /home/jupyter/venv içine yeniden kurun, ardından çekirdeği yeniden başlatın.

Sonraki adımlar

• Not defterlerinize yerel dil modelleri sunmak için Ollama kurulumu rehberini izleyin.
• Aynı GPU üzerinde görüntü üretmek için ComfyUI kurulumu rehberine bakın.
• Belirteç, parola ve kimlik seçenekleri için Jupyter Server güvenlik belgelerini okuyun.
• Not defterleri için sunucuları Jupyter hosting sayfasında karşılaştırın.