Docker Compose down vs stop: Perbedaan dan Dampaknya

Jawaban singkat

docker compose stop menghentikan container dan membiarkannya tetap tersimpan di disk. docker compose down menghentikan container, lalu menghapus container dan network yang dibuat Compose untuk project tersebut. Tidak satu pun dari kedua perintah ini menyentuh named volume. Database Anda hanya akan terhapus jika Anda menambahkan -v, seperti pada docker compose down -v. Opsi ini menghapus named volume yang dideklarasikan di bagian volumes pada file Compose.

Itulah seluruh perbedaannya dalam satu paragraf. Bagian selanjutnya membuktikannya dengan volume Postgres yang dapat Anda pantau tetap ada setelah down dan hilang setelah down -v, serta menjelaskan dua kondisi ketika Anda memerlukan --force-recreate.

docker compose stop: container tetap ada

stop mengirim SIGTERM ke proses utama pada setiap container, menunggu, lalu mengirim SIGKILL jika proses tersebut masih berjalan. Waktu tunggu default adalah 10 detik dan -t mengubahnya. Tidak ada yang dihapus. Container tetap memiliki ID, writable layer, reservasi IP, dan log-nya.

docker compose stop
docker compose ps -a

docker compose ps tanpa argumen hanya menampilkan container yang sedang berjalan. Jadi, setelah stop, perintah tersebut menampilkan tabel kosong dan orang mengira container sudah hilang. ps -a menyertakan container yang berhenti, dan di situlah Anda akan melihat Exited (0) di samping setiap service. Jalankan kembali dengan docker compose start, yang menggunakan kembali container yang sama persis.

Karena container masih ada, semua yang ditulis di dalamnya di luar volume tetap tersimpan. Ini termasuk paket yang Anda instal secara manual dengan docker compose exec dan file konfigurasi yang Anda edit di dalam container. Inilah alasan praktis untuk memilih stop saat melakukan debugging: Anda dapat memulai ulang container dalam kondisi yang sama.

docker compose down: container dan jaringan dihapus

down menghentikan container, lalu menghapusnya beserta jaringan default yang dibuat Compose untuk project tersebut. Dokumentasi Docker menjelaskan bahwa perintah ini menghentikan container serta menghapus container, jaringan, volume, dan image yang dibuat oleh up. Namun, penghapusan volume dan image hanya dilakukan jika Anda memintanya dengan -v dan --rmi.

docker compose down
docker compose ps -a
docker network ls

Setelah down, ps -a tidak menampilkan apa pun untuk project tersebut, dan jaringan <project>_default sudah tidak ada. Nama project diambil dari nama direktori, kecuali Anda menetapkan name: dalam file Compose atau meneruskan -p. Semua perubahan yang Anda buat pada writable layer container kini tidak dapat dipulihkan. Karena itu, anggap down sebagai perintah yang membuang container dan mempertahankan data yang Anda simpan dalam volume.

Jika perintah ini dijalankan di direktori yang salah, Anda akan mendapatkan no configuration file provided: not found. Compose tidak mengetahui project yang dimaksud, sehingga perintah tersebut ditolak. Gunakan docker compose -f /srv/myapp/compose.yaml down jika Anda tidak berada di folder project.

Apakah docker compose down menghapus volume saya?

Tidak. Named volume yang dideklarasikan di bawah key tingkat atas volumes tetap ada setelah down selesai, dan tetap ada setelah container yang menggunakannya dihapus. Kekhawatiran ini paling sering muncul terkait perintah tersebut. Jawabannya tetap sama pada Compose v2.

Siapkan stack untuk pengujian. Simpan konfigurasi berikut di compose.yaml dalam direktori kosong bernama voltest.

services:
  db:
    image: postgres:16.4
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Jalankan stack tersebut, lalu tulis satu baris yang dapat Anda kenali nanti.

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "create table marker (note text);"
docker compose exec -T db psql -U postgres -c "insert into marker values ('survived');"

Sekarang hapus container dan periksa volume tersebut.

docker compose down
docker volume ls

Output tetap mencantumkan voltest_pgdata. Container sudah tidak ada, tetapi datanya tetap ada. Jalankan kembali stack tersebut dan baca barisnya.

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "select * from marker;"

Anda mendapatkan satu baris yang berisi survived. Container baru tersebut berbeda dari container sebelumnya dan memiliki ID yang berbeda, tetapi terhubung ke volume yang sama. Untuk gambaran yang lebih luas, panduan dasar Compose membahas named volume dibandingkan bind mount serta lokasi sebenarnya masing-masing pada host.

Apa yang sebenarnya dihapus oleh down -v

-v (bentuk panjang --volumes) menghapus volume bernama yang dideklarasikan dalam bagian volumes pada file Compose, serta volume anonim yang terpasang pada container. Jalankan perintah ini pada stack yang sama.

docker compose down -v
docker volume ls

voltest_pgdata tidak lagi tercantum. Jalankan stack kembali. Entry point Postgres menemukan direktori data yang kosong, lalu menginisialisasi cluster baru. Log container menyatakannya dengan jelas.

The files belonging to this database system will be owned by user "postgres".
PostgreSQL init process complete; ready for start up.

Jika blok tersebut muncul pada stack yang telah berjalan selama berbulan-bulan, berarti volume telah dihapus. Tabel marker Anda sudah hilang. Satu-satunya cara untuk memulihkannya adalah dari backup.

Beberapa penyimpanan tidak pernah dihapus oleh -v. Bind mount adalah path pada host, sehingga Docker hanya melepas mount tersebut dan file Anda tetap berada di tempatnya. Volume yang ditandai external: true dideklarasikan sebagai milik sesuatu di luar project ini, sehingga Compose tidak pernah menghapusnya. Volume bernama yang Anda hapus dari file Compose sebelum menjalankan down -v tidak lagi dideklarasikan. Compose tidak mengetahui bahwa volume tersebut harus dihapus, sehingga volume itu tertinggal sebagai orphan selama docker volume prune.

Kasus terakhir ini sering terjadi saat refactor. Hapus sebuah service dan volumenya dari file, lalu jalankan down -v. Volume tersebut tetap ada karena file tidak lagi menyebutkannya. Jalankan down -v sebelum mengedit file, bukan setelahnya.

Kapan Anda benar-benar perlu menggunakan --force-recreate

docker compose up -d tidak membangun ulang semuanya setiap kali dijalankan. Compose menyimpan hash konfigurasi setiap service yang telah di-resolve sebagai label pada container. Jika hash dan ID image sama, container dibiarkan dan Anda mendapatkan Container voltest-db-1 Running, bukan Recreated. Inilah perilaku yang hampir selalu diinginkan, karena membuat up -d aman dijalankan berulang kali.

Hal ini juga menjelaskan mengapa beberapa perubahan tampak tidak berpengaruh. Compose menghitung hash definisi service yang telah di-resolve, bukan isi file yang dirujuk oleh definisi tersebut. File konfigurasi yang di-mount ke dalam container dan dibaca satu kali saat startup tidak akan memicu pembuatan ulang ketika Anda mengeditnya, karena path mount tidak berubah. Service tetap berjalan dengan nilai yang dibacanya saat boot.

docker compose up -d --force-recreate

Perintah tersebut menghentikan dan menghapus setiap container, lalu membuat container baru dari definisi yang sama. Gunakan setelah mengedit file konfigurasi yang di-mount, atau ketika container mengalami perubahan kondisi yang tidak dapat Anda jelaskan. Volume tidak terpengaruh, sehingga database tetap ada setelah force recreate. Untuk mengambil image yang lebih baru dengan tag yang sama, Anda juga perlu melakukan pull.

docker compose pull
docker compose up -d

pull mengambil ID image baru, lalu up -d mendeteksi bahwa ID image tersebut berbeda dari container yang sedang berjalan dan membuat ulang container secara otomatis. Menambahkan --force-recreate tanpa pull hanya menghasilkan container baru dari image lama yang sama. Karena itu, keluhan "Saya sudah melakukan force recreate, tetapi versinya masih lama" sangat umum terjadi.

docker compose restart tidak melakukan semua itu. Perintah tersebut hanya me-restart container yang sudah ada dan sama sekali tidak membaca ulang file Compose. Karena itu, perubahan environment variable atau port mapping tidak akan diterapkan. Jika Anda mengedit file tersebut, gunakan up -d.

Model mental yang perlu diingat

Container dapat diganti. Container adalah proses dengan lapisan yang dapat ditulis dan tipis. Compose dapat membuat container yang identik dari file tersebut dalam waktu sekitar satu detik. Volume tidak dapat diganti karena menyimpan satu-satunya salinan state yang tidak dapat dibuat ulang oleh file apa pun dalam repositori Anda.

Setiap verb Compose sesuai dengan pemisahan tersebut. stop dan start mempertahankan container. down dan up mengganti container, tetapi mempertahankan volume. down -v adalah satu-satunya perintah rutin yang menghapus state. Karena itu, perintah tersebut memerlukan flag eksplisit. Sebelum mengetikkannya pada sistem yang digunakan, pastikan Anda memiliki backup yang sudah pernah dipulihkan setidaknya satu kali.

Logika yang sama berlaku untuk secret. Password yang ditetapkan melalui POSTGRES_PASSWORD hanya dibaca saat database melakukan inisialisasi pertama. Jadi, mengubahnya dalam file environment lalu menjalankan up -d menghasilkan password authentication failed for user "postgres". Container tersebut baru, tetapi volumenya lama. Volume lama itu masih menyimpan password lama. Cara Compose menyelesaikan file environment dan secret menjelaskan layer mana yang berlaku jika variabel yang sama ditetapkan dua kali.

Mode kegagalan dan string yang akan Anda lihat

no configuration file provided: not found berarti Compose dijalankan di direktori yang tidak memiliki compose.yaml maupun docker-compose.yml. Teruskan -f dengan path lengkap.

network voltest_default has active endpoints pada down berarti ada container di luar project yang terhubung ke network project tersebut. Biasanya container itu dijalankan secara manual dengan docker run --network. Hapus container tersebut, lalu jalankan down lagi.

Found orphan containers ([voltest-old-1]) for this project muncul setelah Anda mengganti nama atau menghapus service. Container lama masih menyimpan label project. docker compose down --remove-orphans menghapusnya, dan aman dijalankan pada stack yang sehat.

Error response from daemon: remove voltest_pgdata: volume is in use pada docker volume rm manual berarti masih ada container yang mereferensikan volume tersebut, termasuk container yang sudah berhenti. Jalankan docker compose down terlebih dahulu, lalu hapus volume tersebut, atau langsung gunakan down -v. Pada project yang lebih besar, stack Compose multi-service menunjukkan jumlah volume yang dapat dikumpulkan oleh satu project.

FAQ

Apakah docker compose down menghapus database saya?

Tidak, jika database berada dalam named volume atau bind mount. down menghapus container dan network project, sedangkan volume tetap berada di disk beserta datanya. docker compose up -d berikutnya memasang container baru ke volume yang sama, sehingga data tetap tersedia. Hanya docker compose down -v yang menghapus named volume, dan hanya volume yang dideklarasikan pada bagian volumes dalam file Compose.

Apa perbedaan stop dan down untuk container yang ingin saya gunakan kembali?

stop mempertahankan container, sehingga docker compose start mengembalikan Anda ke container yang sama dengan writable layer yang sama. Apa pun yang Anda instal atau ubah secara manual di dalam container tetap ada. down menghapus container, sehingga up -d berikutnya membuat container baru dari image dan perubahan manual tersebut hilang. Saat melakukan debugging, gunakan stop.

Bagaimana cara menghapus semua yang dibuat oleh project Compose?

docker compose down -v --rmi all --remove-orphans menghapus container, network project, named volume yang dideklarasikan dalam file, image yang digunakan oleh service, dan setiap container yang masih memiliki label nama project. Perintah ini tidak menyentuh bind mount atau volume yang ditandai external: true. Periksa hal-hal yang akan dihapus dengan docker volume ls sebelum menjalankannya.

Mengapa container saya mengabaikan perubahan pada file konfigurasi yang di-mount?

Compose menentukan apakah container perlu dibuat ulang dengan membandingkan hash dari definisi service yang telah diselesaikan. Hash tersebut tidak mencakup isi file yang di-mount. Path tidak berubah, sehingga Compose membiarkan container tetap berjalan dengan nilai yang dibaca saat startup. Jalankan docker compose up -d --force-recreate untuk membuat container baru yang membaca file tersebut kembali.

Mengapa POSTGRES_PASSWORD baru saya tidak berfungsi setelah diubah?

Image Postgres hanya membaca POSTGRES_PASSWORD saat menginisialisasi direktori data yang kosong. Volume Anda sudah berisi cluster yang diinisialisasi, sehingga variabel tersebut diabaikan dan password lama tetap berlaku. Anda akan melihat password authentication failed for user "postgres". Ubah password dengan ALTER USER di dalam database yang sedang berjalan, atau terima kehilangan data dan mulai dari awal dengan docker compose down -v.