Docker Compose Plugin Kurulumu: docker compose ile docker-compose Farkı

Üç kurulum senaryosu

Docker'ın Compose kurulum genel bakış sayfası üç senaryo tanımlar. Docker Desktop, Compose'u Docker Engine ve Docker CLI ile birlikte getirdiği için belgelerde en kolay ve önerilen yol olarak geçer; Linux, Mac ve Windows için mevcuttur. Plugin yöntemi yalnızca Linux'ta kullanılabilir ve Docker Engine ile CLI'nin zaten kurulu olduğunu varsayar. Standalone yöntem ise önerilmez ve yalnızca geriye dönük uyumluluk için desteklenir.

Bir VPS'te Docker Desktop yerine doğrudan Docker Engine çalıştırıyorsanız sizin için doğru seçenek plugin'in depodan kurulmasıdır. Böylece Compose da Engine gibi paket yöneticisiyle güncellenir.

docker compose ile docker-compose arasındaki fark

Bu iki komutun farkı Compose'un geçmişinden gelir. Compose belgelerindeki tarihçe sayfasına göre Compose v1 2014'te yayımlandı, Python ile yazılmıştı ve docker-compose komutuyla çağrılıyordu. v1 projelerinde Compose dosyasının başında genellikle 2.0 ile 3.8 arasında bir değer taşıyan version öğesi bulunurdu.

Compose v2 2020'de duyuruldu, Go ile yazıldı ve docker compose komutuyla çağrılır. v2, version öğesini yok sayar ve dosyayı tamamen Compose Specification'a göre yorumlar. Compose v5 ise 2025'te yayımlandı ve işlevsel olarak v2 ile aynıdır; temel farkı resmî bir Go SDK getirmesidir. Belgelere göre sürüm numarası, eski "v2" ve "v3" dosya formatı etiketleriyle karışmasın diye doğrudan v5'e atlatıldı. Bugün desteklenen Compose CLI sürümleri v2 ve v5'tir.

Dosya formatı tarafında da benzer bir sadeleşme oldu. v1 döneminde üç ana format vardı: format 1 (2014, Compose 1.0.0), format 2.x (2016, Compose 1.6.0) ve format 3.x (2017, Compose 1.10.0). Format 1 en üstte services anahtarı içermediği için çok farklıdır; belgelere göre bu formatta yazılmış dosyalar v2 veya v5 ile çalışmaz. 2.x ve 3.x formatları Compose Specification altında birleştirildi. Spesifikasyon sürekli güncellenen (rolling) bir yapıdadır ve version öğesini isteğe bağlı hale getirir.

version anahtarı ne olur? Gerçek bir doğrulama

Eski projelerden kalma version: "3.8" satırı bugün ne yapar? Aşağıdaki dosyayı Docker Compose v5.5.1 ile docker compose config --quiet komutundan geçirdik:

version: "3.8"
services:
  web:
    image: nginx:alpine

Komut başarıyla (çıkış kodu 0) döndü, yani dosya geçerli kabul edildi, ancak bir uyarı yazdı: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion. Yani satır hata vermez ama hiçbir etkisi yoktur ve kaldırılması önerilir. Yeni dosyalarınıza version yazmanıza gerek yoktur.

Plugin'i Docker deposundan kurmak

Plugin kurulumu, Docker deposunun sistemde tanımlı olmasını gerektirir. Depoyu henüz eklemediyseniz dağıtımınıza göre Ubuntu kurulumu veya Debian, Fedora, RHEL ve CentOS kurulumu yazısındaki depo adımını uygulayın. Sonra paket dizinini güncelleyip eklentiyi kurun:

# Ubuntu ve Debian
sudo apt-get update
sudo apt-get install docker-compose-plugin

# RPM tabanlı dağıtımlar
sudo yum update
sudo yum install docker-compose-plugin

# Doğrulama
docker compose version

docker compose version komutu kurulu Compose eklentisinin sürümünü yazar. Güncelleme için ayrı bir komut yoktur: belgelere göre aynı update ve install komutlarını yeniden çalıştırmanız, eklentiyi depodaki en güncel sürüme yükseltir. Docker Engine'i tam paket listesiyle kurduysanız docker-compose-plugin o listede zaten bulunur.

Ubuntu'da dikkat etmeniz gereken bir çakışma vardır: Ubuntu kurulum sayfası, dağıtımın kendi docker-compose ve docker-compose-v2 paketlerini resmî olmayan ve çakışabilecek paketler olarak listeler ve kurulumdan önce kaldırılmalarını ister. Debian listesinde de docker-compose yer alır. Sunucunuzda hem dağıtım paketi hem resmî eklenti varsa hangi komutun hangi ikiliyi çağırdığı karışabilir.

Plugin'i elle kurmak

Depo kullanamıyorsanız eklentiyi GitHub sürüm sayfasından indirip CLI eklenti dizinine koyabilirsiniz. Belgeler bu yöntem için açık bir uyarı verir: elle kurulumlar otomatik güncellenmez; bakım kolaylığı için depo yöntemi önerilir.

DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/<sürüm>/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

docker compose version

İlk satır DOCKER_CONFIG değişkeni tanımlı değilse onu $HOME/.docker yapar. İkinci satır bu dizinin altında cli-plugins klasörünü oluşturur, üçüncü satır Compose ikilisini bu klasöre docker-compose adıyla indirir. Kurulum doğruysa son satırdaki docker compose version eklentinin sürümünü yazar. Bu komutlar Compose'u yalnızca o anki kullanıcı için, $HOME altına kurar. Üç değişiklik yapabilirsiniz:

• Tüm kullanıcılar için kurmak: ~/.docker/cli-plugins yerine /usr/local/lib/docker/cli-plugins dizinini kullanın ve chmod adımını sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose olarak çalıştırın.
• Farklı bir sürüm: URL'deki <sürüm> kısmına istediğiniz Compose sürümünü yazın.
• Farklı bir mimari: x86_64 yerine GitHub sürüm sayfasındaki uygun mimari adını kullanın; örneğin ARM sunucularda bu kısım değişir.

chmod +x adımı atlanırsa dosya çalıştırılabilir olmaz ve CLI eklentiyi kullanamaz. Elle kurulumda güncelleme de elle yapılır: yeni sürümü aynı yola indirip yeniden çalıştırılabilir yapmanız gerekir.

Standalone (Legacy) kurulum: yalnızca zorunluysa

Bazı eski betikler hâlâ docker-compose komutunu çağırır. Belgeler standalone ikiliyi yalnızca Docker Desktop veya Compose eklentisini kullanamıyorsanız kurmanızı söyler ve bu kurulumun compose yerine -compose sözdizimini kullandığını hatırlatır: docker compose up yerine docker-compose up yazmanız gerekir.

curl -SL https://github.com/docker/compose/releases/download/<sürüm>/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# Komut bulunamazsa PATH'e bir bağlantı ekleyin:
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Kurulumdan sonra docker-compose komutu çalışmazsa belgeler önce PATH'inizi kontrol etmenizi, gerekirse /usr/bin veya PATH'teki başka bir dizine sembolik bağlantı oluşturmanızı önerir. Eski betiklerinizi zamanla docker compose biçimine geçirmek, iki ayrı Compose ikilisini sunucuda tutma ihtiyacını ortadan kaldırır.

Windows Server üzerinde standalone Compose

Standalone kurulumun belgelerde ayrıca anlatılan ikinci platformu Windows Server'dır. Bu senaryo, Docker daemon'ını doğrudan Windows Server üzerinde binary dosyalarıyla çalıştırıyorsanız geçerlidir; belgelere göre bu kurulumda daemon buildx ve compose bileşenlerini içermez, bu yüzden Compose'u ayrıca indirmeniz gerekir. PowerShell yönetici olarak açılır; eski bir Windows Server sürümündeyseniz (örneğin 2016) GitHub bağlantısı için TLS 1.2'nin etkin olduğundan emin olmanız istenir. Ardından Compose sürüm sayfasındaki docker-compose-windows-x86_64.exe dosyası Start-BitsTransfer ile $Env:ProgramFiles\Docker\docker-compose.exe konumuna indirilir. Belgeler Windows Server 2019'da bu dizinin sistem PATH'inde kayıtlı olduğunu, bu yüzden ek ayar yapmadan docker-compose.exe version ile kurulumu test edebileceğinizi belirtir.

Linux sunucu yöneticileri için bu bölümün asıl mesajı şudur: Windows Server'da bile Compose, Engine paketine dahil gelmiyorsa ayrı bir ikili olarak bakım ister. Linux'ta ise depo üzerinden kurulan docker-compose-plugin bu yükü paket yöneticisine bırakır.

Kurulumu bir Compose dosyasıyla doğrulamak

docker compose version eklentinin kurulu olduğunu gösterir. Bir adım daha ileri gidip eklentinin dosya okuyabildiğini görmek için küçük bir dosyayı config komutundan geçirebilirsiniz. Bu komut container başlatmaz; dosyayı ayrıştırır, doğrular ve normalleştirilmiş halini yazar. Aşağıdaki dosyayı ilkproje adlı bir klasörde compose.yaml olarak kaydettik:

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:8080:80"

docker compose -f compose.yaml config
name: ilkproje
services:
  web:
    image: nginx:alpine
    networks:
      default: null
    ports:
      - mode: ingress
        host_ip: 127.0.0.1
        target: 80
        published: "8080"
        protocol: tcp
networks:
  default:
    name: ilkproje_default

Bu çıktı Compose v5.5.1'in gerçek çıktısıdır ve birkaç şeyi öğretir. Proje adı (name) klasör adından türetilmiştir. Kısa port yazımı "127.0.0.1:8080:80" uzun biçime açılmıştır: host_ip, target ve published alanları ayrı ayrı görünür. Ayrıca siz yazmasanız da projeye ilkproje_default adlı varsayılan bir ağ eklenmiştir. Portu 127.0.0.1 adresine bağlamanın neden önemli olduğunu Docker port yayınlama yazısında anlatıyoruz. Sadece geçerlilik kontrolü istiyorsanız --quiet ekleyin; hata yoksa hiçbir şey yazmadan 0 koduyla çıkar.

Compose'u kaldırmak

Kaldırma yöntemi kurulum biçimine bağlıdır. Paket yöneticisiyle kurduysanız:

# Ubuntu veya Debian
sudo apt-get remove docker-compose-plugin

# RPM tabanlı dağıtımlar
sudo yum remove docker-compose-plugin

# Elle, kullanıcı için kurulduysa
rm $DOCKER_CONFIG/cli-plugins/docker-compose

# Elle, tüm kullanıcılar için kurulduysa
rm /usr/local/lib/docker/cli-plugins/docker-compose

Elle kurulan dosyayı silerken "Permission denied" hatası alırsanız belgelere göre o dosyayı silmek için gerekli izniniz yoktur; komutun başına sudo ekleyip yeniden çalıştırın. Docker Desktop ile gelen Compose'u ayrıca kaldıramazsınız; belgeler Desktop'ı kaldırmanın, başka bir Docker kurulumu yoksa Engine, CLI ve Compose dahil tüm bileşenleri kaldırdığını hatırlatır.

Compose eklentisinin hangi dizinde durduğundan emin değilseniz belgelerdeki şu komut eklentinin yolunu yazar:

docker info --format '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}'

Bu komut bir Go şablonuyla docker info çıktısındaki istemci eklentileri listesini dolaşır ve adı compose olanın yolunu basar. --format şablonlarının mantığını Docker format ve filter kullanımı yazısında ayrıntılı anlatıyoruz.

Sık yapılan hatalar

• Eski betiklerde docker-compose yazmaya devam etmek: plugin kurulumunda komut docker compose biçimindedir. Standalone ikiliyi yalnızca uyumluluk için tutun.
• Dağıtım paketini ve resmî eklentiyi birlikte kurmak: Ubuntu'nun docker-compose ve docker-compose-v2 paketleri resmî paketlerle çakışabilir.
• Elle kurulumu unutmak: elle kurulan eklenti otomatik güncellenmez; sunucunuzda hangi yöntemi kullandığınızı not edin.
• version satırını zorunlu sanmak: v2 ve v5 bu öğeyi yok sayar; Compose v5.5.1 doğrulamamızda yalnızca uyarı verdi.
• Format 1 dosyalarını çalıştırmaya çalışmak: en üstte services anahtarı olmayan çok eski dosyalar v2 ve v5 ile çalışmaz.

Sık Sorulan Sorular

Compose v2 ile v5 arasında dosya açısından fark var mı?

Belgelere göre v5 işlevsel olarak v2 ile aynıdır ve ikisi de Compose Specification'ı kullanır. v5'in temel yeniliği, Compose işlevlerini CLI olmadan uygulamalara katmaya yarayan resmî Go SDK'dır.

docker compose version çalışıyor ama docker-compose bulunamıyor, sorun mu?

Hayır. Plugin kurulumunda doğru komut docker compose biçimidir. docker-compose yalnızca legacy standalone ikiliyi kurduysanız vardır.

Compose'u Docker Engine olmadan kurabilir miyim?

Plugin talimatları Docker Engine ve Docker CLI'nin zaten kurulu olduğunu varsayar. Compose, container'ları Docker Engine üzerinde çalıştırır; önce Engine'i kurmanız gerekir.

Kurulumdan sonra ne öğrenmeliyim?

İlk adım tek servisli bir dosya ve up, logs, down komutlarıdır: Docker Compose başlangıç rehberi. Ardından değişken interpolasyonu (Compose değişken interpolasyonu) ve dosya birleştirme (include, extends ve merge) gibi ileri konulara geçebilirsiniz.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Docker öğrenme rehberi · Compose başlangıç rehberi · Docker Compose rehberi · Docker Ubuntu kurulumu · Compose watch · Compose interpolasyon