Docker Compose ile Çok Servisli Uygulama

Gerçek dünyadaki hiçbir web uygulaması tek başına çalışmaz. Bir WordPress sitesinin arkasında bir MySQL veritabanı, bir Node.js API'nin yanında bir Redis önbelleği, bir yönetim panelinin önünde de bir ters proxy vardır. Bu servisleri tek tek docker run komutlarıyla ayağa kaldırmayı deneyen herkes aynı duvara toslar: onlarca satırlık bayrak, elle oluşturulan ağlar, unutulan hacimler ve "önce hangisini başlatmıştım?" diye not tutulan bir kağıt. Bir sunucuyu yeniden kurmanız gerektiğinde ise bu bilgi genellikle çoktan kaybolmuş olur.

Docker Compose tam olarak bu kaosu ortadan kaldırmak için var. Bütün servislerinizi, aralarındaki bağlantıları, hangi verinin kalıcı olacağını ve hangi ayarların nereden geleceğini compose.yaml adında tek bir metin dosyasında tanımlarsınız. Ardından docker compose up -d yazdığınız anda tüm yapı ayağa kalkar; docker compose down yazdığınızda da temiz bir şekilde iner. Bu rehberde Compose dosyasının anatomisini, en çok kullanılan alanları ve gerçekçi iki örneği (WordPress + MySQL ile app + veritabanı + proxy) uçtan uca ele alacağız. Konteyner kavramına henüz yabancıysanız önce Docker nedir başlangıç rehberi yazısını okumanızı öneririm; buradaki her şey onun üzerine inşa ediliyor.

Docker Compose Nedir ve Neyi Çözer#

Docker Compose, birden çok konteyneri bir "uygulama yığını" olarak yönetmenizi sağlayan bir araçtır. Modern Docker sürümlerinde ayrı bir program değil, Docker'ın kendi eklentisidir; bu yüzden komut artık tire ile ayrılmış docker-compose değil, boşluklu docker compose şeklinde çalışır. Eski docker-compose (v1) kullanımdan kaldırıldı, yeni sunucularda doğrudan docker compose yazmalısınız.

Compose'un çözdüğü asıl problem tekrarlanabilirlik ve okunabilirliktir. Servislerin tanımı koda döküldüğü için sunucunuzu yeniden kursanız bile aynı dosyayla saniyeler içinde ayağa kaldırırsınız. Bu dosyayı Git deposuna koyduğunuzda tüm ekip aynı ortamı paylaşır; "bende çalışıyordu" tartışmaları büyük ölçüde biter. Ayrıca yerel geliştirme, hazırlık (staging) ve üretim ortamları arasında farkları küçük değişikliklerle yönetmek çok daha kolay hâle gelir.

Tek Docker sunucusunda birden çok servisi yönetmek için Compose fazlasıyla yeterlidir. Onlarca sunucuya yayılan, otomatik ölçeklenen dev sistemler için Kubernetes gibi orkestratörler devreye girer; ama küçük ve orta ölçekli projelerin ezici çoğunluğu ömrü boyunca sadece Compose ile mutlu mesut yaşar. Gereğinden fazla karmaşık araca atlamadan önce Compose'un sınırlarını zorlamanızı tavsiye ederim.

compose.yaml Dosyasının Yapısı#

Compose dosyası YAML biçimindedir. YAML'de girinti (indentation) anlamlıdır: iç içe geçmiş alanlar boşluklarla belirlenir ve sekme (tab) karakteri kullanılmaz, yalnızca boşluk. En sık yaşanan "invalid compose file" hatası neredeyse her zaman bozuk bir girintiden kaynaklanır. Dosya adı olarak günümüzde compose.yaml tercih edilir; eski docker-compose.yml adı da hâlâ geçerlidir ve Compose ikisini de otomatik bulur.

Dosyanın üst düzeyinde birkaç ana anahtar bulunur. En önemlisi services; her servis (konteyner) burada tanımlanır. volumes ile adlandırılmış kalıcı depolama alanları, networks ile de servislerin haberleştiği ağlar tanımlanır. Eski dosyalarda gördüğünüz version satırı artık gereksizdir ve Compose tarafından yok sayılır; yeni dosyalara yazmayın.

services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "80:80"
  app:
    build: ./app
    environment:
      NODE_ENV: production

volumes:
  db_data:

networks:
  default:
    name: proje_agi

Bu iskelet üç şeyi gösterir: iki servis (web ve app), db_data adında bir hacim ve varsayılan ağın adlandırılması. Girintinin her seviyede iki boşluk olduğuna dikkat edin; tutarlı girinti YAML'de pazarlık konusu değildir.

Servisleri Tanımlama: image, build ve ports#

Her servis ya hazır bir imajdan (image) ya da kendi Dockerfile'ınızdan (build) çalışır. Hazır bir uygulama kullanıyorsanız image: postgres:16 gibi bir satır yeterlidir. Kendi kodunuzu paketliyorsanız build ile Dockerfile'ın bulunduğu dizini gösterirsiniz. İkisini birlikte de verebilirsiniz: build ile imajı üretip image ile ona bir ad ve etiket atarsınız, böylece imajı yeniden kullanmak kolaylaşır.

Etiket seçimi (tag) sandığınızdan önemlidir. Üretimde asla latest kullanmayın; bugün çektiğiniz latest ile üç ay sonra çektiğiniz bambaşka olabilir ve bu, tanısı en zor arızalardan birini doğurur. Bunun yerine mysql:8.4 gibi sabit bir sürüm sabitleyin. Boyutu küçük tutmak için -alpine varyantlarını tercih edebilirsiniz.

services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    image: firmam/api:1.4.0
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"

ports alanı sol tarafta ana makine (host), sağ tarafta konteyner portunu belirtir: "8080:80" ifadesi sunucunun 8080 portuna geleni konteynerin 80 portuna yönlendirir. Güvenlik açısından kritik bir ayrıntı: yukarıdaki gibi 127.0.0.1:3000:3000 yazarsanız port yalnızca sunucunun kendi içinden erişilebilir olur; önüne bir ters proxy koyacaksanız uygulama portlarını böyle kapatmak iyi bir alışkanlıktır. restart: unless-stopped ise konteyner çökerse veya sunucu yeniden başlarsa servisin otomatik ayağa kalkmasını sağlar; üretimde neredeyse her servise koyulur.

Hacimler, Ağlar ve Bağımlılıklar#

Konteynerler doğaları gereği geçicidir; sildiğinizde içindeki her şey uçar. Veritabanı dosyaları, yüklenen görseller veya yapılandırmalar gibi kalıcı olması gereken veriler mutlaka bir hacimde (volume) tutulmalıdır. İki temel yöntem vardır: adlandırılmış hacim (Docker'ın yönettiği depolama, db_data:/var/lib/mysql gibi) ve bind mount (sunucudaki bir klasörü doğrudan bağlama, ./config:/etc/app gibi). Veritabanları için adlandırılmış hacim, elle düzenleyeceğiniz yapılandırma dosyaları için bind mount pratik bir kuraldır.

Ağlar servislerin birbirini nasıl bulduğunu belirler. Compose sizin için otomatik olarak bir ağ oluşturur ve aynı dosyadaki tüm servisleri bu ağa koyar. En güzel yanı: servisler birbirine servis adıyla ulaşır. Yani app servisiniz veritabanına db:3306 diyerek bağlanır; IP adresi ezberlemeye gerek yoktur çünkü Compose dahili bir DNS sağlar. Bu yüzden veritabanı bağlantı dizesinde host olarak localhost değil, servisin adını (db) yazmalısınız.

depends_on ise başlatma sırasını belirtir; app servisine depends_on: [db] yazarsanız Compose önce db konteynerini başlatır. Ancak dikkat: bu yalnızca konteynerin başlamasını bekler, veritabanının bağlantı kabul etmeye hazır olmasını beklemez. MySQL'in tamamen açılması birkaç saniye sürebilir; bu aralıkta bağlanmaya çalışan uygulama hata verir. Sağlam çözüm condition: service_healthy ile bir sağlık kontrolünü (healthcheck) bekletmektir.

services:
  db:
    image: mysql:8.4
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
  app:
    image: firmam/app:1.0.0
    depends_on:
      db:
        condition: service_healthy

volumes:
  db_data:

Ortam Değişkenleri ve .env Kullanımı#

Parolalar, API anahtarları ve ortama göre değişen ayarlar asla Compose dosyasının içine sabit yazılmamalıdır; hele Git'e gidecek bir dosyada. Docker Compose bunun için .env dosyasını doğrudan destekler: Compose çalıştığı dizinde bir .env görürse içindeki değişkenleri otomatik okur ve compose.yaml içinde ${DEGISKEN} sözdizimiyle bu değerlere ulaşırsınız.

# .env — bu dosya asla Git'e girmemeli (.gitignore'a ekleyin)
MYSQL_ROOT_PASSWORD=cok-gizli-root-parola
MYSQL_DATABASE=wp_uygulama
MYSQL_USER=wp_kullanici
MYSQL_PASSWORD=guclu-bir-parola
WP_PORT=8080

Bu değerleri Compose dosyasında şöyle kullanırsınız:

services:
  db:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}

Burada iki farklı kavramı karıştırmamak önemli. .env dosyası, Compose dosyasının kendisindeki ${...} yer tutucularını doldurur (host tarafında). environment bloğu ise değişkenleri konteynerin içine aktarır. Çok sayıda değişkeniniz varsa env_file: .env.app diyerek bütün bir dosyayı bir servise topluca da verebilirsiniz. Farklı ortamlar için .env.dev, .env.prod gibi dosyalar tutup dağıtım sırasında doğru olanı kopyalamak yaygın ve temiz bir yaklaşımdır.

Aşağıdaki tablo iki mekanizmanın farkını özetliyor:

WordPress + MySQL Örneği (Uçtan Uca)#

Şimdi teoriyi gerçek bir yığında birleştirelim. Aşağıdaki compose.yaml, bir WordPress sitesini ve onun MySQL veritabanını ayağa kaldırır. Değerler yukarıdaki .env dosyasından gelir; böylece dosyanın kendisinde hiçbir parola yer almaz.

services:
  db:
    image: mysql:8.4
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-p${MYSQL_ROOT_PASSWORD}"]
      interval: 10s
      timeout: 5s
      retries: 5

  wordpress:
    image: wordpress:6.5-php8.2-apache
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: ${MYSQL_DATABASE}
      WORDPRESS_DB_USER: ${MYSQL_USER}
      WORDPRESS_DB_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - wp_data:/var/www/html
    ports:
      - "127.0.0.1:${WP_PORT}:80"

volumes:
  db_data:
  wp_data:

Bu dosyada dikkat çekmesi gereken üç nokta var. Birincisi, WordPress veritabanına WORDPRESS_DB_HOST: db:3306 ile bağlanıyor; db burada servis adıdır ve Compose'un dahili DNS'i sayesinde çalışır. İkincisi, hem veritabanı dosyaları (db_data) hem de WordPress'in yükleme klasörü (wp_data) hacimlerde saklandığından konteynerleri silseniz bile içerik korunur. Üçüncüsü, WordPress portunu 127.0.0.1 ile sınırladık; siteyi internete açarken önüne SSL sonlandıran bir ters proxy koymanız beklenir. Bu tür bir kurulumu kendi VDS'inizde çalıştırmak istiyorsanız VDS sunucu çözümlerimiz Docker için biçilmiş kaftandır; yalnızca WordPress'e odaklanacaksanız yönetimli WordPress hosting paketlerimiz de kurulum yükünü tamamen sizden alır.

Dosyayı kaydettikten sonra kurulum tek komuttur:

docker compose up -d

Tarayıcıdan http://SUNUCU_IP:8080 (veya proxy arkasındaki alan adınız) adresine gidip WordPress kurulum sihirbazını tamamlarsınız. Veritabanı zaten hazır olduğu için sihirbaz bağlantı bilgisi sormaz.

App + Veritabanı + Ters Proxy Örneği#

İkinci örnek, tipik bir modern uygulamayı gösteriyor: bir uygulama servisi, bir PostgreSQL veritabanı ve önlerinde Nginx tabanlı bir ters proxy. Proxy, dışarıdan gelen tüm trafiği tek noktadan karşılar, uygulamayı doğrudan internete açmaz. Nginx'i sıfırdan yapılandırmayı merak ediyorsanız Nginx kurulumu rehberi yazısı ayrıntılı bir başlangıç noktasıdır.

services:
  proxy:
    image: nginx:1.27-alpine
    restart: unless-stopped
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - app

  app:
    build: ./app
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://${PG_USER}:${PG_PASSWORD}@db:5432/${PG_DB}
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${PG_USER}
      POSTGRES_PASSWORD: ${PG_PASSWORD}
      POSTGRES_DB: ${PG_DB}
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${PG_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pg_data:

Proxy servisinin yanına bir nginx.conf dosyası koyarsınız; buradaki proxy_pass da yine servis adını kullanır, IP değil:

server {
    listen 80;
    server_name uygulamam.com;

    location / {
        proxy_pass http://app:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Bu mimarinin güzelliği, uygulamanın ve veritabanının hiçbir zaman doğrudan dışarıya açılmamasıdır; sadece proxy'nin 80 (ve gerçek dünyada SSL için 443) portu dinlenir. Uygulamayı docker compose up -d --scale app=3 ile çoğaltıp Nginx tarafında yük dengeleme yapmanız bile mümkündür. Böyle bir yapıyı barındıracak asıl güç sunucusu için bulut sunucu ve özel sunucu seçeneklerimize göz atabilir, trafik arttıkça WAF ve DDoS koruması katmanlarını da devreye alabilirsiniz.

Günlük Yönetim Komutları#

Yığını ayağa kaldırıp yönetmek birkaç temel komuta indirgenir. En sık kullanacağınız komut up, servisleri arka planda (-d, detached) başlatır. down ise hepsini durdurup kaldırır. Dosyada bir değişiklik yaptığınızda up -d komutunu tekrar çalıştırmanız yeterlidir; Compose yalnızca değişen servisleri yeniden oluşturur, dokunulmayanlara karışmaz.

# Tüm yığını arka planda başlat (imaj gerekiyorsa çeker/derler)
docker compose up -d

# Çalışan servislerin durumunu gör
docker compose ps

# Bir servisin loglarını canlı izle
docker compose logs -f app

# Belirli bir servisi yeniden başlat
docker compose restart app

# Değişiklikten sonra imajı yeniden derleyip başlat
docker compose up -d --build

# Yığını durdur ve kaldır (hacimler KORUNUR)
docker compose down

# Hacimler DAHİL her şeyi sil (veriler gider — dikkat!)
docker compose down -v

# Çalışan bir konteynerin içine gir
docker compose exec db bash

En kritik uyarı down -v ile ilgilidir: -v bayrağı adlandırılmış hacimleri de siler, yani veritabanınız yok olur. Sadece servisleri durdurup verinizi korumak istiyorsanız düz docker compose down kullanın. Bir sorunu teşhis ederken ilk bakacağınız yer daima loglardır; docker compose logs -f servis_adi size neredeyse her arızanın kök nedenini gösterir. Değişikliklerinizin dosyada doğru olup olmadığını göndermeden önce docker compose config komutuyla doğrulayabilirsiniz; bu komut nihai birleştirilmiş yapılandırmayı ekrana basar ve sözdizimi hatalarını yakalar.

Sık Yapılan Hatalar ve İpuçları#

Yıllar içinde en çok tekrarlanan birkaç hata var. Birincisi, veritabanı hazır olmadan uygulamanın bağlanmaya çalışması. depends_on tek başına yetmez; mutlaka bir healthcheck ile condition: service_healthy birlikte kullanın veya uygulamanıza bağlantıyı birkaç kez deneyen (retry) bir mantık ekleyin. İkincisi, verinin hacme alınmaması: konteyneri her yeniden oluşturduğunuzda veritabanının sıfırlandığını görüyorsanız neredeyse kesinlikle volumes tanımını unutmuşsunuzdur.

Üçüncü klasik hata, host olarak servis adı yerine localhost yazmaktır. Konteynerin içinde localhost o konteynerin kendisidir; başka bir servise ulaşmak için mutlaka servis adını (db, redis vb.) kullanmalısınız. Dördüncüsü, parolaları doğrudan compose.yaml içine yazıp bu dosyayı Git'e göndermektir; her zaman .env kullanın ve .env'i .gitignore'a ekleyin.

Aşağıdaki tablo en sık kullanılan servis alanlarını hızlı bir başvuru olarak topluyor:

Son bir tavsiye: Compose dosyanızı, sunucunuzun düzenli yedekleme kapsamına ekleyin ve hacim verilerinizi de ayrıca yedekleyin. Compose dosyası uygulamanın "tarifi", hacimler ise "içeriği"dir; ikisi bir arada olmadan tam bir geri dönüş yapamazsınız. Güvenlik için uygulama portlarını proxy arkasına almayı ve mümkünse SSL sertifikası ile HTTPS'i proxy katmanında sonlandırmayı ihmal etmeyin.

Sıkça Sorulan Sorular#

docker compose ile docker-compose arasındaki fark nedir#

Eskiden Compose, Python ile yazılmış ayrı bir program olarak docker-compose (tireli) komutuyla çalışırdı; buna v1 denir ve artık kullanımdan kaldırıldı. Yeni sürümlerde Compose, Docker'ın bir eklentisidir ve boşluklu docker compose (v2) komutuyla çağrılır. İşlevleri büyük ölçüde aynıdır ama v2 daha hızlı ve bakımlıdır; yeni kurulumlarda daima docker compose yazmalısınız.

Compose dosyasında version satırı yazmam gerekir mi#

Hayır, artık gerekmez. Eski dosyaların en üstünde gördüğünüz version: "3.8" gibi satırlar Compose v2 tarafından tamamen yok sayılır ve hatta yazarsanız bir uyarı görebilirsiniz. Yeni compose.yaml dosyalarında doğrudan services: ile başlayın; sürüm belirtmeye ihtiyaç yoktur.

Konteynerleri sildiğimde verilerim kayboluyor, nasıl korurum#

Verinizin kalıcı olması için ilgili dizini bir hacme (volume) bağlamanız gerekir. Örneğin MySQL için db_data:/var/lib/mysql, PostgreSQL için pg_data:/var/lib/postgresql/data satırlarını servise ekleyip aynı hacmi dosyanın altındaki volumes bloğunda tanımlayın. Bu şekilde docker compose down yaptığınızda bile veriniz korunur; yalnızca down -v komutu hacimleri de sildiği için verinizi yok eder.

Bir servis diğerine neden localhost ile bağlanamıyor#

Çünkü konteynerin içinde localhost o konteynerin kendisini işaret eder, komşu servisi değil. Compose otomatik bir ağ ve dahili DNS oluşturduğu için servisler birbirine servis adıyla erişir. Uygulamanızın veritabanı ayarında host olarak localhost yerine servisin adını (örneğin db) yazmalısınız; port da konteynerin iç portudur (3306, 5432 gibi).

depends_on veritabanının hazır olmasını beklemiyor, ne yapmalıyım#

depends_on yalnızca bağımlı konteynerin başlamasını bekler, içindeki servisin bağlantı kabul etmeye hazır olmasını değil. Doğru çözüm, veritabanı servisine bir healthcheck eklemek ve uygulamanın depends_on tanımında condition: service_healthy kullanmaktır. Alternatif olarak uygulamanızın başlangıcında bağlantıyı birkaç saniye arayla yeniden deneyen (retry) bir mantık kurabilirsiniz; ikisi birlikte en sağlam sonucu verir.

.env dosyasını Git'e göndermek güvenli mi#

Hayır, kesinlikle güvenli değildir. .env genellikle veritabanı parolaları ve API anahtarları gibi gizli değerler içerir; bu dosyayı depoya gönderdiğinizde sırlarınız herkese açık hâle gelebilir. .env dosyasını mutlaka .gitignore'a ekleyin ve depoya yalnızca gizli değer içermeyen bir .env.example şablonu koyun. Ekip arkadaşlarınız bu şablonu kopyalayıp kendi gerçek değerlerini doldurur.

Kapanış#

Docker Compose, "çalışan bir uygulama yığınını tek dosyayla tarif etme" fikrini pratiğe döker. compose.yaml içinde servislerinizi, hacimlerinizi, ağlarınızı ve ortam değişkenlerinizi netleştirdikten sonra docker compose up -d ile ayağa kaldırmak, down ile indirmek dakikalar değil saniyeler sürer. WordPress + MySQL gibi basit bir yığından app + veritabanı + ters proxy gibi çok katmanlı bir mimariye kadar aynı mantık ölçeklenir; sabit sürüm etiketleri, hacimlerle kalıcılık, healthcheck ile doğru başlatma sırası ve .env ile ayrılan sırlar da üretim kalitesinin dört köşe taşıdır.

Bu yapıları çalıştırmak için root erişimine ve Docker kurabileceğiniz tam kontrollü bir ortama ihtiyacınız var. Clou.TR'nin VDS ve bulut sunucu paketleri Docker Compose yığınlarınız için hızlı NVMe diskler ve garantili kaynaklar sunar; kurulum ve bakımı bize bırakmak isterseniz sunucu yönetimi hizmetimiz devreye girer. Yalnızca web sitesi barındıracaksanız hosting ve yönetimli WordPress hosting paketlerimizle uğraşmadan yayına geçebilir, alan adınızı domain bölümümüzden hemen alabilirsiniz. Bir sonraki adım için Docker'a giriş yazımızla temeli sağlamlaştırmanızı öneririz.