Portainer ile Docker Yönetimi (Kurulum Rehberi)

Portainer, Docker ortamlarınızı tek bir web arayüzünden yönetmenizi sağlayan, dünya genelinde milyonlarca kurulumu olan açık kaynaklı bir yönetim panelidir. Konteynerleri, imajları, volume’ları, ağları ve Docker Compose stack’lerini komut satırına hiç dokunmadan görsel olarak yönetirsiniz. Portainer’ın kendisi de bir Docker konteyneri olarak çalışır; sunucudaki Docker soketine bağlanarak bütün ortamı denetler. Yani ekstra bir veritabanı ya da karmaşık bir kurulum süreci yoktur, tek komutla ayağa kalkar.

Bu rehberde Portainer’ın ne işe yaradığını, Community ve Business sürümleri arasındaki gerçek farkı, adım adım kurulumu, Compose stack dağıtımını, sık karşılaşılan hataları ve üretim ortamında dikkat edilmesi gereken güvenlik noktalarını bir Docker yöneticisinin günlük hayatından örnekler vererek anlatıyoruz. Portainer’ı çalıştırmak için Docker kurulu bir VPS/sunucu yeterlidir; ev laboratuvarından canlı üretim ortamına kadar her ölçekte aynı mantıkla işler.

Portainer Ne İşe Yarar?

Docker’ı yalnızca komut satırından yönetmek, birkaç konteynerle uğraştığınız sürece sorun değildir. Ama on, yirmi, elli konteyner çalıştırmaya başladığınızda docker ps, docker logs, docker exec komutlarını sürekli yazmak yorucu hale gelir. Hangi konteynerin neden çöktüğünü, hangi imajın güncel olmadığını, hangi volume’ün yer kapladığını takip etmek zorlaşır. Portainer tam burada devreye girer ve bütün bu bilgiyi tek bir ekranda görselleştirir.

Pratikte Portainer ile şu işlerin hepsini fare ile yaparsınız: çalışan konteynerleri durum renkleriyle (yeşil/kırmızı) tek bakışta görmek, herhangi bir konteynerin canlı log’larını açmak, içine terminal (exec/console) ile girmek, yeniden başlatmak veya durdurmak, yeni konteyner ya da Compose stack oluşturmak, imaj çekmek (pull), kullanılmayan imaj ve volume’ları temizlemek, kaynak (CPU/RAM) kullanımını izlemek. Ayrıca rol tabanlı erişim sunar: bir geliştiriciye sunucunun SSH parolasını vermeden, yalnızca belirli ortamlarda konteyner yönetme yetkisi tanıyabilirsiniz. Bu, ekip çalışmasında güvenliği ciddi şekilde artırır.

Tek bir Portainer kurulumu, birden fazla Docker sunucusunu da yönetebilir. Merkezi bir Portainer Server kurar, diğer sunuculara hafif bir Agent (ya da internet üzerinden Edge Agent) yerleştirirsiniz; böylece dağıtık altyapınızı tek panelden görürsünüz.

Community Edition mi Business Edition mi?

Portainer iki sürümle gelir ve burada çoğu kullanıcının kafası karışır. Özetle ikisi de para istemiyor, fark özellik ve lisanslama felsefesinde:

Pratik tavsiye: tek bir VPS’te Docker yönetiyorsanız veya ev laboratuvarı kuruyorsanız Community Edition fazlasıyla yeterlidir ve hiçbir anahtar/telemetri derdi olmadan çalışır. LDAP/Active Directory entegrasyonu, ince ayarlı rol yönetimi ya da üç’ten fazla node yönetimi gerekiyorsa Business Edition’ın ücretsiz tier’ini deneyebilirsiniz. Bu rehberin geri kalanında CE üzerinden ilerliyoruz; kurulum komutu dışında arayüz neredeyse aynıdır.

Kurulum Öncesi: Docker Kontrolü

Portainer bir Docker konteyneri olduğu için önce sunucunuzda Docker’ın çalıştığından emin olun. Aşağıdaki komut sürüm bilgisi dönüyorsa hazırsınız:

docker --version
docker info

Docker kurulu değilse, AlmaLinux/Ubuntu gibi dağıtımlarda resmi Docker deposundan birkaç dakikada kurabilirsiniz. Bu adımı Alastyr sunucu veya bulut sunucu hizmetlerinde root erişiminizle rahatlıkla yapabilirsiniz.

Portainer Kurulumu (Docker ile)

Önce verilerin saklanacağı bir volume oluşturun, ardından Portainer Server konteynerini başlatın. Aşağıdaki komut, kalıcı LTS sürümünü (lts etiketi) çekerek konteyneri sunucu her yeniden başlatıldığında otomatik ayağa kaldıracak şekilde yapılandırır:

# 1) Veri icin volume olustur
docker volume create portainer_data

# 2) Portainer Server konteynerini baslat
docker run -d -p 8000:8000 -p 9443:9443 --name portainer
  --restart=always
  -v /var/run/docker.sock:/var/run/docker.sock
  -v portainer_data:/data
  portainer/portainer-ce:lts

Komutun parçalarını hızlıca açalım:

• -d: Konteyneri arka planda (detached) çalıştırır.
• -p 9443:9443: HTTPS yönetim arayüzü portu. Tarayıcıdan buraya bağlanırsınız; önerilen erişim budur.
• -p 8000:8000: Edge Agent tünel portu. Uzak ortamları Edge ile yönetmeyecekseniz bu satırı atlayabilirsiniz.
• -v /var/run/docker.sock:/var/run/docker.sock: Portainer’ın yerel Docker’ı yönetmesini sağlayan bağlantı. Zorunludur.
• -v portainer_data:/data: Kullanıcılar, ayarlar ve veritabanının saklandığı kalıcı volume.
• --restart=always: Sunucu yeniden başladığında Portainer’ın da otomatik kalkmasını sağlar.

Belirli bir sürüme sabitlemek isterseniz :lts yerine :2.21.5 gibi bir etiket de kullanabilirsiniz; ancak güvenlik yamalarını almak için LTS etiketi çoğu kullanım için daha pratiktir.

İlk Erişim ve Yönetici Hesabı

Tarayıcınızdan https://SUNUCU_IP:9443 adresine gidin. Portainer varsayılan olarak kendi imzaladığı (self-signed) bir SSL sertifikası üretir, bu yüzden tarayıcı “güvenli değil” uyarısı verir; bu ilk kurulumda normaldir, devam edebilirsiniz. Açılan ekranda bir yönetici (admin) hesabı oluşturursunuz. En az 12 karakterlik güçlü bir parola belirleyin, çünkü bu hesap sunucunuzdaki tüm Docker ortamına hakim olacaktır.

Hesabı oluşturduktan sonra “local” Docker ortamını seçerek panele girersiniz. Karşınıza Dashboard çıkar; buradan konteyner sayısı, imajlar, volume’lar ve ağlar özet halinde görünür. Artık tüm yönetim işlerini bu arayüzden yapabilirsiniz.

Önemli: 5 dakikalık güvenlik penceresi

Portainer’ı ilk başlattıktan sonra yönetici hesabını beş dakika içinde oluşturmazsanız, servis güvenlik amacıyla kendini kilitler ve “Your Portainer instance has timed out for security purposes” hatasını verir. Bu, taze bir kurulumun kötü niyetli biri tarafından ele geçirilmesini önlemek içindir. Çözümü basittir: konteyneri yeniden başlatıp yeni bir beş dakikalık pencere açmak yeterli:

docker restart portainer

Restart sonrası hemen https://SUNUCU_IP:9443 adresine gidip admin hesabını oluşturun. Veriyi tamamen sıfırlamak isterseniz konteyneri durdurup silebilir, ardından docker volume rm portainer_data ile volume’ü kaldırıp baştan kurabilirsiniz.

Compose Stack’lerini Portainer ile Dağıtmak

Portainer’ın en çok kullanılan özelliklerinden biri “Stacks” bölümüdür. Burada bir docker-compose.yml dosyasını doğrudan arayüze yapıştırıp dağıtabilir, bir Git deposundan çekebilir ya da dosya yükleyebilirsiniz. Komut satırında docker compose up -d çalıştırmak yerine, tüm stack’i görsel olarak yönetir, tek tıkla yeniden dağıtır veya silersiniz.

Örnek olarak basit bir web sunucusu stack’ini Portainer’da oluşturmak için “Stacks > Add stack” yolunu izleyip şu Compose içeriğini yapıştırmanız yeterli:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    restart: unless-stopped
    volumes:
      - web_data:/usr/share/nginx/html

volumes:
  web_data:

“Deploy the stack” dediğinizde Portainer bu yapılandırmayı çalıştırır; değişken (environment variable) tanımlama, Git’ten otomatik güncelleme (GitOps) gibi özellikleri de buradan kullanabilirsiniz. Bu yaklaşım, özellikle birden fazla servisi birlikte çalıştıran WordPress + veritabanı, n8n + PostgreSQL gibi kurulumlarda hayat kurtarır.

Üretim Ortamında Güvenlik: Bilmeniz Gerekenler

Portainer’ı bir test makinesinde çalıştırmak ile internete açık bir üretim sunucusunda çalıştırmak aynı şey değildir. Docker soketine erişim, pratikte o sunucuda root yetkisi demektir; çünkü soket üzerinden istediğiniz konteyneri ana sisteme bağlayıp her şeye erişebilirsiniz. Bu nedenle Portainer erişimini küçümsemeyin. Aşağıdaki noktalar üretimde kendinizi korur:

• 9443 portunu firewall’da sınırlayın. Mümkünse yönetim arayüzünü herkese açmak yerine yalnızca kendi ofis/VPN IP’nize izin verin. Açık bırakılan bir Portainer paneli, sürekli otomatik parola denemelerinin hedefi olur.
• HTTP yerine her zaman HTTPS (9443) kullanın. Üretimde düz HTTP (9000) portunu açmaktan kaçının; gerekiyorsa önüne Nginx/Traefik + Let’s Encrypt sertifikası koyup gerçek bir alan adı üzerinden yayınlayın.
• Oturum süresini kısaltın. Ayarlardan oturum ömrünü birkaç saatle sınırlamak, unutulan bir tarayıcı sekmesinden ele geçirme riskini azaltır.
• Soketi yalnızca Portainer’a bağlayın, Docker API’sini TCP üzerinden dışa açmayın. Uzak sunucuları yönetmek için Edge Agent kullanın; Edge Agent dış bağlantıyı kendisi başlattığı için sunucuda ek bir gelen port açmanız gerekmez, bu da saldırı yüzeyini küçültür.
• Rol tabanlı erişimi kullanın. Herkese admin vermeyin; ekip üyelerine ihtiyacı kadar yetki tanımlayın.

Bu önlemlerin etkisi, çalıştığınız altyapının sağlamlığıyla katlanır. Alastyr VPS ve sunucularında ağ katmanında Voxility tabanlı, 1 Tbps’in üzerinde kapasiteli L3-L4 anti-DDoS koruma bulunur; yönetim panelinizi hedef alan hacimsel saldırılar daha sunucunuza ulaşmadan filtrelenir. Üst katmanda ise firewall kurallarını ve erişim kısıtlamalarını sizin yapılandırmanız önemlidir.

Bakım: Güncelleme ve Yedekleme

Portainer’ı güncellemek, taze imajı çekip konteyneri yeniden oluşturmak kadar basittir. Verileriniz portainer_data volume’ünde durduğu için konteyneri silmek ayarlarınızı kaybettirmez:

# 1) Yeni imaji cek
docker pull portainer/portainer-ce:lts

# 2) Eski konteyneri durdur ve sil
docker stop portainer
docker rm portainer

# 3) Ayni komutla yeniden olustur (veri volume'da korunur)
docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:lts

Felaket senaryolarına karşı portainer_data volume’ünü düzenli yedekleyin; kullanıcılar, ortam tanımları ve ayarlarınızın tamamı burada saklanır. Alastyr altyapısında günlük otomatik yedekleme standart olarak sunulsa da, kritik konteyner ortamlarınızı kendi periyodunuzla da yedeklemenizi öneririz.

Sıkça Sorulan Sorular

Portainer ücretsiz mi?

Community Edition (CE) tamamen ücretsiz ve açık kaynaklıdır, lisans anahtarı gerektirmez. Business Edition üç node’a kadar ücretsiz kullanılabilir; sonrasında kurumsal özellikler için ücretlidir. Tek bir VPS yöneten çoğu kullanıcı için CE fazlasıyla yeterlidir.

Portainer hangi porttan erişilir?

HTTPS yönetim arayüzü için varsayılan port 9443’tür ve önerilen erişim budur. Eski düz HTTP erişimi için isteğe bağlı 9000 portu eklenebilir, ancak üretimde güvenlik nedeniyle HTTPS kullanmanız tavsiye edilir.

Tek Portainer ile birden çok sunucu yönetebilir miyim?

Evet. Merkezi bir Portainer Server kurar, diğer sunuculara Agent veya internet üzerindeki ortamlar için Edge Agent yerleştirirsiniz. Böylece dağıtık Docker altyapınızı tek bir panelden yönetirsiniz.

Portainer Compose stack çalıştırır mı?

Evet. “Stacks” bölümünden bir docker-compose dosyasını yapıştırabilir, dosya olarak yükleyebilir ya da bir Git deposundan çekebilirsiniz. Stack’i tek tıkla dağıtır, yeniden dağıtır veya silersiniz; değişken tanımlama ve GitOps gibi özellikler de mevcuttur.

“Your Portainer instance has timed out” hatasını nasıl çözerim?

Bu hata, ilk kurulumda yönetici hesabını beş dakika içinde oluşturmadığınızda güvenlik amacıyla ortaya çıkar. Çözüm için konteyneri “docker restart portainer” komutuyla yeniden başlatıp hemen 9443 portundan admin hesabını oluşturun.

Docker soketini bağlamak güvenli mi?

Docker soketine erişim, o sunucuda fiilen root yetkisine eşittir. Bu yüzden soketi yalnızca Portainer konteynerine bağlayın, Docker API’sini TCP üzerinden dışa açmayın ve yönetim portunu firewall ile sınırlayın. Uzak sunucular için soket yerine Edge Agent kullanmak daha güvenlidir.

Portainer’ı nasıl güncellerim, verilerim silinir mi?

Yeni imajı “docker pull” ile çekip eski konteyneri silip aynı komutla yeniden oluşturmanız yeterlidir. Verileriniz portainer_data volume’ünde tutulduğu için konteyneri silmek ayarlarınızı, kullanıcılarınızı ve ortam tanımlarınızı kaybettirmez.

Portainer’ı çalıştırmak için nasıl bir sunucu gerekir?

Docker kurulu, root erişiminiz olan bir VPS veya sunucu yeterlidir. Portainer çok hafif bir konteynerdir; asıl kaynak ihtiyacını üzerinde çalıştıracağınız konteynerler belirler. Düşük gecikme ve istikrar için Türkiye lokasyonundaki bir VPS mantıklı bir tercihtir.

Portainer ile SSH erişimi vermeden ekip yönetimi mümkün mü?

Evet. Rol tabanlı erişim sayesinde ekip üyelerine sunucunun SSH parolasını vermeden, yalnızca belirli ortamlarda konteyner yönetme yetkisi tanıyabilirsiniz. Bu, hem güvenliği artırır hem de yetki dağıtımını kolaylaştırır.