Pengantar Docker Compose

Menjalankan satu container lewat docker run sudah cukup untuk aplikasi sederhana, tapi aplikasi nyata jarang berdiri sendiri. Sebuah aplikasi web biasanya butuh database, cache, dan mungkin reverse proxy yang berjalan bersamaan, saling terhubung lewat network yang sama, dengan urutan startup yang harus diperhatikan. Menjalankan semua itu manual lewat serangkaian perintah docker run yang panjang, lalu mengulanginya setiap kali environment perlu dibuat ulang, cepat terasa merepotkan baik bagi Developer yang mengatur environment lokal maupun Sysadmin/DevOps Engineer yang menyiapkan staging. Bab ini membahas Docker Compose sebagai solusinya: apa itu Docker Compose, cara instalasinya, sintaks dasar compose.yaml, serta bagaimana versioning dan compatibility file Compose bekerja di Compose V2 yang jadi standar saat ini.

16.1 Apa itu Docker Compose?

Docker Compose adalah tool untuk mendefinisikan dan menjalankan aplikasi Docker yang terdiri dari banyak container sekaligus, lewat satu file konfigurasi berformat YAML. Alih-alih menjalankan setiap container satu per satu lewat docker run dengan opsi yang panjang, seluruh service, network, dan volume yang dibutuhkan aplikasi cukup dituliskan sekali dalam file compose.yaml, lalu dijalankan bersamaan lewat satu perintah.

16.1.1 Masalah yang Diselesaikan Docker Compose

Ambil contoh sederhana: sebuah aplikasi web butuh service web dan database redis berjalan bersamaan dan saling terhubung. Tanpa Compose, Developer harus menjalankan dua perintah docker run terpisah, memastikan keduanya berada di network yang sama, mengatur urutan startup secara manual, dan mengulang seluruh proses itu setiap kali environment dibuat ulang dari awal. Semakin banyak service yang terlibat, semakin panjang pula daftar perintah yang harus diingat dan dijalankan secara konsisten.

Docker Compose menyelesaikan masalah ini lewat beberapa manfaat utama, menurut dokumentasi resmi Docker:

• Mendefinisikan seluruh aplikasi multi-container dalam satu file YAML.
• Menjamin environment yang konsisten di development, testing, maupun production, karena definisi service yang sama dipakai di seluruh tahap tersebut.
• Mengurus urutan startup dan keterhubungan (linking) antar container secara otomatis.
• Merampingkan workflow development dan memangkas waktu setup environment baru.
• Memastikan setiap service berjalan di container-nya sendiri sehingga tidak saling bertabrakan.

Di lapangan, manfaat paling terasa justru pada poin konsistensi environment. Developer yang meng-clone sebuah repository dan menjalankan docker compose up langsung mendapat environment kerja yang identik dengan rekan setimnya, tanpa harus menginstal database atau dependency lain langsung di mesinnya sendiri.

16.1.2 Compose V1 vs Compose V2

Docker Compose punya dua generasi implementasi yang perlu dibedakan. Compose V1 pertama kali dirilis tahun 2014, ditulis dengan Python, dan dijalankan lewat perintah docker-compose (dengan tanda hubung). Compose V2 yang diumumkan tahun 2020 ditulis ulang dengan Go dan dijalankan sebagai plugin resmi Docker CLI lewat perintah docker compose (dua kata terpisah, tanpa tanda hubung).

Compose V1 sudah deprecated dan tidak lagi dikembangkan. Series ini secara konsisten memakai sintaks docker compose (Compose V2) sebagai standar penulisan, kecuali saat membahas konteks legacy secara eksplisit. Docker sendiri merilis Compose v5 pada tahun 2025 yang secara fungsional identik dengan Compose V2, bedanya cuma penambahan Go SDK resmi untuk integrasi programatik; penomoran versi langsung melompat ke v5 supaya tidak membingungkan dengan versi format file Compose lama yang juga memakai label "v2" dan "v3". Baik docker compose versi v2 maupun v5 tetap dipanggil dengan sintaks perintah yang sama, jadi pembahasan di bab ini berlaku untuk keduanya.

16.2 Instalasi Docker Compose

Cara paling praktis mendapatkan Docker Compose adalah lewat Docker Desktop, karena Docker Desktop sudah menyertakan Docker Compose bersama Docker Engine dan Docker CLI yang jadi prasyaratnya. Untuk Linux tanpa Docker Desktop, Docker Compose dipasang sebagai plugin CLI terpisah bernama docker-compose-plugin.

16.2.1 Instalasi via Docker Desktop (macOS dan Windows)

Di macOS dan Windows (lewat WSL2), instalasi Docker Desktop otomatis menyertakan Docker Compose plugin, jadi tidak ada langkah instalasi terpisah yang perlu dilakukan. Setelah Docker Desktop terpasang, versi Compose yang aktif bisa dicek lewat menu About Docker Desktop pada Docker menu, atau lewat terminal dengan perintah docker compose version, persis seperti cara verifikasi di Linux.

16.2.2 Instalasi Plugin di Linux

Untuk distribusi berbasis Debian/Ubuntu, pasang docker-compose-plugin lewat apt setelah repository resmi Docker terdaftar.

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

Untuk distribusi berbasis RPM seperti CentOS, Fedora, atau RHEL, gunakan yum atau dnf sesuai package manager yang dipakai distro tersebut.

sudo yum update
sudo yum install docker-compose-plugin

Kalau repository resmi Docker belum terdaftar di package manager, ikuti dulu langkah pendaftaran repository sesuai distro yang dipakai sebelum menjalankan perintah instalasi di atas. Sysadmin/DevOps Engineer yang mengelola server produksi berbasis Linux umumnya memasang Docker Engine dan Compose plugin lewat jalur package manager ini, bukan Docker Desktop yang memang ditujukan untuk environment desktop.

16.2.3 Instalasi Manual Plugin (Alternatif)

Kalau package manager distro tidak menyediakan docker-compose-plugin, plugin bisa dipasang manual dengan mengunduh binary rilisnya langsung ke direktori CLI plugins milik Docker CLI.

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

Ganti placeholder <versi> dengan nomor rilis Compose yang diinginkan, misalnya v2.39.4, sesuai daftar rilis resmi di halaman GitHub docker/compose. Perintah chmod +x di atas wajib dijalankan supaya binary yang diunduh punya izin eksekusi.

16.2.4 Verifikasi Instalasi

Setelah proses instalasi selesai, verifikasi bahwa Docker Compose sudah terpasang dan bisa dipanggil lewat Docker CLI dengan perintah docker compose version.

docker compose version

Docker Compose version v2.39.4

Kalau output di atas malah memunculkan pesan error seperti docker: 'compose' is not a docker command, berarti plugin belum terpasang dengan benar atau belum terdeteksi oleh Docker CLI. Cek kembali apakah file binary docker-compose memang ada di direktori ~/.docker/cli-plugins/ (untuk instalasi manual) atau ulangi perintah instalasi plugin sesuai distro Linux yang dipakai.

16.3 Sintaks compose.yaml

File konfigurasi Docker Compose lazim diberi nama compose.yaml (nama docker-compose.yml peninggalan Compose V1 juga masih dikenali untuk kompatibilitas). File ini ditulis dalam format YAML dan berisi beberapa elemen tingkat atas yang mendefinisikan seluruh komponen aplikasi.

16.3.1 Elemen Tingkat Atas: services, networks, volumes

Tiga elemen tingkat atas yang paling sering dipakai dalam compose.yaml adalah services, networks, dan volumes. Elemen services mendefinisikan setiap container yang membentuk aplikasi, networks mendefinisikan jaringan custom yang menghubungkan service-service tersebut, dan volumes mendefinisikan penyimpanan persisten yang dipakai bersama antar service.

services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - REDIS_HOST=redis

  redis:
    image: redis:alpine

Contoh di atas mendefinisikan dua service: web yang dibangun dari Dockerfile di direktori saat ini lewat instruksi build, dan redis yang memakai image publik redis:alpine dari Docker Hub lewat instruksi image. Opsi ports memetakan port 8000 di host ke port 5000 di dalam container web, sementara environment mengatur environment variable yang dibaca aplikasi untuk menemukan alamat Redis. Kedua service ini otomatis berada di network yang sama begitu dijalankan lewat Compose, sehingga service web bisa menjangkau redis cukup lewat namanya sebagai hostname, tanpa perlu konfigurasi network manual tambahan.

16.3.2 Menjalankan dan Menghentikan Aplikasi

Setelah compose.yaml siap, jalankan seluruh aplikasi lewat satu perintah docker compose up di direktori yang sama dengan file tersebut.

docker compose up -d

Opsi -d menjalankan seluruh service dalam mode detached di background, sama seperti opsi -d pada docker run. Docker Compose otomatis membuat network khusus untuk aplikasi ini, menarik atau membangun image yang diperlukan, lalu menjalankan seluruh service yang terdefinisi. Cek status seluruh service yang berjalan lewat docker compose ps.

docker compose ps

Untuk menghentikan dan membersihkan seluruh resource yang dibuat Compose (container, network default, tapi bukan named volume kecuali ditentukan lain), jalankan docker compose down.

docker compose down

Perlu diperhatikan bahwa docker compose down tanpa opsi tambahan tidak menghapus named volume yang dipakai service, jadi data yang tersimpan di volume tetap aman. Kalau volume juga ingin dihapus sekaligus, tambahkan opsi -v, tapi berhati-hati karena langkah ini bersifat destruktif dan menghapus seluruh data yang tersimpan di volume tersebut secara permanen.

16.3.3 Struktur Penulisan YAML yang Perlu Diperhatikan

Karena compose.yaml ditulis dalam format YAML, aturan indentation (spasi, bukan tab) sangat menentukan struktur konfigurasi. Setiap level di bawah sebuah key harus konsisten memakai jumlah spasi yang sama, karena YAML memakai indentation untuk menentukan hierarki elemen, bukan tanda kurung seperti pada JSON. Kesalahan indentation sekecil satu spasi saja sudah cukup membuat Compose salah membaca struktur file atau langsung menolak menjalankannya dengan pesan error parsing.

Di lapangan, Developer yang baru pindah dari menulis JSON ke YAML sering terjebak masalah ini, terutama saat menyalin-tempel konfigurasi dari sumber lain yang ternyata memakai tab alih-alih spasi. Editor kode modern umumnya sudah punya plugin validasi YAML yang bisa menangkap masalah indentation semacam ini sebelum file benar-benar dijalankan lewat docker compose up.

16.4 Versioning dan Compatibility

Format file Compose sudah mengalami beberapa kali evolusi sejak Compose V1 pertama dirilis, dan memahami sejarah singkatnya penting supaya tidak bingung saat menemukan file compose.yaml lama yang masih menyertakan elemen version di bagian paling atas.

16.4.1 Dari Format Bernomor Versi ke Compose Specification

Compose V1 mengenal tiga generasi format file yang ditandai lewat elemen version di tingkat atas file: format versi 1 (dirilis bersama Compose 1.0.0 tahun 2014, tanpa elemen services sama sekali sehingga tidak kompatibel dengan Compose V2 maupun v5), format versi 2.x (dirilis bersama Compose 1.6.0 tahun 2016), dan format versi 3.x (dirilis bersama Compose 1.10.0 tahun 2017 dengan tambahan opsi khusus untuk Swarm). Format 2.x dan 3.x ini sangat mirip satu sama lain, tapi penomoran ganda ini justru menimbulkan kebingungan soal fitur mana yang tersedia di versi mana.

Untuk menyudahi kebingungan tersebut, format 2.x dan 3.x akhirnya digabung menjadi satu spesifikasi tunggal bernama Compose Specification (compose-spec.io). Compose V2 dan v5 memakai Compose Specification ini sebagai dasar, dan berbeda dari format bernomor versi sebelumnya, Compose Specification bersifat rolling (terus diperbarui secara bertahap tanpa nomor versi besar) serta menjadikan elemen version di tingkat atas file bersifat opsional.

16.4.2 Status Elemen version Saat Ini

Elemen version di tingkat atas compose.yaml kini sudah obsolete menurut Compose Specification. Elemen ini tetap dipertahankan semata demi kompatibilitas ke belakang dan sifatnya cuma informatif, sehingga kalau tetap dituliskan, Compose V2 maupun v5 akan menampilkan peringatan bahwa elemen tersebut sudah obsolete.

services:
  web:
    image: nginx:alpine

Contoh compose.yaml di atas sengaja tidak menyertakan elemen version sama sekali, karena memang tidak lagi diperlukan. Docker Compose V2 dan v5 selalu memvalidasi file lewat skema Compose Specification paling baru, terlepas dari ada atau tidaknya elemen version di dalam file tersebut. Kalau ada field yang tidak dikenali (biasanya karena file ditulis memakai field dari versi spesifikasi yang lebih baru dari yang didukung Compose yang terpasang), Compose akan menampilkan peringatan alih-alih langsung gagal total.

16.4.3 Kompatibilitas dengan docker stack deploy

Satu pengecualian penting terkait compatibility adalah perintah docker stack deploy yang dipakai untuk deployment lewat Docker Swarm. Perintah ini masih memakai format Compose file version 3 (legacy) milik Compose V1, dan tidak kompatibel dengan Compose Specification versi terbaru. Beberapa fitur yang didefinisikan Compose Specification seperti rolling update, healthcheck lanjutan, rollback_config, dan stop_grace_period tertentu tidak sepenuhnya berlaku sama saat file yang sama dipakai lewat docker stack deploy.

Sysadmin/DevOps Engineer yang menulis compose.yaml untuk dipakai baik lewat docker compose up di development maupun docker stack deploy di Swarm production perlu menyadari perbedaan ini, karena file yang berjalan mulus lewat docker compose tidak otomatis terjamin berperilaku identik saat dideploy lewat docker stack deploy. Kalau target deployment memang Swarm, sebaiknya uji langsung lewat docker stack deploy di environment staging, bukan hanya mengandalkan hasil pengujian lewat docker compose up.

16.4.4 Ringkasan Perbandingan

Sebagai standar penulisan ke depan, cukup gunakan sintaks docker compose dan tulis compose.yaml tanpa elemen version di tingkat atas, kecuali memang harus mempertahankan file lama yang belum dimigrasikan atau menargetkan deployment lewat docker stack deploy secara eksplisit.