VSCode'da Uzaktan Geliştirme: SSH ile Sunucuda Kod

Merhabalar! Bugün sizlerle, özellikle sunucu üzerinde çalışan ya da uzak bir makineye bağlanarak kod yazan herkesin yaşamış olduğu bir acıyı çözeceğiz: VSCode Remote – SSH eklentisi ile uzak bir sunucuda nasıl sorunsuz geliştirme yaparız? Kendi deneyimimden söyleyebilirim ki; bir kez alıştıktan sonra “nasıl oldu da bunu kullanmadan önce idare ettim?” diye soruyorsunuz. Ama bir de bağlantının csırdandığı, vscode-server’ın takıldığı o karanlık anlar var… Bu yazıda hem temel kurulumu hem de bu sorunların çözümlerini adım adım göstereceğim.

VSCode Remote – SSH Nedir?

VSCode Remote – SSH, Visual Studio Code’un resmi eklentisidir ve size SSH üzerinden herhangi bir uzak makineye (sunucu, VM, Raspberry Pi, konteyner — fark etmez) bağlanıp tam VS Code deneyimini yaşamayı sağlar. Yani uzak makinede dosyaları açar, düzenler, terminal çalıştırır, eklentileri yükler, hata ayıklar (debug) yaparsınız — hepsi sanki kod yereldeymiş gibi.

Bunu yaparken VS Code, arka planda uzak makineye vscode-server adında küçük bir sunucu bileşeni kurar. Bu bileşen dosya işlemlerini, terminali, debug motorunu ve dil sunucularını (LSP) uzakta çalıştırır; sizin bilgisayarınız sadece bir “arayüz” görevi görür. Senkronizasyon, dosya indirme/indirme derdi yoktur.

Neden kullanmalısınız? Birkaç senaryo:

  • Geliştirme yaptığınız proje büyük ve derleme için güçlü bir sunucu gerekiyor
  • Deployment yaptığınız ortamda kodu çalıştırıp debug etmek istiyorsunuz
  • Yerel makineniz Windows ama kodunuz Linux’ta çalışacak
  • Raspberry Pi veya gömülü cihazda proje geliştiriyorsunuz

1. Ön Hazırlık: SSH Kurulumu

Bağlanacağınız makinede bir SSH sunucusunun çalıştığından emin olmanız gerekiyor. Çoğu Linux dağıtımında zaten kuruludur; emin değilseniz:

sudo apt update && sudo apt install openssh-server -y
sudo systemctl enable --now ssh

Kendi bilgisayarınızda da bir SSH istemcisi gerekiyor. Linux ve macOS’ta bu zaten yüklüdür. Windows 10/11’de ise OpenSSH Client özelliğini ayarlardan açmanız gerekebilir (Settings > Apps > Optional Features). Ek olarak, çoğu Windows kullanıcısı tercih eder ama ben PowerShell üzerinden de gayet güzel çalışıyor.

Önce klasik SSH ile bağlanabildiğinizi doğrulayın:

ssh kullaniciadi@sunucu-ip

Eğer password girdikten sonra bağlanabiliyorsanız ilk adım tamam. Ama şifreyle her seferinde giriş yapmaktamaya gerek yok; SSH anahtarı kurmak çok daha pratik.

2. SSH Anahtarı Oluşturma (Önerilir)

SSH anahtarı, parolanızı her seferinde yazmadan güvenli bir şekilde bağlanmanızı sağlar. Eğer halihazırda bir anahtarınız yoksa şu komutla oluşturun:

ssh-keygen -t ed25519 -C "vscode-remote"

Sizden kaydedilecek dosya yolu ve parola (passphrase) isteyecek. Passphrase girmek ek güvenlik sağlar ama opsiyoneldir; boş bırakabilirsiniz.

Şimdi publicKey’i uzak sunucuya tanıtmamız gerekiyor. Linux/macOS’ta tek komutla olabilir:

ssh-copy-id kullaniciadi@sunucu-ip

Windows’ta ssh-copy-id yoksa manuel olarak da yapılabilir:

type %USERPROFILE%\.ssh\id_ed25519.pub | ssh kullaniciadi@sunucu-ip "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Bundan sonra ssh kullaniciadi@sunucu-ip yazdığınızda parola sormadan bağlanmalısınız. Kontrol edin — VSCode kurulumuna geçmeden önce bu çalışıyor olmalı.

3. VSCode Remote – SSH Eklentisinin Kurulumu

VSCode’u açın (Linux, macOS, Windows fark etmez). Sol kenardaki eklentiler (Extensions) sekmesine geçin veya Ctrl+Shift+X / Cmd+Shift+X kısayolunu kullanın. Arama çubuğuna “Remote – SSH” yazın.

Microsoft tarafından yayınlanan, mavi uzay/EVRA-yüklü bir eklenti göreceksiniz. Install‘a tıklayın.

Eğer VS Code’unuzun kendisi yoksa, code.visualstudio.com adresinden indirip kurun. Eklenti VS Code ile birlikte gelmez, elle kurmanız gerekir.

Not: “Remote Development” adında bir extension pack de var; bu paket Remote-SSH, Remote-Containers ve Remote-WSL’yi birden kurar. Eğer üçünü de kullanacaksanız paketi kurmak daha pratik.

4. İlk Bağlantı: SSH Config ve Bağlanma

Eklenti kurulduktan sonra Command Palette’yi açın (F1 ya da Ctrl+Shift+P / Cmd+Shift+P). “Remote-SSH: Open Configuration File…” komutunu aratın ve SSH config dosyanızı seçin (genelde ~/.ssh/config ya da Windows’ta C:\Users\isminiz\.ssh\config).

İçine basit bir host tanımı ekleyin:

Host benim-sunucum
    HostName 192.168.1.100
    User kullaniciadi
    IdentityFile ~/.ssh/id_ed25519

Host kısmına istediğiniz takma adı verebilirsiniz; VSCode bu ismi gösterir. HostName sunucunun IP adresi veya domain adıdır. IdentityFile ise az önce oluşturduğumuz private key dosyası.

Config dosyasını kaydettikten sonra tekrar Command Palette’yi açın ve “Remote-SSH: Connect to Host…” komutunu çalıştırın. Listede benim-sunucum görünecek. Tıklayın.

İlk bağlantıda VS Code, uzak makineye vscode-server bileşenini indirip kuracak. Bu işlem birkaç saniye ile birkaç dakika arası sürebilir (internet hızına bağlı olarak). Kurulum bittiğinde sol alttaki status bar yeşil renkte olacak ve bağlandığınız host’un adını gösterecek.

Artık File > Open Folder‘ı kullanarak uzak makinedeki herhangi bir dizini açabilirsiniz. Tüm dosya gezgini, arama, terminal — her şey uzakta çalışıyor.

5. Uzak Makinede Terminal ve Eklentiler

Bağlandınız, bir klasör açtınız. Şimdi terminal açmak için Ctrl+ (backtick) tuşuna basın. Bu terminal, uzak makinede çalışan gerçek bir bash/zsh oturumudur. Python, Node, Docker, git — ne kuruluysa hepsi burada çalışır.

Önemli bir nokta: VSCode eklentileri uzak makinede ayrı çalışır. Yani Python eklentisini hem yerelde hem uzakta ayrı ayrı kurmanız gerekir. Eklenti sekmesinde “Install in SSH: benim-sunucum” butonu görürsünüz. Eklentilerin çoğu uzakta çalışmalı — özellikle dil sunucuları (Python, C/C++, Java vs.). Tema ve icon pack’leri gibi UI eklentileri ise yerelde kalmaya devam eder.

Hızlı bir test: Python yüklü bir sunucuda bir test.py oluşturun:

print("Merhaba uzak dünya!")

Terminalden çalıştırın:

python3 test.py

Çıktı:

Merhaba uzak dünya!

Tebrikler! Artık uzakta tam bir geliştirme ortamına sahipsiniz.

6. Port Yönlendirme (Port Forwarding)

Uzak makinede çalışan bir web sunucusu (örneğin FastAPI, Flask, Node.js) yerel tarayıcınızdan test etmek istiyorsanız port yönlendirme kullanın. VSCode bunu otomatik yapar — terminalde python3 -m http.server 8000 yazdığınızda VSCode “Forwarded Port” bildirimi gösterir ve tıklayınca tarayıcınızda açar.

Manuel de eklenebilir: Command Palette > “Remote-SSH: Forward Port…” > port numarasını girin (ör. 8000). Artık localhost:8000 adresi uzaktaki port’a tünel tạo.

Seçenek olarak “Restore Forwarded Ports” ayarını aktifleştirirseniz, bir sonraki bağlantıda otomatik olarak aynı portlar açılır. Pratik bir özellik.

7. Jump Host (Ara Sunucu) ile Bağlantı

Eğer hedef sunucu dışarıdan direkt erişilemiyorsa, bir jump host (bastion) üzerinden geçmeniz gerekiyorsa SSH config’inize ProxyJump ekleyebilirsiniz:

Host jump-host
    HostName 52.10.10.10
    User ana
    IdentityFile ~/.ssh/jumpbox

Host hedef-sunucu
    HostName 10.0.0.5
    User kullanici
    IdentityFile ~/.ssh/hedef
    ProxyJump jump-host

VSCode Remote – SSH, bu ProxyJump tanımını tanır ve jump host üzerinden hedefe bağlanır. Harika değil mi?

8. Yaygın Sorunlar ve Çözümleri

Birkaç klasik sorunla karşılaşmanız muhtemel. İşte deneyimlerime göre en çok karşılaşılanlar ve nasıl çözdüğüm:

Sorun 1: “Could not establish connection” / vscode-server kurulumu takılıyor

En sık karşılaşılan sorun. VSCode, uzak makineye bir script borular (pipe) ile gönderir ve bu script vscode-server’ı indirip kurar. Ama eğer uzak makinede wget/curl yoksa, disk doluysa ya da ağ kısıtlamalıysa bu başarısız olur.

Çözüm: Command Palette > “Remote-SSH: Kill VS Code Server on Host…” komutunu çalıştırın. Bu, vscode-server dosyalarını uzakta temizler. Sonra tekrar bağlanmayı deneyin.

Eğer hâlâ olmuyorsa, ~/.vscode-server dizinini elle silin:

rm -rf ~/.vscode-server

Sonra VSCode’dan tekrar bağlanın.

Sorun 2: Bağlantı çok yavaş / dosya açılışları gecikmeli

SSH bağlantısı üzerinden VS Code’un dosya sistem çağrıları uzakta çalışır. Eğer ağınız yavaşsa ya da sunucu uzak bir datacenter’daysa gecikme hissedebilirsiniz. Ayarlar > “Remote.SSH: Enable Dynamic Forwarding” seçenğini açın. Ayrıca remote.SSH.serverInstallPath ayarını farklı bir disk selmek de bazı durumlarda yardımcı oluyor.

Sorun 3: “Failed to parse remote port”

Bunun sebebi SSH sunucusunun karşılıklı DOSya yansıtması farklı bir portu bildirmesidir. Genelde ~/.ssh/config içinde RemoteForward ile çözülebilir. Config dosyanıza ekleyin:

RemoteForward 52698 127.0.0.1:52698

Sorun 4: Eklenti uzakta çalışmıyor / “Extension not installed on remote”

Eklenti listesinde “Install in SSH: host-adi” butonu görünecek. Tıklayın. Eğer yine olmuyorsa: Command Palette > “Extensions: Install Local Extensions in ‘SSH: host-adi'” komutuna bakın. Listede yüklenmemiş eklentileri görebilir topluca kurabilirsiniz.

Sorun 5: İzin hataları / “Permission denied (publickey)”

SSH anahtarınızın izinleri yanlış olabilir. Şunları kontrol edin:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/id_ed25519

Windows’taysa, anahtar dosyanın sahibi “SYSTEM” ya da siz olmalısınız; miras yoluyla gelen izinler bazen ssh-agent’ı kavarır. PowerShell’den:

icacls $env:USERPROFILE\.ssh\id_ed25519 /inheritance:r
icacls $env:USERPROFILE\.ssh\id_ed25519 /grant:r "$($env:USERNAME):(R)"

9. Güvenlik İpuçları

Son olarak birkaç güvenlik notu:

  • Passphrase’siz anahtar üretmeyin Eğer anahtarınız çalınırsa, passphrase olmadan sunucuya direkt giriş sağlar. Passphrase ekleyin ve ssh-agent kullanın.
  • Firewall’da sadece gerekli portları açık tutun SSH (22) dışındaki portları yetkisiz kişilerden koruyun.
  • PermitRootLogin no sunucudaki /etc/ssh/sshd_config içinde kapatın. Root ile direkt giriş yapılıp yapılmayacağını kontrol edin.
  • VSCode’un server bileşeni ~/.vscode-server dizinine kurulur: Bu dizini periyodik olarak temizlemek ( bazı oyun/esinti kalıntılar birikebilir) disk dolmasını önler.

Sonuç

VSCode Remote – SSH, özellikle sunucuda çalışan開発者ler için oyunun kurallarını değiştiren bir araç.SCP/rsync ile dosya senkronizasyonu yapma, ssh + vim ile gözünüzü yorma devri geçeli zamanlar oldu. Artık tam IDE deneyimini uzakta yaşıyorsunuz; debug, IntelliSense, terminal, git — hepsi yerinde.

Bu yazıda sıfırdan SSH kurulumu, anahtar oluşturma, VSCode eklentisi kurulumu, ilk bağlantı, port forwarding, jump host ve yaygın sorunların çözümlerini gördük. Benim için en keyifli yanı, Ctrl+ ile terminal açtığımda artık uzakta bir shell’in beni beklediğini bilmek. Hemen kullanmaya başlayın, bir kez denedikten sonra geri dönüş yok.

Okuduğunuz için teşekkür ederim! Herhangi bir adımda takılırsanız ya da kendi deneyiminizi paylaşmak isterseniz yorum kısmında buluşalım. Bir sonraki yazıda görüşmek üzere, iyi kodlamalar! 🚀