Membangun Image
Dockerfile, Multi-stage & Entrypoint

FROM sampai CMD, build context, dan .dockerignore

Dockerfile adalah resep deklaratif: deretan instruksi yang Docker eksekusi dari atas ke bawah untuk merakit sebuah image.

Setiap instruksi menambah satu layer (ingat Chapter 1), dan urutannya bukan sekadar gaya, ia menentukan seberapa sering cache build kamu meleset. Mari kenali instruksi inti lebih dulu, lalu bahas kenapa urutan itu penting.

Saat kamu menjalankan docker build ., titik di akhir itu adalah build context: seluruh isi folder tersebut di-paket dan dikirim ke daemon Docker sebelum build dimulai. Kalau folder itu berisi .git, node_modules, atau binary lokal berukuran ratusan MB, semuanya ikut terkirim, build jadi lambat dan ada risiko file rahasia (seperti .env) bocor masuk ke image.

flowchart LR
  A[Folder proyek] -->|paket build context| B[Docker daemon]
  B -->|baca Dockerfile| C[Rakit layer]
  C --> D[Image jadi]
  E[.dockerignore] -.->|saring sebelum kirim| A

Build context dikirim ke daemon. .dockerignore menyaring file sebelum apa pun dikirim, jadi konteks tetap ramping.

Solusinya .dockerignore: daftar pola file yang tidak ikut dikirim sebagai build context. Polanya mirip .gitignore, tapi tujuannya berbeda.

.dockerignoreSalin
.git
node_modules
*.env
.env
dist/
tmp/
skincare-backend          # binary hasil build lokal
Dockerfile
.dockerignore

Sekarang resep paling sederhana untuk API Go kita, satu tahap (multi-stage menyusul di section berikutnya). Perhatikan urutan COPY-nya.

DockerfileSalin
FROM golang:1.26
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o /skincare-api ./cmd/server
EXPOSE 8080
CMD ["/skincare-api"]

Kenapa go.mod dan go.sum disalin lebih dulu, terpisah dari COPY . .? Karena cache. Docker meng-cache setiap layer berdasarkan input instruksinya. Layer RUN go mod download hanya akan di-build ulang bila go.mod/go.sum berubah. Selama dependency tetap, mengubah satu file handler di internal/product/ tidak membatalkan cache download dependency, build berikutnya lompat langsung ke go build. Kalau kamu menulis COPY . . sebelum go mod download, perubahan kode apa pun akan membuang cache dependency dan mengunduh ulang semua modul tiap build.

Resep di atas berfungsi, tapi ada satu masalah serius: image yang dihasilkan gemuk. Mari perbaiki itu.

Image kecil: pisahkan tahap compile dan runtime

Multi-stage build memisahkan tahap meng-compile dari tahap menjalankan, sehingga toolchain Go yang berat tidak pernah ikut ke image produksi.

Image single-stage tadi berfungsi, tapi gemuk: berbasis golang:1.26 ia bisa mencapai sekitar satu gigabyte karena membawa compiler Go, git, header C, dan ratusan MB tooling yang hanya berguna saat build, sama sekali tidak dibutuhkan untuk menjalankan binary yang sudah jadi. Membawa semua itu ke produksi berarti image besar (lambat di-pull, lambat deploy) dan permukaan serangan yang luas (makin banyak paket, makin banyak CVE potensial).

Ide multi-stage: pakai satu stage golang untuk compile, lalu mulai stage runtime baru dari image super-minimal dan COPY --from hanya binary-nya. Semua isi stage build (compiler, source, cache) ditinggal dan tidak ikut ke image akhir. Hasilnya dramatis: image yang tadinya sekitar 1 GB bisa turun ke kisaran belasan MB.

flowchart LR
  subgraph S1[Stage build: golang:1.26]
    A[go mod download] --> B[go build CGO_ENABLED=0]
    B --> C[/skincare-api binary/]
  end
  C -->|COPY --from=build| D
  subgraph S2[Stage runtime: distroless static]
    D[/api/] --> E[Image kecil, non-root]
  end

Dua tahap, satu artifact. Hanya binary yang menyeberang dari stage build ke stage runtime.

Berikut Dockerfile multi-stage untuk skincare-api kita. Modul Go memakai github.com/kamu/skincare-backend.

DockerfileSalin
# --- build ---
FROM golang:1.26 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/api ./cmd/server

# --- runtime ---
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /app/api /api
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/api"]

Dua detail krusial di stage build. CGO_ENABLED=0 mematikan linking ke pustaka C, sehingga Go menghasilkan binary statis yang tidak bergantung pada glibc apa pun, syarat agar bisa berjalan di image kosong seperti distroless static atau scratch. Flag -ldflags="-s -w" membuang tabel simbol dan info debug, memangkas ukuran binary tanpa mengubah perilakunya.

Untuk runtime kita pakai gcr.io/distroless/static-debian12 dengan tag :nonroot. Distroless adalah image yang hanya berisi runtime minimal: tidak ada shell, tidak ada package manager, tidak ada bin/sh. Image static distroless sendiri hanya sekitar 2 MB; ditambah binary Go-mu, image akhir tipikalnya berkisar 12 sampai 15 MB, dibanding hampir 1 GB versi single-stage. USER nonroot:nonroot membuat proses berjalan sebagai user tak-berhak, sehingga andai ada celah di aplikasi, penyerang tidak otomatis jadi root di dalam container.

Memilih base image runtime

Distroless bukan satu-satunya pilihan. Tiga base yang paling sering dipakai untuk biner Go statis berbeda pada satu sumbu: seberapa banyak yang ikut, dan apakah ada shell untuk debugging.

Mari buktikan pemangkasan ukurannya dengan tanganmu sendiri.

Image sudah kecil dan aman. Tapi ada satu pertanyaan yang belum dijawab: saat container dijalankan, proses apa yang menjadi PID 1, dan apa ia berhenti dengan benar?

Menentukan proses default container dengan benar

CMD dan ENTRYPOINT sama-sama menetapkan proses default, tapi keduanya menjawab pertanyaan yang berbeda: “apa yang dijalankan” versus “ini memang program apa”.

Sebuah image perlu tahu satu hal saat docker run dipanggil tanpa argumen: perintah apa yang menjadi proses pertama di dalam container. Di Go, jawabannya hampir selalu binary tunggal hasil build, misalnya server API skincare. Dua instruksi mengatur ini, dan memilih yang tepat menentukan apakah container kamu mau berhenti dengan rapi saat di-deploy ulang.

Pola paling kokoh untuk service Go: pakai ENTRYPOINT untuk binary dan CMD untuk argumen default. ENTRYPOINT mengunci “ini server”, sementara CMD memberi flag default yang masih bisa diganti tanpa menyentuh binary-nya.

DockerfileSalin
ENTRYPOINT ["/api"]
CMD ["--http-addr=:8080"]

Dengan kombinasi di atas, docker run img menjalankan /api --http-addr=:8080. Sementara docker run img --http-addr=:9090 menjalankan /api --http-addr=:9090: binary tetap, hanya argumennya yang ditimpa. Inilah yang membuat satu image bisa dipakai untuk port berbeda tanpa rebuild.

Yang krusial adalah perbedaan exec form dan shell form. Exec form (array JSON, ["/api"]) menjalankan binary secara langsung sebagai PID 1. Shell form (string, "/api") diam-diam dibungkus menjadi /bin/sh -c "/api", sehingga PID 1 adalah sh, dan binary Go kamu hanya anak proses.

flowchart TB
  subgraph exec["Exec form: ENTRYPOINT ["/api"]"]
    K1[Kernel] -->|SIGTERM| P1["PID 1 = /api"]
    P1 -->|graceful shutdown| OK[Tutup koneksi, drain]
  end
  subgraph shell["Shell form: ENTRYPOINT "/api""]
    K2[Kernel] -->|SIGTERM| S1["PID 1 = /bin/sh"]
    S1 -.->|sinyal tidak diteruskan| P2["/api anak proses"]
    P2 -.->|tidak tahu mau stop| KILL["dipaksa SIGKILL setelah timeout"]
  end

Jalur sinyal SIGTERM. Hanya exec form yang menjadikan binary Go sebagai PID 1, sehingga ia menerima sinyal stop dan bisa shutdown bersih.

Kenapa ini penting di produksi? Saat orchestrator (Compose, Kubernetes, ECS) ingin menghentikan container, misalnya selama rolling deploy versi baru, ia mengirim SIGTERM ke PID 1, menunggu beberapa detik, lalu SIGKILL paksa bila belum mati. Server Go yang baik menangkap SIGTERM untuk menghentikan terima request baru, menyelesaikan request yang sedang jalan, lalu menutup koneksi database. Itu semua hanya terjadi bila SIGTERM benar-benar sampai ke binary kamu, dan itulah yang membedakan deploy mulus tanpa request terputus dari deploy yang memutus transaksi checkout pelanggan di tengah jalan.

cmd/server/main.goSalin
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()

go func() {
	if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
		log.Fatalf("listen: %v", err)
	}
}()

<-ctx.Done() // SIGTERM tiba di sini (hanya jika binary PID 1)
shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
_ = srv.Shutdown(shutdownCtx)

Image Go yang kecil, aman, dan berperilaku benar

Chapter ini mengubah biner Go menjadi image produksi: resep yang sadar cache, ramping lewat multi-stage, dan berhenti dengan rapi lewat ENTRYPOINT exec-form.

Kita mulai dari Dockerfile sebagai resep berlapis, dengan dua trik kunci: .dockerignore menjaga build context ramping dan bebas secret, dan urutan COPY go.mod go.sum sebelum COPY . . menjaga cache dependency tetap awet. Lalu multi-stage memisahkan toolchain build dari runtime, memangkas image dari sekitar 1 GB ke belasan MB lewat CGO_ENABLED=0 plus base distroless static non-root. Terakhir, ENTRYPOINT exec-form memastikan binary Go menjadi PID 1, sehingga SIGTERM sampai dan graceful shutdown bekerja saat deploy ulang.

Image sudah jadi dan berperilaku benar. Tapi image yang sama harus bisa jalan beda config di tiap lingkungan, menyambung ke service lain, dan menyimpan data yang bertahan. Itu fokus Chapter 3: environment variable, networking, dan volume.