Menyiapkan infrastruktur lokal secara manual seperti database dan cache sering kali menimbulkan friksi dalam alur kerja pengembangan. Developer harus menjalankan perintah docker compose up -d secara terpisah, memastikan port tidak bentrok, lalu menyalin kredensial koneksi ke dalam application.properties. Inkonsistensi konfigurasi antar anggota tim menjadi masalah yang umum terjadi.

Mulai Spring Boot 3.1, modul spring-boot-docker-compose menyediakan integrasi langsung antara siklus hidup aplikasi Spring Boot dengan Docker Compose. Modul ini mendeteksi berkas compose di direktori proyek, menyalakan container secara otomatis saat aplikasi dijalankan, menginjeksi properti koneksi ke ApplicationContext tanpa konfigurasi manual, dan mematikan container saat aplikasi berhenti.

Konfigurasi Build Tool: Mencegah Leakage ke Production

Modul Docker Compose ditujukan khusus untuk fase development. Membawa pustaka ini ke dalam berkas production JAR dapat menyebabkan kegagalan startup bila host production tidak menyediakan socket Docker aktif atau jika aplikasi mencoba menjalankan orchestration secara tidak sengaja.

Gunakan scope dependensi development agar artifact build akhir tetap bersih.

Gradle

dependencies {
    developmentOnly("org.springframework.boot:spring-boot-docker-compose")
}

Maven

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-docker-compose</artifactId>
    <optional>true</optional>
</dependency>

Penggunaan konfigurasi developmentOnly di Gradle atau <optional>true</optional> di Maven menjamin bahwa modul tidak akan disertakan ketika perintah bootJar atau package production dijalankan.

Menyusun compose.yaml dengan Healthcheck

Letakkan berkas compose.yaml (atau docker-compose.yaml) pada root folder proyek Anda. Spring Boot secara default mencari berkas di direktori kerja root saat runtime.

Spring Boot Docker Compose membaca kesiapan container sebelum ApplicationContext diinisialisasi secara penuh. Menambahkan blok healthcheck pada setiap service mencegah terjadinya race condition di mana Spring Boot mencoba membuat connection pool saat database belum siap menerima koneksi TCP.

services:
  postgres:
    image: 'postgres:16-alpine'
    environment:
      POSTGRES_DB: 'app_db'
      POSTGRES_USER: 'app_user'
      POSTGRES_PASSWORD: 'secretpassword'
    ports:
      - '5432:5432'
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app_user -d app_db"]
      interval: 3s
      timeout: 3s
      retries: 5

  redis:
    image: 'redis:7-alpine'
    ports:
      - '6379:6379'
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 3s
      timeout: 3s
      retries: 5

volumes:
  pgdata:

Injeksi Properti Otomatis via Service Connection

Keunggulan utama modul ini adalah kemampuan Service Connection otomatis. Ketika menggunakan official image seperti postgres, redis, mysql, atau rabbitmq, Spring Boot mendeteksi jenis service dari container metadata dan port yang terbuka.

Properti koneksi standar berikut diabaikan karena Spring Boot akan mengisinya secara dinamis saat runtime:

  • spring.datasource.url
  • spring.datasource.username
  • spring.datasource.password
  • spring.data.redis.host
  • spring.data.redis.port

Jika menggunakan custom image atau nama image internal registry yang tidak standar, definisikan label Docker Compose agar Spring Boot dapat mengenali tipe adapter yang harus diterapkan:

services:
  custom-pg:
    image: 'myregistry.internal/custom-postgres:latest'
    labels:
      org.springframework.boot.service-connection: postgres

Label ini setara dengan anotasi @ServiceConnection pada Testcontainers, memastikan pencocokan factory bean connection yang tepat tanpa konfigurasi manual.

Manajemen Siklus Hidup Container

Perilaku modul saat aplikasi dimulai dan ditutup dikendalikan melalui properti spring.docker.compose.lifecycle-management di application.properties atau application.yml:

# Pilihan: none, start-only, start-and-stop (default)
spring.docker.compose.lifecycle-management=start-only
  • start-and-stop: Menjalankan docker compose up saat aplikasi boot dan mengeksekusi docker compose stop saat Spring ApplicationContext ditutup. Opsi ini ideal jika Anda ingin membersihkan resource sistem secara otomatis.
  • start-only: Menyalakan container jika belum aktif, tetapi membiarkannya tetap berjalan ketika aplikasi dimatikan. Opsi ini mempercepat restart berulang selama siklus debugging karena container tidak perlu diinisialisasi ulang dari nol.
  • none: Menonaktifkan orkestrasi lifecycle tetapi tetap membaca metadata service connection untuk container yang telah berjalan.

Penanganan Readiness dan Timeout

Secara default, Spring Boot menunggu seluruh container mencapai status healthy (jika healthcheck tersedia) atau running. Perilaku ini dapat disesuaikan:

# Mengatur batas waktu tunggu kesiapan container (default: 2 menit)
spring.docker.compose.readiness.timeout=45s

# Memilih status yang ditunggu: healthy, running (default: healthy jika terdefinisi)
spring.docker.compose.readiness.wait=healthy

Isolasi Environment dan CI/CD

Pada pipeline Continuous Integration (CI) atau lingkungan staging di mana dependensi disediakan melalui external mock atau container terpisah, nonaktifkan modul sepenuhnya dengan menambahkan environment variable:

export SPRING_DOCKER_COMPOSE_ENABLED=false

Atau deklarasikan pada profil spesifik:

spring.docker.compose.enabled=false

Troubleshooting dan Masalah Umum

  • Port Collision: Jika port 5432 atau 6379 telah digunakan oleh proses lokal di host, container akan gagal melakukan bind port. Solusi: Ubah port mapping di compose.yaml menjadi port acak atau non-standar (misalnya '15432:5432'). Spring Boot Service Connection tetap membaca port target secara benar dari mapping Docker.
  • Koneksi Gagal Saat Startup: Hal ini umumnya terjadi karena container belum sepenuhnya siap melayani request meskipun statusnya sudah running. Selalu deklarasikan blok healthcheck pada file compose untuk database.
  • Multi-Compose Files: Jika memiliki berkas di lokasi khusus, tentukan lokasinya menggunakan properti: spring.docker.compose.file=./docker/dev-compose.yaml.