Cheat Sheet Perintah Docker Compose di Server

Perintah Compose yang benar-benar Anda gunakan

Docker Compose menyediakan puluhan subperintah. Pekerjaan harian pada server biasanya hanya menggunakan sekitar selusin. Halaman ini mengelompokkan perintah tersebut berdasarkan tugasnya, memberikan satu alasan singkat untuk setiap perintah, dan mengarahkan Anda ke pembahasan mendalam jika suatu perintah memiliki jebakan tertentu.

Semua contoh di sini menggunakan Compose V2 atau V5: docker compose dengan spasi, bukan skrip lama docker-compose. Keduanya merupakan plugin Go. Di Linux, plugin Compose diinstal secara terpisah dari Docker Engine. Ubuntu 24.04 LTS masih menyediakan alat Python V1 lama sebagai docker-compose versi 1.29.2-6ubuntu1 dalam repositori universe. Periksa dengan docker compose version. Jika perintah tersebut tidak tersedia, siapkan repositori Docker lalu instal paket docker-compose-plugin.

Setiap perintah di bawah ini dijalankan dari direktori yang berisi compose.yaml. Compose menggunakan nama direktori tersebut sebagai nama proyek default, kecuali Anda menggantinya. Tanpa -f atau COMPOSE_FILE, Compose mencari file konfigurasi di direktori kerja dan direktori induknya. Jadi, menjalankan perintah satu tingkat di atas hanya menemukan stack Anda jika filenya masih berada dalam jalur pencarian tersebut. Jika format file itu sendiri masih baru bagi Anda, mulai dengan file Compose pertama pada VPS, lalu kembali ke sini untuk mempelajari perintah-perintahnya.

Siklus hidup: empat perintah yang Anda ketik, dan satu perintah yang menghapus container

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

up -d membuat network, membuat container, menjalankannya, lalu selesai. Perintah ini selesai setelah container dijalankan tanpa menunggu aplikasi siap digunakan. Karena itu, skrip deployment yang langsung menjalankan probe curl sering gagal pada percobaan pertama. up -d --wait menunggu service yang memiliki healthcheck hingga berstatus healthy, serta menunggu service tanpa healthcheck hingga berjalan. Service yang berstatus unhealthy atau --wait-timeout yang kedaluwarsa menyebabkan exit code non-zero. Flag ini hanya sebaik pemeriksaan yang mendasarinya. Karena itu, buat healthcheck yang dapat dipercaya oleh Compose sebelum mengandalkannya dalam automation.

stop menghentikan container dan mempertahankannya. Dengan demikian, start menjalankan kembali container yang sama dengan writable layer yang sama. down menghentikan container, lalu menghapus container dan network project. Semua data yang ditulis di dalam container dan di luar volume akan ikut terhapus. Ini adalah kesalahpahaman paling berisiko dalam Compose. Perbedaan lengkap antara down dan stop menjelaskan dampaknya.

restart bukan reload. Perintah ini menghentikan dan menjalankan kembali container yang sama dengan konfigurasi yang sudah dimilikinya. Karena itu, perubahan environment variable, tag image baru, atau perubahan port mapping sama sekali tidak berpengaruh. Untuk menerapkan perubahan file, jalankan up -d lagi. Compose membandingkan setiap service dengan container yang sedang berjalan, lalu membuat ulang container yang konfigurasi atau image-nya berubah.

Menerapkan perubahan: membuat ulang, pull, atau build

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 menggunakan kembali container yang sedang berjalan jika konfigurasinya dan image-nya tidak berubah; proses pull dan build image mengikuti kebijakan pull service. --force-recreate mengabaikan perbandingan tersebut dan mengganti setiap container meskipun konfigurasinya identik. Ini adalah cara tercepat untuk menghapus state yang tidak semestinya di dalam container.

Rutinitas pembaruan image secara eksplisit menggunakan dua perintah karena keduanya melakukan hal yang berbeda. pull mengunduh image terbaru untuk setiap tag yang tercantum dalam file. Setelah itu, up -d mendeteksi bahwa ID image service tidak lagi cocok dengan container yang sedang berjalan, lalu membuat ulang container tersebut. Dengan kebijakan pull default missing, tag yang tersedia di cache akan digunakan kembali, kecuali latest yang selalu di-pull. Risiko sebaliknya muncul pada stack dengan banyak service. Menjalankan pull latest untuk semua service sekaligus dapat merusak aplikasi yang masih berfungsi sepuluh detik sebelumnya. Karena itu, workspace AFFiNE yang di-host sendiri menyarankan agar image aplikasi dan image migrasi dipatok ke digest yang sama. Pinning juga mengubah upgrade menjadi pengeditan tag secara sengaja, yang kemudian diikuti pull dan recreate yang sama. Pada stack yang memigrasikan database saat boot, siapkan dump sebelum menjalankan salah satu perintah tersebut. Itulah rutinitas yang diikuti meja dukungan Chatwoot yang di-host sendiri untuk setiap pembaruan versi.

build berlaku untuk service yang mendeklarasikan bagian build:, termasuk service yang juga mendeklarasikan image:. up -d --build melakukan build dan start dalam satu langkah. Ini adalah siklus normal saat Anda mengubah kode. Gunakan --no-cache hanya jika layer yang tersimpan di cache jelas sudah usang, karena perintah ini membangun ulang setiap layer dari awal. Beberapa project menyediakan kedua jalur tersebut dari satu repo hasil clone. Dalam kondisi itu, kedua siklus tersebut menjadi jalur pembaruan alternatif: pelacak latihan openGym yang di-host sendiri menggunakan docker compose up -d --build untuk membangun checkout yang dipatok, karena melakukan pull pada image latest dapat menjalankan rilis yang lebih baru daripada checkout tersebut.

Melihat apa yang sedang berjalan

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 hanya mencantumkan container yang sedang berjalan. Service yang mengalami crash saat start tidak akan terlihat di sana sampai Anda menambahkan -a. Karena itu, container yang tidak muncul pada ps tetapi ditampilkan sebagai Exited (1) oleh ps -a merupakan pola normal pada kegagalan saat start. Baca exit code, lalu baca log.

logs -f mengikuti semua service secara bersamaan dan menambahkan nama service di awal setiap baris. Tampilan ini berguna ketika service saling berkomunikasi dan urutan kejadian penting. Tentukan nama service untuk mempersempit hasil. --tail=100 penting untuk container yang sudah berjalan selama sebulan karena output default menampilkan seluruh riwayat dan membanjiri terminal. --since 15m menjawab pertanyaan yang biasanya Anda miliki, yaitu apa yang terjadi selama restart yang baru saja dilakukan.

top mencantumkan proses di dalam setiap container. Dengan demikian, Anda dapat membedakan antara “container sedang berjalan” dan “proses di dalamnya sedang berjalan”. ls keluar dari direktori saat ini dan mencantumkan project Compose yang sedang berjalan di host beserta statusnya. Tambahkan -a untuk menyertakan project yang telah dihentikan.

Mendapatkan shell di dalam service

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 menjalankan perintah di dalam container yang sudah aktif. run memulai container baru dari definisi service yang sama. Ini diperlukan jika service tidak bertahan cukup lama untuk menjadi target exec. Selalu pasangkan run dengan --rm. Tanpanya, setiap pemanggilan meninggalkan container yang berhenti, dan container tersebut akan menumpuk hingga docker compose ps -a tidak dapat dibaca.

Coba sh sebelum bash. Beberapa image berbasis Alpine menyertakan bash, termasuk image PostgreSQL Alpine resmi. Jika tidak tersedia, kegagalannya berbunyi exec: "bash": executable file not found in $PATH. Menambahkan --no-deps ke run akan melewati dependensi service. Dengan demikian, pemeriksaan konfigurasi singkat tidak menjalankan seluruh database.

run --rm web env adalah cara tercepat untuk melihat environment yang sebenarnya diterima service setelah setiap file .env, blok environment:, dan variabel shell digabungkan. Jika suatu nilai salah, urutan penggabungan biasanya menjadi penyebabnya. cara Compose menyelesaikan file env dan secret menjelaskan sumber mana yang diprioritaskan.

Jaringan, port, dan resolusi nama

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

Secara default, Compose menempatkan setiap service pada satu network proyek, dan nama setiap service menjadi nama DNS di network tersebut. Menjalankan getent hosts db di dalam web, jika image tersebut menyertakan getent, akan memeriksa resolusi nama; perintah ini tidak menguji apakah db menerima koneksi. Jika nama berhasil di-resolve tetapi koneksi ditolak, periksa apakah server sedang berjalan dan mendengarkan pada alamat serta port yang diminta; binding hanya ke 127.0.0.1 adalah salah satu kemungkinan penyebabnya. Batas yang sama menjelaskan mengapa container yang dijalankan di luar proyek, baik melalui docker run maupun sebagai stack tersendiri, memerlukan shared network agar dapat me-resolve nama service seperti jellyfin. Hal ini merupakan pemeriksaan pertama ketika front end Halcyon untuk library Jellyfin Anda tidak dapat menjangkau server yang dituju. Penjelasan selengkapnya mengenai model tersebut tersedia di cara kerja network Compose dan DNS service.

port web 80 menampilkan alamat host dan port tempat port container dipublikasikan. Ini menghindarkan Anda dari menebak ketika mapping berasal dari sebuah variabel. Publikasi port juga menulis aturan firewall yang dikelola Docker sendiri. Aturan tersebut berada di atas aturan Anda. Akibatnya, service yang Anda anggap privat dapat terbuka ke Internet. Kasus ini dibahas di alasan port Docker yang dipublikasikan melewati ufw. Membiarkan port tersebut tidak dipublikasikan, lalu menempatkan satu proxy yang melakukan autentikasi pada network proyek di depan service, merupakan arsitektur yang lebih aman. Itulah yang diberikan oleh menjalankan Authentik sebagai lapisan single sign-on.

Volume dan data

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

config --volumes menampilkan named volume yang dideklarasikan oleh project, satu per baris. Daftar tersebut hanya merupakan sebagian dari inventaris backup: bind mount dan file konfigurasi juga perlu diperiksa. Jika volume menyimpan data yang tidak dapat digantikan, perintah backup yang tepat sama pentingnya dengan daftarnya. Karena itu, perbandingan PhotoPrism dan Immich menjabarkan perintah dump dan copy yang diperlukan oleh setiap server foto. cp menyalin file ke atau dari container tanpa membuka shell, menggunakan bentuk service:path pada sisi mana pun yang merupakan container.

down -v menghapus named volume yang dideklarasikan, kecuali volume eksternal, serta anonymous volume yang terpasang pada container, bersama dengan container tersebut. Perintah ini tepat untuk membongkar test stack, tetapi tidak tepat untuk apa pun yang menyimpan data penting bagi Anda karena tidak ada konfirmasi dan tidak ada cara untuk membatalkannya. Bind mount tetap ada karena berada pada filesystem host. Perbedaan dalam cakupan dampak ini menjadi salah satu alasan untuk memilih secara sengaja antara bind mount dan named volume.

Pembersihan yang membebaskan ruang disk tanpa kehilangan data

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

--remove-orphans menghapus container yang terkait dengan project tetapi tidak lagi tercantum dalam file. Ini persis yang terjadi setelah Anda mengganti nama service. Tanpa opsi ini, container tersebut tetap berjalan, dan docker compose ps secara default menyertakan orphan yang sedang berjalan.

docker system df menunjukkan penggunaan disk sebelum Anda menghapus apa pun. Perintah ini memisahkan image, container, local volume, dan build cache, serta menampilkan jumlah yang dapat direklamasi untuk masing-masing. image prune -a menghapus setiap image yang tidak digunakan oleh container, baik memiliki tag maupun tidak. Pada server yang telah menarik beberapa versi image berukuran besar, tindakan ini biasanya memberikan penghematan terbesar. builder prune secara default menghapus dangling build cache. Tambahkan -a untuk menghapus semua build cache yang tidak digunakan.

Tidak satu pun dari perintah tersebut menyentuh named volume. docker volume prune --all, docker compose down -v, dan docker volume rm menghapus named volume. docker volume prune tanpa opsi hanya menghapus anonymous volume.

Memeriksa file sebelum menimbulkan masalah

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

config --quiet memvalidasi dan tidak mencetak apa pun jika berhasil. Karena itu, gunakan perintah ini pada tahap pra-deployment atau git hook. config biasa mencetak file yang sudah digabungkan dan diinterpolasi sepenuhnya. Dengan cara ini, Anda dapat memastikan bahwa variabel berhasil di-resolve dan file override diterapkan sesuai harapan. Variabel yang tidak disetel akan muncul sebagai nilai kosong, diikuti peringatan The "X" variable is not set. Defaulting to a blank string.

--dry-run adalah flag global, bukan flag subperintah. Karena itu, letakkan flag ini sebelum up. Perintah ini mencetak semua tindakan yang akan dilakukan Compose tanpa mengubah apa pun. Waktu tiga puluh detik ini layak digunakan sebelum menjalankan down pada stack yang penting.

Bekerja dengan file, profile, dan project

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

Beberapa flag -f digabungkan secara berurutan, dan file yang muncul belakangan menimpa file sebelumnya berdasarkan setiap key. Ini adalah cara standar untuk mempertahankan satu file dasar dengan override kecil untuk production. Namun, aturannya berbeda untuk list dan map. Baca cara Compose menggabungkan beberapa file sebelum menelusuri penyebab hasil yang tidak terduga.

--profile menjalankan service yang diberi profile tersebut bersama service tanpa profile. Dengan demikian, tool debug tidak ikut dijalankan dalam up normal. -p menetapkan nama project, sehingga dua salinan stack yang sama dapat berjalan berdampingan dengan network dan nama volume yang terpisah. Untuk menjalankan kembali stack setelah reboot, gunakan restart policy atau unit yang menjalankan Compose, seperti dijelaskan dalam menjalankan stack Compose saat boot.

FAQ

Apa yang menggantikan docker-compose dengan tanda hubung?

Compose V2 dan V5, yang dipanggil sebagai docker compose dengan spasi. Di Linux, Compose adalah plugin yang diinstal secara terpisah; Ubuntu 24.04 LTS masih menyediakan tool Python V1 di repositori universe. Jika format dengan spasi tidak tersedia, siapkan repositori Docker lalu instal paket docker-compose-plugin. Perbarui skrip lama ke format dengan spasi, bukan dengan menambahkan alias, karena V2 memiliki flag yang tidak tersedia di V1.

Mengapa docker compose restart tidak menerapkan perubahan konfigurasi saya?

restart menghentikan dan menjalankan kembali container yang sudah ada dengan konfigurasi saat container tersebut dibuat, dan tidak pernah membaca ulang compose.yaml. Setiap perubahan pada variabel lingkungan, port, volume, atau tag image memerlukan docker compose up -d, yang membandingkan setiap service dengan container yang sedang berjalan lalu membuat ulang container yang berbeda. Tambahkan --force-recreate jika Anda ingin penggantian tetap dilakukan meskipun tidak ada perubahan pada file.

Bagaimana cara memperbarui service ke image yang lebih baru?

Jalankan docker compose pull, lalu docker compose up -d. Perintah pull mengambil image terbaru untuk setiap tag dalam file, dan up -d membuat ulang service yang ID image-nya tidak lagi cocok dengan container-nya. Menjalankan up -d saja mengikuti kebijakan pull: kebijakan default missing menggunakan kembali image yang tersimpan di cache, kecuali latest, yang selalu di-pull.

Perintah pembersihan mana yang aman pada server aktif?

docker system df melaporkan penggunaan disk tanpa menghapus apa pun; docker image prune -a dan docker builder prune menghapus image serta cache build yang tidak digunakan, sehingga service yang sedang berjalan tetap berfungsi dan named volume tidak tersentuh. Pasangan yang berbahaya adalah docker compose down -v, yang menghapus named volume non-eksternal yang dideklarasikan project serta anonymous volume terpasang tanpa konfirmasi, dan docker volume prune --all, yang menghapus local volume yang tidak digunakan, termasuk named volume, setelah satu prompt y/N atau tanpa prompt sama sekali dengan -f. Jalankan docker compose config --volumes terlebih dahulu agar Anda mengetahui apa yang berisiko dihapus.

Dapatkah saya menjalankan satu perintah tanpa menjalankan seluruh stack?

Ya. docker compose run --rm --no-deps web sh menjalankan satu container dari definisi service web, melewati dependensinya, dan menghapus container saat Anda keluar. Gunakan exec jika container sudah berjalan, karena exec menjalankan perintah Anda di dalam container aktif dan menampilkan kondisi service yang sebenarnya.