Docker Compose Nasıl Kurulur: Linux, macOS ve Windows

Docker çalışıyor ve temel komutlara hâkimsiniz ama konteynerleri tek tek başlatmaktan bıktınız mı?

Docker Compose, tek bir YAML dosyasından çok konteynerli uygulamaları tanımlamanıza ve çalıştırmanıza olanak tanıyan bir araçtır. Kafa karıştıran kısım şu: ortalıkta iki sürüm var — eski bağımsız ikili (v1) ve daha yeni CLI eklentisi (v2). Çoğu kurulum makalesi hangisini kullandığını söylemez; bu yüzden kurulumunuzla örtüşmeyen adımları takip etmek zorunda kalırsınız.

Docker Compose v2, modern Docker kurulumlarıyla birlikte gelen bir eklentidir; bu da kurulum, çalıştırma ve doğrulama işini gerçekten basitleştirir. Artık eskisi kadar manuel değil.

Bu yazıda, Linux, macOS ve Windows’ta Docker Compose’u nasıl doğru şekilde, v2 kullanarak kuracağınızı adım adım göstereceğim.

Sanallaştırma ve konteynerleştirme kavramlarına yeni misiniz? Uygulamalı deneyim için yakın zamanda yayımladığımız Yeni Başlayanlar için Docker makalemizi okuyun.

Docker Compose’u Kurmadan Önce

Öncelikle makinenizde Docker Engine olmalı. Docker Compose tek başına çalışmaz — çalışması için Docker’a ihtiyaç duyar.

Docker sürümünüzü kontrol etmek için bu komutu çalıştırın:

docker --version

Yüklü Docker sürümü

Eğer Docker yüklü değilse, burada durun ve önce onu kurun. Yüklüyse, Compose’un zaten mevcut olup olmadığını kontrol edebilirsiniz:

docker compose version

Yüklü Docker Compose sürümü

Bir sürüm numarası dönerse işiniz bitti — Compose v2 zaten Docker kurulumunuzla birlikte gelmiş. Doğrulama bölümüne atlayabilirsiniz.

Bunun yerine genel bir komut bulunamadı mesajı dönüyorsa, okumaya devam edin.

Bilmeniz gereken temel ayrım şudur:

• Docker Compose v1 eski, bağımsız ikilidir. docker-compose (tireli) ile çağırırsınız. Artık kullanım dışıdır ve bakım yapılmamaktadır.

• Docker Compose v2 modern Docker ile gelen bir CLI eklentisidir. docker compose (tire yok) ile çağırırsınız.

Yakın tarihli bir Docker kurulumu kullanıyorsanız v2’nin zaten yüklü olma olasılığı çok yüksek. Yazının geri kalanı v2’yi esas alır.

Linux’ta Docker Compose Kurulumu

Linux’ta Docker Compose’u edinmenin iki yolu var. İlki Docker’ın resmi deposunu kullanır — önerilen yöntem budur. İkincisi, paket yöneticisi kullanamadığınızda veya belirli bir sürüme ihtiyaç duyduğunuzda işe yarayan manuel kurulumdur.

Yöntem 1: Docker’ın resmi deposunu kullanmak (önerilir)

Bu yöntem Compose’u Docker kurulumunuza bağlı tutar; böylece güncellemeler senkronize kalır.

Docker Engine henüz yüklü değilse, önce Docker’ın resmi apt deposunu yapılandırın:

# Add Docker's GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

Şimdi Docker Engine ve Compose eklentisini birlikte kurun:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

docker-compose-plugin paketi size CLI komutu olarak docker compose sağlar. Çalıştığını doğrulayın:

docker compose version

Ubuntu VM’de Docker Compose sürümü

Hepsi bu.

Yöntem 2: Manuel kurulum (bağımsız ikili)

Belirli bir Compose sürümüne ihtiyacınız olduğunda veya ortamınız Docker’ın deposunu desteklemediğinde bu yöntemi kullanın.

En son sürümü doğrudan GitHub’dan indirerek başlayın. v5.0.1 sürümünü ihtiyacınıza göre değiştirin:

DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v5.0.1/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose

İkili dosyayı çalıştırılabilir yapın:

chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

Ve son olarak, kurulumu doğrulayın:

docker compose version

Ubuntu VM’de Docker Compose sürümü

Burada unutmamanız gereken tek şey, manuel kurulumların otomatik olarak güncellenmediğidir. Bir ikili dosya kurup unutursanız, bilinen hatalara veya güvenlik sorunlarına sahip eski bir sürümü çalıştırabilirsiniz. Bu yolu seçerseniz, ara sıra Docker Compose sürümler sayfasını kontrol etmeyi alışkanlık haline getirin.

macOS’te Docker Compose Kurulumu

macOS’te Docker Compose’u ayrıca kurmanıza gerek yok — Docker Desktop ile birlikte gelir.

Docker Desktop’ı Docker’ın resmi sitesinden indirin. Çipinize uygun sürümü seçtiğinizden emin olun — Apple Silicon (M1–M5) veya Intel.

Kurulumdan sonra Docker Desktop’ı açın ve tamamen başlatmasını bekleyin. Ardından şu komutla Compose’un hazır olduğunu doğrulayın:

docker compose version

macOS’te Docker Compose sürümü

Hepsi bu. Compose v2 kullanıma hazır.

İsteğe bağlı: Homebrew ile kurulum

Araçları Homebrew ile yönetmeyi tercih ediyor ve tam Docker Desktop arayüzünü istemiyorsanız, Docker ve Compose’u Homebrew üzerinden kurabilirsiniz:

brew install docker
brew install docker-compose

Bu yolu seçerseniz, Homebrew’ün Docker Engine’i Desktop uygulaması olmadan kurduğunu unutmayın. CLI kullanımı için gayet uygundur; ancak Docker Dashboard ve otomatik güncellemeler gibi özellikleri kaçırırsınız. Çoğu macOS kullanıcısı için Docker Desktop daha kolay bir yoldur.

Windows’ta Docker Compose Kurulumu

macOS gibi, Windows da Docker Compose’u Docker Desktop aracılığıyla otomatik olarak edinir. Ayrı bir kurulum gerekmez.

Docker Desktop’ı kurmadan önce WSL2’yi (Windows Subsystem for Linux 2) etkinleştirmeniz gerekir. WSL2, Docker’ın Windows’ta gerçek bir Linux çekirdeği üzerinde çalışmasını sağlar; bu da bu platformda konteynerlerin çalışma şeklidir. Etkinleştirmek için PowerShell’i Yönetici olarak açın ve şunu çalıştırın:

wsl --install

İstendiğinde makinenizi yeniden başlatın. Ardından Docker Desktop’ı Docker’ın resmi sitesinden indirip kurun.

Kurulum sırasında "Use WSL2 instead of Hyper-V" seçeneğinin işaretli olduğundan emin olun. Docker Desktop çalışır durumdayken, Compose’un kullanılabilir olduğunu doğrulayın — bunu PowerShell’de veya WSL terminalinizde yapabilirsiniz:

docker compose version

Yaygın izin sorunları

Bir "permission denied" hatası alırsanız, genelde iki sebepten biridir:

• Docker Desktop çalışmıyor. Herhangi bir docker komutunun çalışması için sistem tepsisinde etkin olması gerekir.
• Kullanıcınız doğru grupta değil. WSL’de Linux kullanıcınızın Docker soketine erişimi olduğundan emin olun. Bunu WSL terminalinizi Yönetici olarak çalıştırarak veya kullanıcınızı WSL içinde docker grubuna ekleyerek düzeltebilirsiniz:

sudo usermod -aG docker $USER

Değişikliğin etkili olması için şimdi sadece WSL’den çıkış yapıp tekrar giriş yapın.

Docker Compose Kurulumunu Doğrulayın

Docker Compose’u kurduktan sonra, her şeyin çalıştığını doğrulamak için bu komutu çalıştırın:

docker compose version

Şuna benzer bir çıktı görmelisiniz:

Yüklü Compose sürümü

Kesin sürüm numarası okuma zamanına göre değişir; ancak v5.0.1 veya daha yenisini görüyorsanız hazırsınız.

Eğer docker compose: command not found görürseniz, Compose kurulu değildir veya PATH’inizde değildir. Aşağıdaki sorun giderme bölümüne atlayın.

docker compose ve docker-compose

Çevrimiçi bazı makalelerde tireli docker-compose kullanıldığını fark edebilirsiniz. Fark şudur:

• docker-compose eski v1 komutudur. Docker’dan ayrı olarak kurulan bağımsız bir Python ikilisiydi.

• docker compose (tire yok) v2 CLI eklentisidir ve doğrudan Docker CLI’ın içine yerleşiktir.

Docker 2023’te v1 desteğini bıraktı; dolayısıyla docker-compose artık bakımı yapılmıyor. Hâlâ yüklüyse, hangi sürüme işaret ettiğini kontrol edebilirsiniz:

docker-compose --version

Bir 1.x.x sürümü dönerse eski ikiliyi çalıştırıyorsunuz. Kaldırın ve gelecekte docker compose kullanın. Komutlar neredeyse aynıdır; ancak v2 daha hızlıdır ve aktif olarak bakım görür.

Docker Compose’u Yükseltin

Compose’u nasıl yükselteceğiniz, onu nasıl kurduğunuza bağlıdır.

macOS ve Windows’ta her şeyi Docker Desktop halleder; bu yüzden uygulamayı açın, Settings > Software Updates bölümüne gidin ve gerekirse güncellemesine izin verin. Compose, Docker ile birlikte otomatik olarak yükseltilir.

Linux’ta paket yöneticisiyle şu komutları çalıştırın:

sudo apt-get update
sudo apt-get upgrade docker-compose-plugin

Bu, en son sürümü Docker’ın resmi deposundan çeker.

Manuel kurduysanız, yeni sürüm numarasıyla indirme adımını tekrarlamanız gerekir. En son sürüm için Docker Compose sürümler sayfasına bakın ve ardından ikiliyi değiştirin:

curl -SL https://github.com/docker/compose/releases/download/v5.0.2/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

Her yükseltmeden sonra, yeni sürümün etkin olduğunu doğrulayın:

docker compose version

Başka bir şey yok.

Docker Compose’u Kaldırın

Kaldırma adımları, Compose’u ilk etapta nasıl kurduğunuza bağlıdır.

Linux’ta paket yöneticisiyle kurduysanız, eklentiyi şu komutla kaldırın:

sudo apt-get remove docker-compose-plugin

Manuel kurduysanız, ikiliyi silmeniz yeterlidir:

rm $DOCKER_CONFIG/cli-plugins/docker-compose

Sisteminizde hâlâ eski v1 bağımsız ikilisi varsa, bu komutla bulun ve kaldırın:

sudo rm /usr/local/bin/docker-compose

Kaldırdıktan sonra, docker compose version çalıştırarak gerçekten gittiğini iki kez kontrol edin. Komut bir hata döndürürse kaldırma işlemi başarılı olmuştur.

Yaygın Kurulum Sorunları

Docker Compose’u kurmak ve kaldırmak kolaydır; ancak yine de ters gidebilecek bazı şeyler vardır. Karşılaşabileceğiniz olası sorunları böyle çözebilirsiniz.

"docker compose: command not found"

Bu, ya Compose’un kurulu olmadığını ya da Docker’ın onu bulamadığını gösterir. Önce Docker’ın çalıştığını doğrulayın:

docker --version

Docker düzgünse ama Compose eksikse, eklentiyi yeniden kurun:

sudo apt-get install docker-compose-plugin

İzin reddedildi hataları

docker compose çalıştırırken izin reddedildi hatası görürseniz, muhtemelen kullanıcınızın Docker soketine erişimi yoktur. Kendinizi docker grubuna ekleyin:

sudo usermod -aG docker $USER

Değişikliğin etkili olması için oturumdan çıkıp tekrar giriş yapın. Docker Desktop’ta (macOS/Windows) komutları denemeden önce uygulamanın gerçekten çalıştığından emin olun.

Sürüm uyuşmazlığı

Compose beklenmedik davranıyorsa, gerçekte hangi sürümü çalıştırdığınızı kontrol edin:

docker compose version

Eski bir sürümdeyseniz, önceki bölümdeki yükseltme adımlarını izleyin. Hem v1 hem de v2 kuruluysa, muhtemelen kafa karışıklığının kaynağı budur.

v1 ve v2 arasında çakışmalar

docker-compose (v1) ve docker compose (v2) komutlarının aynı makinede bulunması çakışmalara neden olabilir. v1’in hâlâ mevcut olup olmadığını şu komutla kontrol edin:

which docker-compose

Bir yol dönerse, kaldırın:

sudo rm $(which docker-compose)

Bundan sonra docker compose (tire olmadan) kullanın.

PATH sorunları

Docker kurulu ama komutlar bulunamıyorsa, CLI eklenti dizini PATH’inizde olmayabilir. Compose ikilisinin nerede olduğunu kontrol edin:

ls $DOCKER_CONFIG/cli-plugins/

Oradaysa ama çalışmıyorsa, dizini PATH’inize ~/.bashrc veya ~/.zshrc dosyasında ekleyin:

export PATH=$PATH:$HOME/.docker/cli-plugins

Ardından kabuğunuzu şu komutla yeniden yükleyin:

source ~/.bashrc

Docker Compose v1 ve v2

Uzun süredir Docker kullanıyorsanız, çevrimiçi makale ve videolarda hem docker-compose hem de docker compose gördünüz demektir. Aynı şey değiller.

Docker Compose v1 Docker’dan ayrı kurulan bağımsız bir Python ikilisiydi. docker-compose komutunu (tireli) kullanırdı. Docker 2023’te kullanım dışı bıraktı ve artık bakım ya da güncelleme almıyor.

Docker Compose v2 ise doğrudan Docker CLI’a yerleşik bir Go tabanlı CLI eklentisidir. docker compose (tire yok) ile çağırırsınız. Docker Engine ve Docker Desktop ile birlikte gelir; modern kurulumlarda ekstra bir şey kurmanız gerekmez.

Komut sözdizimi iki sürüm arasında neredeyse aynıdır — çoğu docker-compose komutu docker compose ile aynı şekilde çalışır. Başlıca farklar kaputun altında: v2 daha hızlıdır, Docker araçlarıyla daha iyi entegredir ve aktif olarak bakım görür.

İşte bir karşılaştırma:

Compose v1 ve v2 karşılaştırma tablosu

2026’da v2 ile devam edin. Betikleriniz veya CI hatlarınız hâlâ docker-compose kullanıyorsa, tireyi boşlukla değiştirin — çoğu iş akışı için yapmanız gereken tek değişiklik budur.

Sonuç

Modern bir Docker kurulumundaysanız, Compose v2 zaten yüklüdür. Ek adım gerekmez. macOS ve Windows’ta Docker Desktop uygulaması Compose ile birlikte gelir. Linux kullanıyorsanız, docker-compose-plugin paketi tarafından sağlanır.

Compose dosyaları yazmaya veya çalıştırmaya başlamadan önce, her şeyin yerinde olduğunu teyit etmek için docker compose version çalıştırın.

Hâlâ Compose v1 kullanıyorsanız, şimdi geçiş zamanı. Tireyi bırakın ve eski ikiliyi kaldırın — yapmanız gereken tek şey bu. Mevcut tüm Compose dosyalarınız v2 ile olduğu gibi çalışacaktır.

Docker hakkında daha fazla kaynak mı arıyorsunuz? Şu kursumuza katılın: Introduction to Docker — konteynerler, imajlar ve daha fazlasını öğrenin.