Portainer ile Docker Yönetimi

Docker'ı komut satırından yönetmek alışkanlık hâline geldiğinde hızlıdır, ama ekipte SSH'ye erişimi olmayan ya da olmaması gereken insanlar varsa duvara toslarsınız. Yazılımcı bir konteynerin logunu görmek ister, destek ekibi bir servisi yeniden başlatmak ister, müşteri kendi test ortamındaki uygulamayı ayağa kaldırmak ister. Bunların her biri için sunucuya kök erişim vermek makul değildir; her seferinde sizin komut yazmanız da sürdürülebilir değildir.

Portainer, Docker'ın üstüne oturan bir web yönetim panelidir ve tam olarak bu ihtiyacı karşılar: konteynerleri, imajları, hacimleri, ağları ve stack'leri tarayıcıdan yönetmenizi sağlar; kullanıcı ve takım tanımlayıp kimin neye erişebileceğini sınırlar; uzak sunucuları tek panelde toplar. Bu rehberde Portainer'ı kuracağız, ilk girişteki beş dakikalık güvenlik penceresini açıklayacağız, panelin gerçek maliyeti olan Docker soketi meselesini ayrıntısıyla konuşacağız, stack dağıtımını ve Git entegrasyonunu göreceğiz, uzak sunucuları agent ile ekleyeceğiz ve güncelleme ile sık yapılan hataları ele alacağız.

Portainer Ne Yapar, Ne Yapmaz#

Portainer bir orkestratör değildir; Docker'ın kendi API'sini kullanan bir arayüzdür. Yani Portainer'ın yapabildiği her şeyi zaten docker komutuyla da yapabilirsiniz. Kattığı değer görsellik, erişim denetimi ve ekip içinde yetki dağıtabilme yeteneğidir.

Bunu net koymak önemli, çünkü Portainer kurup "artık izleme sistemim var" diye düşünen ekipler görüyorum. Panel size anlık durumu gösterir; bir servis gece yarısı çöktüğünde kimseyi uyandırmaz. Uyarı ihtiyacınız varsa ayrı bir izleme katmanı kurmanız gerekir.

Kurulum: Tek Komutla Ayağa Kaldırma#

Portainer'ın topluluk sürümü ücretsizdir ve tek konteyner olarak çalışır. Verisi için adlandırılmış bir hacim oluşturun; bu hacim kullanıcıları, ortam tanımlarını ve ayarları tutar:

docker volume create portainer_data

docker run -d \
  --name portainer \
  --restart unless-stopped \
  -p 127.0.0.1:9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Port yayınını 127.0.0.1 ile sınırlandırdığıma dikkat edin. Portainer varsayılan olarak kendi ürettiği bir sertifikayla 9443 portunda HTTPS sunar, ama bu sertifika güvenilir değildir ve tarayıcı her seferinde uyarı verir. Doğru kurulum, paneli yalnızca yerel arayüze bağlayıp önüne düzgün sertifikalı bir ters proxy koymaktır:

server {
    listen 443 ssl;
    http2 on;
    server_name panel.firmaniz.com;

    ssl_certificate     /etc/letsencrypt/live/panel.firmaniz.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.firmaniz.com/privkey.pem;

    location / {
        proxy_pass https://127.0.0.1:9443;
        proxy_ssl_verify off;          # Portainer'in kendi imzali sertifikasi
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        # Konsol ve log akisi WebSocket kullanir
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600s;
    }
}

Son dört satır olmadan panel açılır ama konteyner konsolu ve canlı log akışı çalışmaz; bu, ters proxy arkasındaki Portainer'da en sık karşılaşılan şikâyettir.

İlk Giriş ve Beş Dakikalık Güvenlik Penceresi#

Portainer'ı kurduktan sonra tarayıcıdan açtığınızda sizden bir yönetici kullanıcı oluşturmanızı ister. Burada bilmeniz gereken kritik bir davranış var: konteyner başladıktan sonra kısa bir süre içinde ilk kullanıcı oluşturulmazsa Portainer kendini kilitler ve kuruluma devam etmek için konteyneri yeniden başlatmanız gerekir.

Bu kasıtlı bir güvenlik önlemidir. Aksi hâlde internete açık bir Portainer örneği, saatlerce "ilk kullanıcıyı oluştur" ekranında bekler ve onu ilk bulan kişi yönetici olur; o kişi de o an sunucunuz üzerinde kök yetkisine sahip olur. Kurulumu yaptıktan hemen sonra tarayıcıyı açıp yönetici hesabını oluşturun.

# Kilitlendiyse tek yapmaniz gereken
docker restart portainer

Yönetici parolasını güçlü seçin; Portainer asgari uzunluk şartı koyar ama asıl korumayı siz sağlarsınız. Rastgele ve uzun bir parola üretmek için şifre üretici aracımızı kullanabilirsiniz.

Docker Soketi: Bu Panelin Gerçek Maliyeti#

Şimdi rehberin en önemli bölümüne geldik ve bunu geçiştirmek istemiyorum. Portainer'a /var/run/docker.sock dosyasını bağladığınızda, o konteynere sunucu üzerinde kök yetkisine eşdeğer bir güç vermiş olursunuz. Docker API'sine erişebilen biri, kök dosya sistemini bağlayan ayrıcalıklı bir konteyner başlatabilir ve makinenin tamamına sahip olur.

Bunun pratik sonuçları şunlar:

1. Portainer'a giriş yapabilen bir yönetici, sunucunuza kök erişimi olan biriyle aynı güce sahiptir.
2. Portainer'da bulunacak bir güvenlik açığı, doğrudan sunucu ele geçirilmesine dönüşür.
3. Paneli internete açık bırakmak, SSH'yi parola ile internete açmakla benzer bir risktir.

Bu yüzden üç önlemi birlikte uygulamanızı öneririm. Birincisi paneli asla ham hâlde internete açmayın; ters proxy arkasına alın, mümkünse IP kısıtlaması ya da VPN arkasında tutun. İkincisi yönetici hesabını yalnızca gerçekten gereken kişilere verin, diğerlerine sınırlı kullanıcı tanımlayın. Üçüncüsü, ekstra bir katman istiyorsanız soketi doğrudan bağlamak yerine yalnızca belirli API uç noktalarına izin veren bir soket vekili konteyneri araya koyun; bu, Portainer'ın erişebileceği işlem kümesini daraltır.

Docker soketinin izin modeli ve permission denied hataları hakkında daha fazlası için Docker daemon socket permission denied yazısına bakabilirsiniz.

Arayüzden Günlük İşler#

Panelin gerçekten zaman kazandırdığı yer günlük operasyondur. Konteyner listesinden bir kaydı açtığınızda dört sekme işinizi görür: Logs canlı log akışını gösterir ve arama yapmanızı sağlar, Console konteyner içine kabuk açar, Stats anlık CPU, bellek ve ağ kullanımını çizer, Inspect ise docker inspect çıktısının okunabilir hâlini verir.

Bu dördü, ekipteki yazılımcıya SSH vermeden hata ayıklatabilmenizi sağlar. Konsol açarken kullanıcı alanını boş bırakmayın; varsayılan root yerine uygulamanın çalıştığı kullanıcıyı seçmek, yanlışlıkla dosya sahipliği bozmayı önler.

Hacim ve ağ ekranları da benzer şekilde işe yarar: hangi hacmin hangi konteyner tarafından kullanıldığını, yetim kalmış hacimleri ve ağa bağlı konteynerleri tek bakışta görürsünüz. Yetim hacimleri temizlemeden önce içeriğine baktığınızdan emin olun; panelden silinen bir hacim geri gelmez. Aynı işleri komut satırında yapmak isterseniz konteyner loglarını okuma ve exec yazısı karşılıklarını veriyor.

Stack Yönetimi ve Git'ten Dağıtım#

Portainer'da Stack, bir Compose dosyasının panel üzerinden yönetilen hâlidir. Üç yolla oluşturabilirsiniz: web editörüne YAML yapıştırarak, dosya yükleyerek ya da bir Git deposunu göstererek.

Üçüncüsü açık ara en sağlıklı yöntemdir. Depo adresini, dalı ve Compose dosyasının yolunu verirsiniz; Portainer dosyayı çeker ve dağıtır. Böylece yapılandırmanın tek doğru kopyası sürüm kontrolünde kalır, kim ne değiştirmiş görebilirsiniz ve panelde yapılan bir düzenleme sessizce kaybolmaz.

# Depoda: deploy/stack.yaml
services:
  app:
    image: registry.firmaniz.com/firmaniz/web:1.4.0
    restart: unless-stopped
    environment:
      APP_ENV: production
    ports:
      - "127.0.0.1:8080:8080"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3

Git tabanlı stack'lerde otomatik güncelleme özelliğini de açabilirsiniz: Portainer belirli aralıklarla depoyu kontrol eder ya da bir web kancasıyla tetiklenir ve değişiklik varsa stack'i yeniden dağıtır. Web kancası yöntemini tercih edin; sürekli sorgulamak yerine dağıtım hattınızın sonunda tek bir istek atmak hem daha hızlı hem daha öngörülebilirdir.

Portainer'da tanımladığınız ortam değişkenleri stack ile birlikte saklanır. Parolaları buraya yazmak yerine, sunucudaki bir dosyadan besleme ya da Swarm secret kullanma yöntemlerini tercih edin.

Uzak Sunucuları Agent ile Eklemek#

Tek Portainer örneğiyle birden fazla sunucuyu yönetebilirsiniz. Bunun için uzak sunuculara küçük bir agent konteyneri kurarsınız; agent, Docker API'sini panele güvenli biçimde açar ve Docker soketini internete çıkarmanıza gerek kalmaz.

# UZAK sunucuda calistirilir
docker run -d \
  --name portainer_agent \
  --restart unless-stopped \
  -p 9001:9001 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  portainer/agent:latest

Ardından panelde Environments bölümünden yeni bir ortam ekleyip 185.12.34.57:9001 adresini verirsiniz. Agent portunu güvenlik duvarında yalnızca Portainer sunucusunun IP'sine açın; herkese açık bir agent portu, Docker soketini internete açmakla aynı kapıya çıkar.

Swarm kümesi yönetiyorsanız agent'ı global servis olarak dağıtırsınız; böylece kümeye eklenen her yeni düğümde otomatik olarak çalışır ve panel tüm düğümleri görür. Swarm kurulumunu henüz yapmadıysanız Docker Swarm ile küme kurulumu yazısı adım adım yol gösteriyor.

NAT arkasındaki ya da size doğrudan bağlantı kuramayan sunucular için Edge agent seçeneği vardır: bağlantıyı uzak sunucu başlatır, siz gelen port açmak zorunda kalmazsınız.

Kullanıcılar, Erişim Denetimi ve Güncelleme#

Portainer'ın topluluk sürümünde kullanıcı, takım ve kaynak bazlı erişim denetimi bulunur: bir ortamı ya da belirli kaynakları yalnızca seçtiğiniz takımın görmesini sağlayabilirsiniz. Ayrıntılı rol tanımları (kim yeniden başlatabilir, kim yalnızca log okuyabilir gibi) ticari sürümün özelliğidir; küçük ekipler için ücretsiz düğüm hakkı sunulur.

Pratik desen şudur: yönetici hesabını yalnızca sistem sorumlularında tutun, geliştiricilere kendi projelerinin ortamına erişen bir takım tanımlayın ve üretim ortamını ayrı bir ortam olarak ekleyip erişimi daraltın.

Güncelleme, verinizi hacimde tuttuğunuz için basittir:

docker pull portainer/portainer-ce:latest
docker stop portainer && docker rm portainer
# Ayni volume ile yeniden olustur - ayarlar korunur
docker run -d --name portainer --restart unless-stopped \
  -p 127.0.0.1:9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Sık yapılan hatalara gelince: paneli doğrudan internete açmak listenin başındadır ve en pahalı olanıdır. İkincisi portainer_data hacmini yedeklememektir; hacim kaybolursa kullanıcılar, ortam tanımları ve stack kayıtları gider. Üçüncüsü ters proxy'de WebSocket başlıklarını atlamak, dördüncüsü agent portunu genele açmak, beşincisi ise panelden elle yapılan değişikliklerin depodaki Compose dosyasıyla çelişmesidir; Git tabanlı stack kullanmak bu sonuncusunu yapısal olarak çözer.

Sıkça Sorulan Sorular#

Portainer ücretsiz mi#

Topluluk sürümü (CE) tamamen ücretsiz ve açık kaynaklıdır; konteyner, stack, hacim ve ağ yönetimi, kullanıcı ve takım tanımlama gibi günlük ihtiyaçların tamamını karşılar. Ticari sürüm ayrıntılı rol tabanlı yetkilendirme, kimlik sağlayıcı entegrasyonları ve destek gibi ek özellikler sunar ve küçük kurulumlar için belirli sayıda düğümü ücretsiz kullanma hakkı verir. Çoğu küçük ve orta ölçekli ekip için topluluk sürümü fazlasıyla yeterlidir.

Portainer güvenli mi, internete açabilir miyim#

Panelin kendisi makul biçimde geliştirilmiş bir yazılımdır ama Docker soketine erişimi olduğu için, ona erişen herkes sunucunuzda kök yetkisine eşdeğer güce sahip olur. Bu yüzden paneli ham hâlde internete açmanızı önermiyorum. Ters proxy arkasına alın, geçerli bir TLS sertifikası kullanın ve mümkünse VPN ya da IP kısıtlaması ekleyin. Yönetici hesaplarını da mümkün olduğunca az kişiyle sınırlayın.

Portainer kurulumu Docker'a zarar verir mi#

Hayır, Portainer mevcut konteynerlerinizi ya da yapılandırmanızı değiştirmez; yalnızca Docker API'sini kullanarak durumu okur ve sizin verdiğiniz komutları iletir. Zaten çalışan konteynerlerinizi panelde görür ve yönetebilirsiniz. Tek dikkat noktası, panelden yapılan değişikliklerin sunucudaki Compose dosyalarınıza yansımamasıdır; bu, ileride "dosyada ne yazıyor, sunucuda ne çalışıyor" farkı yaratabilir.

Portainer verilerimi nasıl yedeklerim#

Bütün ayarlar portainer_data hacminde durur; bu hacmin düzenli kopyasını almanız yeterlidir. Panelin ayarlar bölümünde ayrıca şifrelenmiş bir yedek dosyası indirme seçeneği bulunur ve bu, taşıma senaryolarında pratiktir. Yedeği geri yüklerken aynı ya da daha yeni bir Portainer sürümü kullanmaya dikkat edin; eski sürüme geri yükleme sorun çıkarabilir.

Portainer ile Docker Compose birlikte kullanılabilir mi#

Evet ve yaygın bir kombinasyondur. Portainer'ın stack özelliği zaten Compose biçimini kullanır, dolayısıyla mevcut dosyalarınızı doğrudan yükleyebilirsiniz. En sağlıklı düzen, Compose dosyalarını bir Git deposunda tutup Portainer'a o depoyu göstermektir; böylece hem panelden yönetirsiniz hem de yapılandırmanın tek doğru kopyası sürüm kontrolünde kalır.

Birden fazla sunucuyu tek panelden yönetebilir miyim#

Evet. Her uzak sunucuya bir Portainer agent konteyneri kurar ve panelde ortam olarak eklersiniz; ardından tek arayüzden tüm sunucuların konteynerlerini görürsünüz. Agent portunu yalnızca panel sunucusunun IP'sine açmayı unutmayın. Sunucular NAT arkasındaysa ya da size doğrudan bağlantı kurulamıyorsa, bağlantıyı uzak taraftan başlatan Edge agent seçeneğini kullanabilirsiniz.

Portainer yerine ne kullanabilirim#

Alternatifler ihtiyaca göre değişir. Sadece görsel bir konteyner listesi ve log okuyucu istiyorsanız daha hafif paneller vardır. Swarm ya da Kubernetes yönetiyorsanız ilgili ortamın kendi araçları daha derin kontrol sunar. Asıl ihtiyacınız izleme ve alarm ise Portainer doğru araç değildir; metrik toplayan ve eşik tabanlı uyarı üreten bir izleme yığını kurmanız gerekir.

Kapanış#

Portainer, Docker'ı ekipçe yönetmenin en hızlı yoludur ama bedeli, panele erişimin sunucuya kök erişim anlamına gelmesidir. Aklınızda kalması gereken dört alışkanlık şunlar: paneli asla ham hâlde internete açmayın, ters proxy ve geçerli sertifika arkasına alıp WebSocket başlıklarını eklemeyi unutmayın, portainer_data hacmini yedekleme kapsamınıza alın ve stack'leri panelde elle düzenlemek yerine Git deposundan dağıtın. Panelin bir izleme sistemi olmadığını da unutmayın; gece yarısı sizi kimse uyandırmayacaksa ayrı bir alarm katmanı kurmanız gerekir.

Bu tür bir paneli çalıştıracağınız sunucunun hem erişilebilir hem de yalıtılmış olması gerekir. Tam root erişimli VDS ya da kaynağını esnetebileceğiniz bulut sunucu paketlerimiz bu iş için uygundur; kurulum, sertifika ve erişim sertleştirmesini devretmek isterseniz sunucu yönetimi hizmetimiz bunları üstlenir. Panel alan adınız için SSL sertifikası ve konteyner verilerinizin kopyası için yedekleme çözümümüz tamamlayıcı adımlardır.