Portainer CE Kurulumu: VPS'te Docker'ı Güvenli Şekilde Yönetmek

Portainer CE nedir, kimler için uygundur?

Portainer'ın GitHub deposuna göre Portainer CE; Docker, Swarm, Podman, Kubernetes ve ACI ortamları için ücretsiz ve hafif bir konteyner yönetim arayüzüdür ve zlib lisansı ile dağıtılır. Aynı açık kaynak tabanı üzerine kurulan Business Edition (BE) ise RBAC, GitOps, edge yönetimi, denetim kaydı ve SSO gibi özellikler ile ticari destek ekleyen ücretli sürümdür. Depo, BE için "Take3" adıyla 3 düğüme kadar ücretsiz kullanım seçeneğini de duyurur.

Bilmeniz gereken önemli bir ayrıntı: Portainer'ın kendi README dosyası, CE'nin homelab, öğrenme ortamları ve kişisel projeler için tasarlandığını; çalışma süresinin, güvenlik duruşunun veya veri bütünlüğünün önemli olduğu üretim ve iş ortamları için desteklenmediğini açıkça yazar. CE desteksiz, garantisiz ve SLA'sızdır. Yani kişisel bir VPS'te kullanmak mantıklıdır; şirketinizin kritik altyapısı için ticari bir seçenek değerlendirmeniz gerekir.

Asıl risk: docker.sock'u bir konteynere bağlamak

Resmî kurulum komutu /var/run/docker.sock dosyasını Portainer konteynerine bağlar. Portainer, Docker'ı bu Unix soketi üzerinden yönetir. Docker belgelerinin güvenlik sayfası ilk cümleyi bu konuya ayırır: Docker daemon'ını yalnızca güvenilir kullanıcılar kontrol edebilmelidir. Aynı sayfa, Docker'ın ana makinedeki bir dizini konteynerle paylaşabildiğini ve konteynerin içinde ana makinenin / dizinini bağlamanın mümkün olduğunu hatırlatır.

Bunun pratik anlamı şudur: Portainer'a yönetici olarak giren biri yeni bir konteyner başlatıp ana makinenin kök dizinini içine bağlayabilir; bu da sunucuda root yetkisine denk bir erişimdir. Bu yüzden Portainer panelini bir veritabanı parolası gibi değil, sunucunun root parolası gibi korumalısınız.

Önerilen güvenlik katmanları:

• Portainer arayüzünü doğrudan internete açmayın; 127.0.0.1:9443 adresine bağlayın.
• Paneli SSH tüneli üzerinden kullanın veya Nginx arkasında HTTPS ile yayınlayıp IP kısıtlaması ekleyin.
• Edge Agent kullanmıyorsanız 8000 portunu hiç yayınlamayın.
• Yönetici hesabı için uzun ve benzersiz bir parola kullanın; parolanızı bir parola yöneticisinde saklayın.
• Sunucunun genel sertleştirmesini (SSH anahtarı, fail2ban, güncellemeler) atlamayın: VPS güvenlik sertleştirme rehberi.

Önkoşullar ve portlar

Portainer'ın Linux kurulum sayfası; Docker'ın resmî talimatlarla kurulmuş güncel bir sürümünü, sudo erişimini ve Docker'ın root olarak çalışmasını varsayar. Ubuntu'da Docker'ı snap ile kurmamanızı özellikle belirtir. Docker'ı Docker Docs: Install Docker Engine on Ubuntu sayfasındaki apt deposu yöntemiyle kurun; Compose temelleri için Docker Compose başlangıç rehberine göz atabilirsiniz. Gereksinim sayfası test edilen Docker sürümlerini ve x86_64 ile ARM64 mimarilerini listeler; belgelerde belirli bir CPU veya RAM alt sınırı verilmez.

Adım 1: Docker Compose ile kurulum

Resmî compose örneğini temel alıp iki değişiklik yapıyoruz: 9443 portunu yalnızca yerel adrese bağlıyoruz ve Edge Agent kullanmadığımız için 8000 portunu kaldırıyoruz (resmî dosyada bu satırın yanında da "Edge Agent kullanmıyorsanız kaldırın" notu vardır).

sudo mkdir -p /opt/portainer
cd /opt/portainer
sudo nano compose.yaml

services:
  portainer:
    container_name: portainer
    image: portainer/portainer-ce:lts
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    ports:
      - 127.0.0.1:9443:9443

volumes:
  portainer_data:
    name: portainer_data

networks:
  default:
    name: portainer_network

Belgeler lts etiketini kullanır. Sürümler arasında sürpriz yaşamamak için Docker Hub'daki etiket listesinden belirli bir sürüm numarası seçip imajı ona sabitlemeyi düşünebilirsiniz. Ardından konteyneri başlatın:

sudo docker compose up -d
sudo docker ps --filter name=portainer

Compose yerine tek komut tercih ederseniz resmî docker run komutunun yerel adrese bağlanmış hali şöyledir:

sudo docker volume create portainer_data
sudo docker run -d -p 127.0.0.1:9443:9443 --name portainer --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data portainer/portainer-ce:lts

Adım 2: İlk giriş, setup token ve 5 dakika kuralı

Portainer 2.43 ve 2.39.4 sürümlerinden itibaren yeni kurulumlar, ilk kurulumu tamamlamak için tek kullanımlık bir setup token ister. Bu belirteç, yeni açılmış bir örneğin yanlış kişi tarafından sahiplenilmesini önlemek için vardır ve sunucu günlüklerinde yazar:

sudo docker logs portainer 2>&1 | grep setup_token

Ayrıca ilk yönetici hesabı konteyner ilk kez başladıktan sonra 5 dakika içinde oluşturulmalıdır; aksi halde Portainer güvenlik nedeniyle servisi durdurur. Panel 127.0.0.1'e bağlı olduğu için ilk kurulumu en hızlı ve güvenli şekilde kendi bilgisayarınızdan bir SSH tüneliyle yapabilirsiniz:

# Kendi bilgisayarınızda çalıştırın
ssh -L 9443:127.0.0.1:9443 kullanici@SUNUCU_IP

Tünel açıkken tarayıcınızda https://localhost:9443 adresine gidin. Portainer kendi oluşturduğu sertifikayı kullandığı için tarayıcı bir sertifika uyarısı gösterecektir; bu adreste beklenen bir durumdur. Setup token alanına günlükteki değeri yapıştırın, yönetici kullanıcı adını ve güçlü bir parola belirleyin, ardından yerel Docker ortamını seçin. SSH ayrıntıları için SSH ile sunucuya bağlanma rehberine bakabilirsiniz.

Kalıcı kullanımda da SSH tüneli en az saldırı yüzeyi bırakan yöntemdir: hiçbir web portu açmanız gerekmez. Paneli tarayıcıdan doğrudan bir alan adıyla açmak istiyorsanız bir sonraki adıma geçin.

Adım 3 (isteğe bağlı): Nginx ve Let's Encrypt arkasında yayınlama

Portainer'ın resmî Nginx örneği nginxproxy/nginx-proxy konteynerini kullanır. Sunucuda zaten Nginx çalıştırıyorsanız aynı mantığı klasik bir server block ile kurabilirsiniz. Portainer'ın ters proxy güvenlik sayfası üç noktayı vurgular: CSRF koruması her zaman açıktır ve Nginx'te Host başlığı için $host yerine $http_host kullanılmalıdır; X-Forwarded-Proto tarayıcının gerçekten kullandığı şemayla eşleşmelidir; Portainer TLS üzerinden servis verdiğinde kimlik çerezlerine Secure bayrağı ekler ve tarayıcı-proxy bağlantısı düz HTTP ise bu çerezler düşer, giriş başarısız olur.

Önce alan adınız için bir A kaydı (ör. portainer.alanadiniz.com) oluşturun. Sonra Nginx yapılandırmasını yazın. Konteyner konsolu gibi etkileşimli özellikler WebSocket bağlantısı kullandığı için nginx: WebSocket proxying sayfasındaki Upgrade ve Connection başlıklarını da iletiyoruz:

sudo nano /etc/nginx/sites-available/portainer

map $http_upgrade $pt_connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    listen [::]:80;
    server_name portainer.alanadiniz.com;

    # Önerilir: yalnızca kendi sabit IP adresinize izin verin
    # allow 203.0.113.10;
    # deny all;

    location / {
        proxy_pass https://127.0.0.1:9443;
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $pt_connection_upgrade;
    }
}

map değişkenine özel bir ad verdik; aynı sunucuda başka bir sitede de $connection_upgrade tanımlıysa Nginx yinelenen değişken hatası vermez. Siteyi etkinleştirip sertifikayı alın:

sudo ln -s /etc/nginx/sites-available/portainer /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d portainer.alanadiniz.com

Certbot 443 için SSL bloğunu ekler ve HTTP'den HTTPS'e yönlendirme yapar. Certbot kurulumu ve otomatik yenileme için Let's Encrypt SSL kurulumu, server block yapısı için Nginx server block rehberi yazılarına bakın. Sertifika alınmadan, düz HTTP üzerinden giriş yapmaya çalışmayın; yukarıda anlatılan Secure çerez sorunu nedeniyle oturum açılmaz.

Paneli herkese açık bir alan adında tutacaksanız nginx: ngx_http_access_module ile allow ve deny satırlarını etkinleştirip erişimi kendi IP adresinize daraltmanızı öneririz. UFW'de yalnızca 22, 80 ve 443 portlarını açık tutun; ayrıntılar UFW güvenlik duvarı rehberinde.

Güncelleme

Portainer'ın yükseltme belgesi, her güncellemeden önce Portainer yapılandırmasının yedeğini almanızı önerir. Compose ile kurduysanız:

cd /opt/portainer
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune

docker run ile kurduysanız belgelerdeki sıra şöyledir: docker stop portainer, docker rm portainer, docker pull portainer/portainer-ce:lts ve ardından kurulumdaki docker run komutunu aynı volume ile yeniden çalıştırmak. Volume silinmediği sürece ayarlarınız korunur.

Yedekleme

Portainer'da yönetici olarak Settings menüsündeki Back up Portainer bölümünden yapılandırmanızı tar.gz dosyası olarak indirebilir, isterseniz parola ile şifreleyebilirsiniz. Zamanlanmış yerel yedekleme ise belgelere göre Business Edition özelliğidir.

Portainer'ın kendi volume'ünü dosya düzeyinde de arşivleyebilirsiniz. Docker belgelerindeki volume yedekleme yöntemine benzer şekilde, geçici bir konteynerle volume içeriğini bir tar arşivine alın:

sudo docker stop portainer
sudo docker run --rm -v portainer_data:/data -v /root/yedek:/yedek ubuntu \
  tar czf /yedek/portainer_data-$(date +%F).tar.gz -C /data .
sudo docker start portainer

Sık görülen sorunlar

--trusted-origins bayrağı (veya TRUSTED_ORIGINS ortam değişkeni) tam URL bekler; compose dosyasında servis altına command: --trusted-origins https://portainer.alanadiniz.com satırı olarak eklenebilir. Nginx tarafında 502 alıyorsanız 502 ve 504 hata rehberine göz atın.

Sık Sorulan Sorular

Portainer CE gerçekten ücretsiz mi?

Evet, zlib lisanslıdır ve ücret alınmaz. Ancak resmî README'ye göre destek, garanti veya SLA sunulmaz ve üretim ortamları için desteklenmez. Bu ihtiyaçlar için Business Edition sunulur.

docker.sock'u salt okunur (:ro) bağlamak riski ortadan kaldırır mı?

Hayır. Salt okunur bağlama, sokete bağlanıp Docker API'sine komut göndermeyi engellemez; Portainer'ın konteyner başlatıp durdurabilmesi zaten bu API erişimine dayanır. Asıl koruma, panele kimin ulaşabildiğini sınırlamaktır.

9000 portunu açmam gerekir mi?

Hayır. Belgelere göre 9000 yalnızca gerekirse eklenen eski HTTP portudur; varsayılan arayüz 9443 üzerinden HTTPS ile sunulur. Bu rehberde Nginx de 9443'e bağlanır.

Portainer diğer servislerimi bozar mı?

Portainer var olan konteynerleri kendiliğinden değiştirmez; ancak arayüzden yaptığınız her işlem (silme, yeniden oluşturma) gerçek Docker işlemidir. Compose ile yönettiğiniz bir uygulamayı Portainer'dan değiştirirseniz compose dosyanızla arasında fark oluşabilir; tek bir yönetim yöntemi seçmek daha düzenli olur.

Yazılım ve hizmet adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen projeler veya şirketlerle ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Vaultwarden kurulumu · Uptime Kuma ile site izleme · Coolify ile kendi PaaS ortamınız · Gitea ile kendi Git sunucunuz · Docker Compose rehberi · Reverse proxy nedir? · VPS güvenlik sertleştirme