Service dan Image

Setiap service pada compose.yaml, yaitu deskripsi satu kelompok container, harus memiliki sumber container yang jelas: dibangun dari Dockerfile atau ditarik dari sebuah image. Topik ini membahas dua kunci asal tersebut beserta compose.yaml lengkap aplikasi catatan dengan basis data PostgreSQL-nya. Pembahasan juga mencakup perintah compose utama untuk mengelola siklus hidup proyek (project), yaitu kesatuan container dari satu compose.yaml, serta perbedaan antara menghentikan dan menghapusnya. Setelah membacanya, aplikasi web dan basis datanya dapat dihidupkan, diamati, dan dibersihkan dengan perintah yang konsisten tanpa mengetik ulang opsi apa pun.

Dua asal container pada service#

Kunci build: menetapkan bahwa container service dibangun dari Dockerfile. Nilainya berupa build context, yaitu direktori yang dikirimkan Compose ke daemon, proses latar yang mengeksekusi pekerjaan Docker, saat proses build berlangsung. Pada build: ., titik menunjuk direktori tempat compose.yaml berada. Compose mencari Dockerfile pada context itu, mengeksekusi instruksinya, lalu menjalankan container dari image hasil pembangunan. Kunci image: menetapkan jalur yang lain: Compose menarik image yang disebut dari registry, tempat penyimpanan image seperti Docker Hub, bila image itu belum ada di mesin, lalu menjalankan container darinya.

Kedua kunci itu tidak boleh dianggap saling menggantikan, karena keduanya menjawab pertanyaan yang sama dengan cara yang berbeda. Service aplikasi yang kodenya disunting setiap hari cocok memakai build:, sedangkan service pihak ketiga seperti postgres:18-alpine cocok memakai image:. Apabila satu service menuliskan keduanya sekaligus, kunci image: memberi nama bagi image hasil build, seperti berikut.

services:
  web:
    build: .
    image: aplikasi-catatan:lokal

Bentuk di atas membuat image hasil build bertanda aplikasi-catatan:lokal, sehingga image itu dapat dirujuk, dipindahkan, atau didorong ke registry tanpa alat tambahan. Tanpa kunci image:, image hasil build tetap terbentuk, tetapi namanya ditentukan Compose secara otomatis dan kurang mudah dirujuk di luar proyek.

compose.yaml lengkap aplikasi catatan#

Berkas berikut menggabungkan kedua pola asal container pada satu proyek. Service web dibangun dari Dockerfile aplikasi catatan yang berbasis python:3.12-slim, sedangkan service db langsung memakai image resmi PostgreSQL. Kedua service diberi nama web dan db, dan nama itulah yang dipakai Compose untuk menamai container, menjadi nama yang dihubungi antar-container, serta menjadi patokan setiap perintah compose.

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgres://postgres:rahasia-db@db:5432/catatan
    restart: unless-stopped
  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_PASSWORD: rahasia-db
      POSTGRES_DB: catatan
    restart: unless-stopped

Service web memetakan port 8000 ke host, yaitu mesin tempat Docker berjalan, dan membawa DATABASE_URL yang mengarah ke db:5432, yaitu service basis data pada port bawaan PostgreSQL. Service db membawa dua variabel inisialisasi: POSTGRES_PASSWORD wajib diisi karena image PostgreSQL menolak berjalan tanpanya, sedangkan POSTGRES_DB memerintahkan pembuatan basis data bernama catatan pada container pertama. Kunci restart: unless-stopped pada kedua service menerapkan kebijakan pemulihan yang sama dengan opsi --restart pada docker run, sehingga container yang berhenti karena error dihidupkan ulang secara otomatis. Direktori proyek pada keadaan ini memuat tiga berkas, yaitu compose.yaml, Dockerfile, dan app.py, dengan compose.yaml sebagai satu-satunya tempat keputusan penjalanan dinyatakan.

Perintah compose utama#

Semua perintah compose dijalankan dari dalam direktori proyek, karena Compose mencari compose.yaml pada direktori saat itu. Perintah-perintah berikut mencakup kebutuhan sehari-hari, mulai dari menghidupkan proyek hingga mengamatinya.

# tidak-dijalankan: daemon Docker tidak tersedia di sandbox
# menghidupkan seluruh service proyek di latar belakang
docker compose up -d
# membangun ulang image service web sebelum menghidupkan proyek
docker compose up -d --build
# menampilkan daftar container milik proyek
docker compose ps
# mengikuti gabungan log seluruh service
docker compose logs -f

Perintah docker compose up -d membuat container yang belum ada, membuat jaringan proyek, lalu memulainya, sedangkan opsi -d melepasnya ke latar belakang. Opsi --build menyuruh Compose membangun ulang image service bertanda build: terlebih dahulu, sehingga perubahan kode ikut masuk ke container. docker compose ps menampilkan tabel berisi container milik proyek saja, lengkap dengan status dan port yang dipublikasikan, dan namanya berpola aplikasi-catatan-web-1. docker compose logs -f menggabungkan log seluruh service dalam satu aliran yang terus mengikuti keluaran terbaru, sehingga perilaku web dan db dapat diamati sekaligus dari satu layar.

docker compose stop dan docker compose start berpasangan untuk jeda sementara, misalnya saat mesin akan direstart. Container beserta seluruh konfigurasinya tetap ada, sehingga docker compose start menghidupkan kembali container yang sama tanpa membuat apa pun.

Menghapus proyek dengan down#

Perintah docker compose down menghentikan proyek lalu menghapus sebagian sumber dayanya. Yang dihapus adalah container dan jaringan proyek, sedangkan volume proyek, yaitu penyimpanan yang dikelola Docker, tetap utuh di host. Sifat ini menjadikan down aman untuk pekerjaan rutin, karena data basis data tidak terhapus dan akan dipakai lagi oleh container pengganti pada up berikutnya. Setelah down, perintah up berikutnya membangun ulang kelompok yang sama dari nol dengan container dan jaringan baru, sedangkan volume yang bertahan membuat basis data langsung terisi seperti sebelumnya.

# tidak-dijalankan: daemon Docker tidak tersedia di sandbox
# menghapus container dan jaringan, volume proyek tetap bertahan
docker compose down
# menghapus volume proyek juga, termasuk seluruh datanya
docker compose down -v

Opsi -v mengubah cakupan penghapusan tersebut: volume bernama milik proyek ikut dihapus dari host. Perintah ini berguna saat proyek benar-benar dibongkar atau saat basis data perlu diinisialisasi ulang dari nol, misalnya untuk menguji skrip migrasi pertama.

Kesalahan umum#

1. Menyunting kode tanpa membangun ulang image. docker compose up -d memakai image yang sudah ada, sehingga container tetap menjalankan versi kode lama tanpa pesan error apa pun. Perbaikannya dengan menjalankan docker compose up -d --build setiap kali kode service bertanda build: berubah.

2. Menjalankan compose dari direktori yang salah. Compose mencari compose.yaml pada direktori saat ini, sehingga perintah yang dijalankan di luar direktori proyek berakhir dengan error konfigurasi tidak ditemukan. Perbaikannya dengan masuk ke direktori proyek terlebih dahulu, atau menunjuk berkasnya secara eksplisit dengan opsi -f.

3. Mengira down menghapus data basis data. Volume proyek bertahan setelah down, sehingga kekhawatiran data hilang pada perintah itu tidak berdasar. Yang benar-benar menghapus volume adalah down -v, sehingga kedua perintah ini dibedakan dengan sengaja.

Ringkasan#

• Service memilih dua asal container: kunci build: membangun image dari Dockerfile pada build context, sedangkan kunci image: menarik image dari registry.
• docker compose up -d menghidupkan seluruh service sekaligus, dan opsi --build wajib ditambahkan bila image perlu dibangun ulang dari kode terbaru.
• docker compose ps dan docker compose logs -f mengamati proyek pada lingkup proyeknya, bukan seluruh container di host.
• down menghapus container dan jaringan proyek sambil menyimpan volume, sedangkan down -v ikut menghapus volume proyek beserta datanya.

Referensi#

• Services — Docker Docs — Rujukan kunci tingkat service seperti build:, image:, ports:, dan restart:.
• docker compose CLI — Docker Docs — Rujukan subperintah compose seperti up, ps, logs, stop, dan down.