Docker Compose Komutları: Sunucu Yönetimi İçin İpuçları
Docker Compose V2 ile sunucu yönetimi yaparken en sık kullanılan komutları yaşam döngüsü, log takibi ve ağ yapılandırması kategorilerinde inceleyerek hızlıca uygulayın.
Sıkça kullandığınız Compose komutları
Docker Compose düzinelerce alt komut içerir. 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 rehberine yönlendirir.
Buradaki her şey Compose V2 veya V5 kullanır: docker compose, eski docker-compose betiğinin aksine boşlukla kullanılır. Her ikisi de Go eklentisidir; Linux üzerinde Compose eklentisi, Docker Engine'den ayrı olarak kurulur. Ubuntu 24.04 LTS, universe deposunda hala eski Python V1 aracını docker-compose sürüm 1.29.2-6ubuntu1 olarak sunmaktadır. docker compose version ile kontrol edin. Komut mevcut değilse, Docker deposunu yapılandırın ve docker-compose-plugin paketini kurun.
Aşağıdaki her komut, compose.yaml dosyanızı içeren dizinden çalıştırılır; Compose, siz aksi belirtmedikçe dizin adını varsayılan proje adı olarak kullanır. -f veya COMPOSE_FILE kullanılmadığı sürece Compose, yapılandırma dosyasını çalışma dizininde ve üst dizinlerinde arar; bu nedenle bir üst dizinden çalıştırmak, yığınınıza yalnızca dosya hala bu arama yolundaysa erişebilir. 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 downup -d ağı oluşturur, container'ları oluşturur, başlatır ve geri döner. Uygulamanın hazır olup olmadığını beklemeden container'ları başlattıktan sonra geri döndüğü için, bu komutun ardından curl kontrolü yapan bir dağıtım betiği genellikle ilk denemede başarısız olur. --wait-timeout süresi dolmuşsa veya servis sağlıksızsa, up -d --wait sıfır olmayan bir çıkış kodu döndürür; bu komut, sağlık kontrolü (healthcheck) olan servislerin sağlıklı hale gelmesini, olmayanların ise çalışır durumda olmasını bekler. Bu bayrağın başarısı arkasındaki kontrole bağlıdır, 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ı aynı yazılabilir katmanla geri getirir. down ise container'ları durdurur, ardından container'ları ve proje ağını kaldırır. Bir volume dışında, container içinde yazılan her şey bu işlemle birlikte silinir. Bu, Compose'daki en maliyetli yanlış anlaşılmadır ve down ve stop arasındaki temel farklar bu durumun nerede sorun yarattığını açıklar.
restart bir yeniden yükleme (reload) komutu değildir. Aynı container'ı mevcut yapılandırmasıyla durdurup başlatır; bu nedenle değiştirilen bir ortam değişkeni, yeni bir image etiketi veya düzenlenen 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 yapılandırması veya image'ı değişenleri yeniden oluşturur.
Değişiklikleri 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 webup -d, yapılandırması ve imajı değişmediğinde çalışan container'ları yeniden kullanır; imaj çekme ve derleme işlemleri servisin çekme politikasına (pull policy) göre gerçekleştirilir. --force-recreate, bu karşılaştırmayı geçersiz kılar ve yapılandırma aynı olsa bile her container'ı değiştirir; bu nedenle container içindeki beklenmedik durumları temizlemenin en hızlı yoludur.
Açık imaj güncelleme rutini, iki farklı işlem gerçekleştirdiği için iki komut kullanır. pull, dosyada belirtilen her etiket (tag) için güncel imajı indirir. up -d ise servisin imaj kimliğinin (image ID) çalışan container ile artık eşleşmediğini algılar ve onu yeniden oluşturur. Varsayılan missing çekme politikası ile, latest hariç (ki bu her zaman çekilir) önbelleğe alınmış etiketler yeniden kullanılır. Bunun tersi bir risk, çoklu servis içeren bir yığında ortaya çıkar; tüm servisler için aynı anda latest çekmek, on saniye önce çalışan bir uygulamayı bozabilir. Bu nedenle kendi kendine barındırılan bir AFFiNE çalışma alanı, uygulama ve geçiş (migration) imajının aynı digest değerine sabitlenmesini önerir. Sabitleme işlemi, yükseltmeyi etiketin bilinçli bir şekilde düzenlenmesi ve ardından aynı çekme ve yeniden oluşturma adımlarının izlenmesi haline getirir. Başlatma sırasında veritabanı geçişi yapan bir yığında, her iki komuttan önce elinizde bir yedek (dump) bulunmalıdır; kendi kendine barındırılan bir Chatwoot destek masası her sürüm yükseltmesinde bu rutini izler.
build, build: bölümü tanımlayan servisler için geçerlidir; buna image: tanımlayan servisler de dahildir. up -d --build, kod üzerinde değişiklik yaparken kullanılan normal döngü olan derleme ve başlatma işlemlerini tek adımda gerçekleştirir. --no-cache komutuna yalnızca önbelleğe alınmış bir katmanın güncelliğini yitirdiği açık olduğunda başvurun, çünkü bu komut her katmanı sıfırdan yeniden derler. Bazı projeler her iki yolu da tek bir klonlanmış depodan sunar; bu durumda iki döngü alternatif güncelleme yollarıdır: kendi kendine barındırılan bir openGym antrenman takipçisi, sabitlenmiş sürümünü derlemek için docker compose up -d --build kullanır, çünkü latest imajlarını çekmek, o sürümden daha yeni bir sürümü çalıştırabilir.
Ç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 lsps yalnızca çalışan container'ları listeler. Başlatma sırasında çöken bir servis, -a eklenene kadar burada görünmez; bu nedenle ps içerisinde görünmeyen ancak ps -a komutunda Exited (1) olarak listelenen bir container, başlatma hatasının tipik bir göstergesidir. Çıkış kodunu okuyun, ardından logları inceleyin.
logs -f tüm servisleri aynı anda takip eder ve her satırın başına servis adını ekler; servislerin birbiriyle haberleştiği ve olay sırasının önemli olduğu durumlarda ihtiyaç duyulan görünüm budur. Kapsamı daraltmak için bir servis adı belirtin. --tail=100, bir aydır çalışan container'lar için önemlidir; çünkü varsayılan ayar tüm geçmişi yazdırarak terminali doldurur. --since 15m, genellikle ihtiyaç duyulan "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 çalışan Compose projelerini durumlarıyla birlikte listeler; durdurulmuş projeleri dahil etmek için -a ekleyin.
Bir servis içerisinde 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 shexec, halihazı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çerisine exec komutuyla 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 birikerek docker compose ps -a çıktısının okunamaz hale gelmesine neden olur.
bash öncesinde sh komutunu deneyin. Bazı Alpine tabanlı imajlar, resmi PostgreSQL Alpine imajı da dahil olmak üzere bash içerir; bu araç mevcut olmadığında hata mesajı exec: "bash": executable file not found in $PATH şeklinde görünür. run komutuna --no-deps eklemek, servisin bağımlılıklarını atlar; bu sayede hızlı bir yapılandırma kontrolü yaparken tüm veritabanınızın başlatılmasını engellemiş olursunuz.
run --rm web env, her bir .env dosyası, environment: bloğu ve shell değişkeni birleştirildikten sonra servisin gerçekte hangi ortam değişkenlerini aldığını 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 belgesi, hangi kaynağın öncelikli olduğunu açıklamaktadır.
Ağlar, portlar ve isim çözümleme
docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networksCompose, varsayılan olarak her servisi tek bir proje ağına dahil eder ve her servis adı bu ağ üzerinde bir DNS ismi işlevi görür. İmaj getent içerdiğinde, web içerisinde getent hosts db komutunu çalıştırmak isim çözümlemesini denetler; ancak db bağlantı kabul edip etmediğini test etmez. İsim çözümleniyor ancak bağlantı reddediliyorsa, sunucunun çalıştığından ve talep edilen adres ile portu dinlediğinden emin olun; yalnızca 127.0.0.1 adresine bağlanmak olası bir hata nedenidir. Aynı sınır, docker run ile veya kendi yığını olarak proje dışında başlatılan bir container'ın, neden jellyfin gibi bir servis ismini çözümlemek için paylaşımlı bir ağa ihtiyaç duyduğunu açıklar; Jellyfin kütüphaneniz için bir Halcyon ön yüzü işaret ettiği sunucuya ulaşamadığında kontrol edilmesi gereken ilk nokta budur. Bu modelin geri kalanı Compose ağları ve servis DNS'inin çalışma mantığı içerisinde yer almaktadır.
port web 80, 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, 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 baypas ettiği konusunda açıklanmıştır. Bu portları yayınlamadan bırakmak ve servislerin önüne proje ağında kimlik doğrulama yapan bir proxy yerleştirmek daha güvenli bir yapıdır; tek oturum açma katmanı olarak Authentik çalıştırmak size bunu sağlar.
Birimler ve veri
docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -vconfig --volumes, projenin bildirdiği adlandırılmış birimleri her satıra bir tane gelecek şekilde listeler. Bu liste, yedekleme envanterinin yalnızca bir parçasıdır; bind mount'ların ve yapılandırma dosyalarının da kontrol edilmesi gerekir. Birimler yeri doldurulamaz veriler içerdiğinde, yedekleme komutunun kesinliği listenin kendisi kadar önemlidir; bu nedenle PhotoPrism ve Immich karşılaştırması, her fotoğraf sunucusunun ihtiyaç duyduğu dump 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ı konteyner içine veya dışına kopyalar.
down -v, harici olanlar hariç, bildirilen adlandırılmış birimleri, konteynerlere bağlı anonim birimleri ve konteynerlerin kendilerini kaldırır. Bu komut, bir test yığınını tamamen temizlemek için doğru, ancak veri içeren herhangi bir yapı için yanlış komuttur; çünkü herhangi bir onay mekanizması veya geri alma işlemi yoktur. Bind mount'lar, ana makine dosya sisteminde bulundukları 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ın nedenlerinden biridir.
Veri kaybı yaşamadan disk alanı açan temizlik işlemleri
docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune--remove-orphans, projeye ait olan ancak dosya içerisinde artık yer almayan 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 varsayılan olarak çalışan yetim (orphan) container'ları da dahil eder.
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 container tarafından kullanılmayan tüm imajları (etiketli olup olmamasına bakılmaksızın) kaldırır; büyük bir imajın birden fazla sürümünü çekmiş bir sunucuda bu işlem genellikle en büyük kazanımı sağlar. builder prune varsayılan olarak askıda kalan (dangling) build cache'i kaldırır; tüm kullanılmayan build cache'i temizlemek için -a bayrağını ekleyin.
Bu komutların hiçbiri isimlendirilmiş (named) volume'lere dokunmaz. docker volume prune --all, docker compose down -v ve docker volume rm isimlendirilmiş volume'leri kaldırır. Yalın docker volume prune komutu ise yalnızca anonim volume'leri siler.
Dosyayı bir sorun yaratmadan önce kontrol etme
docker compose config --quiet
docker compose config --services
docker compose --dry-run up -dconfig --quiet, doğrulama yapar ve başarılı olduğunda hiçbir çıktı vermez; bu nedenle dağıtım öncesi bir adımda veya bir git hook içerisinde kullanılmalıdır. Basit config komutu ise tamamen birleştirilmiş ve değişkenleri işlenmiş dosyayı yazdırır; bir değişkenin çözümlenip çözümlenmediğini ve geçersiz kılma (override) dosyasının beklendiği gibi katmanlanıp katmanlanmadığını bu şekilde teyit edebilirsiniz. Atanmamış 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ğından ziyade küresel bir bayrak olduğu için up komutundan önce gelir. Compose'un gerçekleştireceği her eylemi yazdırır ve hiçbir değişiklik yapmaz; kritik bir stack üzerinde down komutunu çalıştırmadan önce bu işlem için harcanacak otuz saniye oldukça değerlidir.
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 -dBirden fazla -f bayrağı sırayla birleştirilir ve sonraki dosyalar, anahtar bazında öncekileri geçersiz kılar. Bu, küçük bir üretim (production) geçersiz kılma dosyasıyla tek bir temel dosya tutmanın standart yoludur; ancak listeler ve haritalar 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ği konusunu okuyun.
--profile, o profil ile etiketlenmiş servisleri etiketsiz olanlarla birlikte başlatır; bu, hata ayıklama araçlarını normal bir up dışında tutmanızı sağlar. -p proje adını ayarlar, böylece aynı yığının iki kopyası ayrı ağlar ve ayrı birim (volume) adlarıyla yan yana çalışabilir. Yeniden başlatma sonrasında yığını geri getirmek için bir yeniden başlatma politikası veya sizin yerinize Compose çalıştıran bir birim kullanılır; bu konu Compose yığınlarını önyüklemede başlatma bölümünde açıklanmıştır.
FAQ
docker-compose ifadesini tire işareti ile ne değiştirdi?
Compose V2 ve V5, boşluk karakteri ile docker compose şeklinde çağrılır. Linux üzerinde Compose, ayrı olarak kurulan bir eklentidir; Ubuntu 24.04 LTS, universe deposunda hala V1 Python aracını sunmaktadır. Boşluklu kullanım mevcut değilse, Docker deposunu yapılandırın ve docker-compose-plugin paketini kurun. Eski betikleri bir alias eklemek yerine boşluklu formata güncelleyin, çünkü V2, V1'de bulunmayan bayraklara sahiptir.
docker compose restart neden yapılandırma değişikliğimi algılamıyor?
restart, mevcut container'ı oluşturulduğu yapılandırma ile durdurup başlatır ve compose.yaml dosyasını asla yeniden okumaz. Ortam değişkenleri, portlar, volume'lar veya image etiketi üzerindeki herhangi bir değişiklik, her servisi çalışan container'ı ile karşılaştıran ve farklı olanları yeniden oluşturan docker compose up -d komutunu gerektirir. Dosyada hiçbir şey değişmemiş olsa bile yenileme işleminin gerçekleşmesini istiyorsanız --force-recreate ekleyin.
Bir servisi daha yeni bir image sürümüne nasıl güncellerim?
docker compose pull komutunu, ardından docker compose up -d komutunu çalıştırın. Pull işlemi, dosyadaki her etiket için güncel image'ı çeker ve up -d, image ID'si artık container'ı ile eşleşmeyen tüm servisleri yeniden oluşturur. up -d komutunu tek başına çalıştırmak, pull politikasını izler: varsayılan missing politikası, her zaman çekilen latest hariç, önbelleğe alınmış image'ları yeniden kullanır.
Canlı bir sunucuda hangi temizleme komutları güvenlidir?
docker system df, hiçbir şeyi silmeden disk kullanımını raporlar; docker image prune -a ve docker builder prune kullanılmayan image'ları ve build önbelleğini kaldırır, bu nedenle çalışan servisler çalışmaya devam eder ve isimlendirilmiş volume'lar etkilenmez. Tehlikeli ikili, projenin tanımlanmış harici olmayan isimlendirilmiş volume'larını ve bağlı anonim volume'ları sormadan silen docker compose down -v ile tek bir y/N isteminden sonra (veya -f ile hiç sormadan) isimlendirilmiş olanlar dahil kullanılmayan yerel volume'ları silen docker volume prune --all komutudur. Nelerin risk altında olduğunu bilmek için önce docker compose config --volumes komutunu çalıştırın.
Tüm stack'i başlatmadan tek bir komut çalıştırabilir miyim?
Evet. docker compose run --rm --no-deps web sh, web servis tanımından tek bir container başlatır, bağımlılıklarını atlar ve çıktığınızda container'ı kaldırır. Container zaten çalışıyorsa bunun yerine exec kullanın, çünkü exec komutunuzu canlı container içinde çalıştırır ve servisin o anki gerçek durumunu görmenizi sağlar.