Docker Compose Komutları ve Kullanım Rehberi

Sıkça kullandığınız Compose komutları

Docker Compose kırktan fazla alt komut sunar. Bir sunucudaki günlük işlerde bunların yaklaşık bir düzinesi kullanılır. Bu sayfa, komutları yaptığınız işe göre gruplandırır, her biri için net bir gerekçe sunar ve bir komutun tuzak barındırdığı durumlarda derinlemesine inceleme sayfasına yönlendirir.

Buradaki her şey Compose V2 kullanır: docker compose, eski docker-compose betiğinin aksine boşlukla kullanılır. V2, Docker Engine ile birlikte kurulan bir Go eklentisidir ve V1 güncel paketlerden kaldırılmıştır; bu nedenle Temmuz 2026 itibarıyla yeni bir Ubuntu sunucusunda docker-compose: command not found komutunun çalışması beklenir, hata vermesi değil. docker compose version ile kontrol edin. Eğer çıktı boşsa, docker-compose-plugin paketini kurun.

Aşağıdaki her komut, compose.yaml dosyanızın bulunduğu dizinden çalıştırılmalıdır; çünkü Compose proje adını bu dizinden alır ve dosyayı buna göre konumlandırır. Aynı komutu bir üst dizinde çalıştırırsanız Compose no configuration file provided: not found hatasıyla durur. Eğer dosya formatı sizin için yeniyse, bir VPS üzerinde ilk Compose dosyası ile başlayın ve komutlar için buraya geri dönün.

Yaşam döngüsü: yazdığınız dört komut ve container'ları kaldıran komut

docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose down

up -d ağı oluşturur, container'ları oluşturur, başlatır ve geri döner. Container'lar oluşturulduğu anda geri döndüğü için, bu komutu bir curl denetimiyle takip eden dağıtım betikleri genellikle ilk denemede başarısız olur. up -d --wait, sağlık kontrolü (healthcheck) tanımlayan her servis "sağlıklı" durumuna geçene kadar bekler ve herhangi biri bu duruma ulaşamazsa sıfır olmayan bir çıkış kodu döndürür. Bu bayrak, arkasındaki kontrol kadar güvenilirdir; bu nedenle otomasyonda kullanmadan önce Compose'un güvenebileceği bir sağlık kontrolü yazın.

stop container'ları durdurur ancak silmez; bu sayede start aynı container'ları, üzerinde yazılabilir katmanları koruyarak tekrar başlatır. down ise container'ları durdurur, ardından container'ları ve proje ağını kaldırır. Container içinde, bir volume dışında yazılan her veri bu işlemle birlikte silinir. Bu, Compose özelindeki en maliyetli yanlış anlaşılmalardan biridir ve down ve stop arasındaki farkın tamamı bu durumun nerede sorun yarattığını açıklar.

restart bir yeniden yükleme (reload) komutu değildir. Mevcut yapılandırmayla aynı container'ı durdurup başlatır; bu nedenle değişen bir ortam değişkeni, yeni bir image etiketi veya düzenlenmiş bir port eşlemesi hiçbir etki yaratmaz. Bir dosya değişikliğini uygulamak için up -d komutunu tekrar çalıştırmanız gerekir. Compose, her servisi çalışan container'ı ile karşılaştırır ve yalnızca yapılandırması değişenleri yeniden oluşturur.

Değişiklik uygulama: yeniden oluşturma, çekme veya yeniden derleme

docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build web

up -d, herhangi bir değişiklik olmadığında hiçbir işlem yapmaz; bu da onu defalarca çalıştırmayı güvenli kılar. --force-recreate, bu karşılaştırmayı devre dışı bırakır ve yapılandırma aynı olsa bile her container'ı değiştirir; bu nedenle container içindeki tuhaf durumları temizlemenin en hızlı yoludur.

Bir imajı güncellemek iki farklı işlem yaptıkları için iki komut gerektirir. pull, dosyada belirtilen her etiket için güncel imajı indirir. up -d ise servisin imaj kimliğinin çalışan container ile artık eşleşmediğini görür ve onu yeniden oluşturur. Çekme işlemini atlarsanız up -d, geçen ayın latest sürümünü hatasız bir şekilde çalıştırmaya devam eder. Bunun tersi bir risk, çoklu servis içeren yığınlarda ortaya çıkar; tüm servisler için aynı anda latest komutunu çalıştırmak, on saniye önce çalışan bir uygulamayı bozabilir. Bu yüzden kendi kendine barındırılan bir AFFiNE çalışma alanı, dört imaj etiketinin her birini sabitler.

build, image: yerine build: bölümü tanımlayan servisler için geçerlidir. up -d --build, kod üzerinde değişiklik yaparken kullanılan standart döngü olarak tek adımda derleme ve başlatma işlemini gerçekleştirir. --no-cache komutuna ise yalnızca önbelleğe alınmış bir katmanın güncelliğini yitirdiği kesinleştiğinde başvurun, çünkü bu komut her katmanı sıfırdan yeniden derler.

Çalışanları görüntüleme

docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose ls

ps yalnızca çalışan container'ları listeler. Başlangıç sırasında çöken bir servis, -a eklenene kadar burada görünmez; bu nedenle ps içinde görünmeyen ancak ps -a tarafından Exited (1) olarak gösterilen bir container, başlangıç hatasının normal bir belirtisidir. Çıkış kodunu okuyun, ardından günlük kayıtlarını inceleyin.

logs -f tüm servisleri aynı anda takip eder ve her satırın başına servis adını ekler; servisler birbirleriyle iletişim kurduğunda ve olayların sırası önemli olduğunda ihtiyaç duyacağınız görünüm budur. Kapsamı daraltmak için bir servis adı belirtin. Bir aydır çalışan bir container için --tail=100 önemlidir, çünkü varsayılan ayar tüm geçmişi yazdırır ve terminali doldurur. --since 15m, genellikle ihtiyaç duyduğunuz "az önce yaptığım yeniden başlatma sırasında ne oldu?" sorusunu yanıtlar.

top her container içindeki süreçleri listeler; bu, "container çalışıyor" durumu ile "içindeki süreç çalışıyor" durumunu birbirinden ayırır. ls mevcut dizinin dışına çıkar ve ana makinedeki her Compose projesini durumuyla birlikte listeler; böylece üç ay önce başlattığınız yığını bulabilirsiniz.

Bir servis içerisinde kabuk (shell) oturumu açma

docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web sh

exec, hâlihazırda çalışmakta olan bir container içerisinde komut çalıştırır. run, aynı servis tanımından yeni bir container başlatır; servis, içine exec ile girilemeyecek kadar kısa süre ayakta kaldığında bu yöntem gereklidir. run komutunu her zaman --rm ile birlikte kullanın; aksi takdirde her çağrı geride durdurulmuş bir container bırakır ve bunlar docker compose ps -a okunamaz hale gelene kadar birikir.

bash öncesinde sh komutunu deneyin. Alpine tabanlı imajlar bash içermez ve bu durumda exec: "bash": executable file not found in $PATH hatası alınır. run komutuna --no-deps eklemek, servisin bağımlılıklarını atlar; böylece hızlı bir yapılandırma denetimi sırasında tüm veritabanınızın başlatılması engellenmiş olur.

run --rm web env, her .env dosyası, environment: bloğu ve kabuk değişkeni birleştirildikten sonra bir servisin gerçekten sahip olduğu ortamı görmenin en hızlı yoludur. Bir değer hatalı olduğunda, bunun nedeni genellikle birleştirme sırasıdır ve Compose'un env dosyalarını ve secret'ları nasıl çözümlediği konusu, hangi kaynağın öncelikli olduğunu açıklar.

Ağlar, portlar ve isim çözümleme

docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networks

Compose, her servisi tek bir proje ağına dahil eder ve her servis ismi bu ağ üzerinde bir DNS ismi işlevi görür. getent hosts db komutunu web içerisinde çalıştırmak, çözümleme başarılı olduğunda container IP adresini yazdırır, başarısız olduğunda ise hiçbir çıktı vermez; böylece "bu container'lar birbirini görebiliyor mu" sorusuna iki saniye içinde yanıt verir. İsim çözümleniyor ancak bağlantı reddediliyorsa, db içerisindeki süreç 0.0.0.0 yerine 127.0.0.1 adresine bağlıdır; bu nedenle başka bir container'dan gelen paketleri kabul etmez. Bu modelin geri kalanı Compose ağlarının ve servis DNS'inin çalışma mantığı bölümünde açıklanmıştır.

port web 80 komutu, bir container portunun yayınlandığı ana makine adresini ve portunu yazdırır; bu, eşleştirme bir değişkenden geldiğinde tahmin yürütme zorunluluğunu ortadan kaldırır. Bir portu yayınlamak aynı zamanda Docker'ın kendi yönettiği bir güvenlik duvarı kuralı oluşturur ve bu kural sizin kurallarınızın önüne geçer; dolayısıyla özel olduğunu düşündüğünüz bir servis internete açık hale gelebilir. Bu durum yayınlanan Docker portlarının neden ufw'yi devre dışı bıraktığı bölümünde ele alınmıştır. Bu portları yayınlamadan bırakmak ve servislerin önüne proje ağı üzerinde kimlik doğrulaması yapan bir proxy yerleştirmek daha güvenli bir yapıdır; tek oturum açma katmanı olarak Authentik çalıştırmak size bu imkanı sağlar.

Birimler ve veri

docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -v

config --volumes, projenin tanımladığı adlandırılmış birimleri her satırda bir tane olacak şekilde listeler. Yedeklemeniz gereken liste budur. Birimler yeri doldurulamaz veriler içerdiğinde, yedekleme komutunun kendisi de liste kadar önem taşır; bu nedenle PhotoPrism ve Immich karşılaştırması, her fotoğraf sunucusunun ihtiyaç duyduğu döküm ve kopyalama komutlarını ayrıntılı olarak açıklar. cp, bir kabuk açmaya gerek kalmadan, konteyner tarafında service:path biçimini kullanarak bir dosyayı konteynerin içine veya dışına kopyalar.

down -v, bu adlandırılmış birimleri konteynerlerle birlikte kaldırır. Bu komut, bir test yığınını tamamen temizlemek için doğru, ancak veri kaybı yaşamak istemediğiniz herhangi bir yapı için yanlış komuttur; çünkü herhangi bir onay istemez ve geri alma seçeneği yoktur. Bind mount'lar, ana makine dosya sisteminde yaşadıkları için bu işlemden etkilenmezler. Etki alanındaki bu fark, bind mount'lar ve adlandırılmış birimler arasında bilinçli bir seçim yapmanızın nedenlerinden biridir.

Veri kaybı olmadan diskte yer açma

docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune

--remove-orphans, projeye ait olan ancak artık dosyada görünmeyen container'ları siler; bu durum, bir servisi yeniden adlandırdıktan sonra tam olarak karşılaşılan senaryodur. Bu komut kullanılmadığında, söz konusu container'lar çalışmaya devam eder ve docker compose ps tarafından görülmezler.

docker system df, herhangi bir silme işlemi yapmadan önce disk alanının nereye gittiğini gösterir; imajları, container'ları, yerel volume'leri ve build cache'i ayırarak her biri için geri kazanılabilir miktarı listeler. image prune -a, hiçbir etiketle işaretlenmemiş tüm imajları kaldırır; birden fazla sürümü çekilmiş büyük bir imajın bulunduğu bir sunucuda bu işlem genellikle en büyük kazanımı sağlar. builder prune, kendi imajlarını oluşturan her sunucuda sessizce büyüyen build cache'i temizler.

Bu komutların hiçbiri isimlendirilmiş volume'lere dokunmaz. Yalnızca docker volume prune ve docker compose down -v bunu yapar.

Dosyayı bozmadan önce kontrol etme

docker compose config --quiet
docker compose config --services
docker compose --dry-run up -d

config --quiet başarılı olduğunda hiçbir çıktı vermez, bu nedenle bir dağıtım öncesi adımda veya bir git hook içerisinde kullanılmalıdır. Basit config komutu ise tamamen birleştirilmiş ve işlenmiş dosyayı yazdırır; bir değişkenin çözümlenip çözümlenmediğini ve geçersiz kılma dosyasının beklendiği gibi katmanlanıp katmanlanmadığını bu şekilde teyit edersiniz. Ayarlanmamış bir değişken, The "X" variable is not set. Defaulting to a blank string. uyarısının yanında boş bir değer olarak görünür.

--dry-run bir alt komut bayrağı değil, genel bir bayraktır; bu nedenle up komutundan önce gelir. Compose'un gerçekleştireceği her eylemi yazdırır ve hiçbir şeyi değiştirmez; kritik bir yığın üzerinde down komutunu çalıştırmadan önce bu işlem için otuz saniye ayırmak faydalıdır.

Dosyalar, profiller ve projeler arasında çalışma

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -d

Birden fazla -f bayrağı sırayla birleştirilir ve sonraki dosyalar, önceki dosyaların üzerine anahtar bazında yazar. Bu, temel bir dosyayı küçük bir üretim geçersiz kılma ayarıyla tutmanın standart yoludur; ancak listeler ve eşlemeler için kurallar farklılık gösterir. Bu nedenle, beklenmedik bir durumla karşılaştığınızda hata ayıklamadan önce Compose'un birden fazla dosyayı nasıl birleştirdiğini okuyun.

--profile, o profil ile etiketlenmiş servisleri, etiketsiz olanlarla birlikte başlatır; bu da hata ayıklama araçlarını normal bir up işleminden uzak tutar. -p proje adını belirler; böylece aynı yığının iki kopyası, ayrı ağlar ve ayrı birim adlarıyla yan yana çalışabilir. Bir yeniden başlatma sonrasında yığını geri getirmek, manuel olarak yazdığınız bir komut değildir; bu, sizin yerinize bir tane çalıştıran bir birimdir ve Compose yığınlarını önyüklemede başlatma bölümünde açıklanmıştır.

FAQ

What replaced docker-compose with a hyphen?

Compose V2, invoked as docker compose with a space. It is a plugin bundled with Docker Engine, and the V1 Python tool is no longer installed by current packages. If the space form prints nothing, install the docker-compose-plugin package for your distribution. Update old scripts to the space form rather than adding an alias, because V2 has flags V1 never had.

Why does docker compose restart not pick up my config change?

restart stops and starts the existing container with the configuration it was created with, and it never re-reads compose.yaml. Any change to environment variables, ports, volumes or the image tag needs docker compose up -d, which compares each service against its running container and recreates the ones that differ. Add --force-recreate when you want the replacement to happen even though nothing in the file changed.

How do I update a service to a newer image?

Run docker compose pull, then docker compose up -d. The pull fetches the current image for each tag in the file, and up -d recreates any service whose image ID no longer matches its container. Running up -d on its own reuses the image already on disk, which is how a stack pinned to latest sits on a months old build without printing any error.

Which cleanup commands are safe on a live server?

docker system df, docker image prune -a and docker builder prune remove images and cache only, so running services keep working and named volumes are untouched. The dangerous pair is docker compose down -v and docker volume prune, which delete named volumes with no prompt. Run docker compose config --volumes first so you know what is at risk.

Can I run one command without starting the whole stack?

Yes. docker compose run --rm --no-deps web sh starts a single container from the web service definition, skips its dependencies, and removes the container when you exit. Use exec instead when the container is already running, because exec joins the live process and shows you the state the service is actually in.