Containerize Go API
dengan Docker

Dari binary lokal menuju artefak deployment yang konsisten

Di React kamu mengirim bundle statis ke CDN. Di Laravel kamu mengirim source code plus PHP-FPM, Composer, extension, dan web server. Di Go, kita mengirim satu binary statis di dalam container ukuran beberapa megabita.

Go meng-compile ke binary native tanpa runtime eksternal. Itu membuat Dockerfile Go jauh lebih ringkas daripada setup PHP-FPM atau Node, karena container final tidak perlu membawa compiler Go, source code, package manager, atau toolchain build. Untuk backend skincare, image inilah yang nanti dipakai CI untuk testing, dipush ke registry, dijalankan di staging, lalu dipromosikan ke AWS ECS Fargate tanpa rebuild.

Docker dipakai bukan karena Go tidak bisa dijalankan langsung, tapi karena deployment butuh artefak yang konsisten dan portabel. Image yang sama bisa dites di laptop, dijalankan di CI, dipush ke ECR, lalu dipakai ECS. Yang berubah antar environment hanya environment variable, bukan binary-nya.

Image adalah template berlapis, container adalah proses yang berjalan

Kalau kamu terbiasa dengan frontend build, image mirip artefak hasil build, dan container adalah artefak itu saat dijalankan sebagai proses sistem operasi.

Bagi developer JS/PHP, perbedaan terbesar ada di image final. Image Node dan PHP biasanya identik antara build-time dan runtime: interpreter yang dipakai untuk menjalankan kode tetap harus ada di production. Go memutus rantai itu. Build butuh compiler 800+ MB, tapi production hanya butuh hasilnya, satu binary.

flowchart LR
  subgraph BUILD["Build-time (dibuang)"]
    SRC["Source code Go"] --> TOOL["golang:1.26 (~800 MB)"]
    TOOL --> COMP["go build"]
  end
  COMP --> BIN["binary /app"]
  subgraph FINAL["Image final (~2 MB)"]
    BIN --> BASE["distroless/static + binary"]
  end
  BASE --> RUN["docker run -> container proses /app"]

Gambar 1. Multi-stage memisahkan dapur build (besar, berisi toolchain) dari ruang makan production (kecil, hanya binary). Stage builder dibuang dari image final.

Satu binary, beberapa subperintah: serve, worker, migrate, healthcheck

Dockerfile yang baik dimulai dari struktur proyek yang stabil. Sebelum menulis Dockerfile, kita tata dulu agar satu binary bisa menjadi API maupun worker.

Daripada membuat dua binary terpisah (cmd/api dan cmd/worker) yang masing-masing butuh image, kita pakai satu binary dengan subperintah. Pola ini umum di Go dan membuat image final tunggal yang bisa dipakai ulang. Argumen pertama menentukan mode.

cmd/app/main.goSalin
package main

import (
	"context"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"
)

func main() {
	cmd := "serve"
	if len(os.Args) > 1 {
		cmd = os.Args[1]
	}

	switch cmd {
	case "serve":
		runServer()
	case "worker":
		runWorker()
	case "healthcheck":
		runHealthcheck()
	default:
		slog.Error("perintah tidak dikenal", slog.String("cmd", cmd))
		os.Exit(2)
	}
}

func runServer() {
	addr := getenv("HTTP_ADDR", ":8080")

	mux := http.NewServeMux()
	mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
	})

	server := &http.Server{
		Addr:              addr,
		Handler:           mux,
		ReadHeaderTimeout: 5 * time.Second,
	}

	// Graceful shutdown saat container menerima SIGTERM dari Docker / ECS.
	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()

	go func() {
		slog.Info("skincare API listening", slog.String("addr", addr))
		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
			slog.Error("server stopped", slog.Any("error", err))
			os.Exit(1)
		}
	}()

	<-ctx.Done()
	slog.Info("shutting down, draining connections")
	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	if err := server.Shutdown(shutdownCtx); err != nil {
		slog.Error("graceful shutdown failed", slog.Any("error", err))
	}
}

func getenv(key, fallback string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return fallback
}

Build dengan golang:1.26, jalankan dengan image final yang kecil

Multi-stage build adalah Dockerfile dengan lebih dari satu FROM. Stage builder boleh besar (berisi compiler), tapi yang masuk image final hanya binary yang kita salin secara eksplisit.

DockerfileSalin
# syntax=docker/dockerfile:1
FROM golang:1.26 AS builder
WORKDIR /src

# Layer dependency lebih dulu agar cache efektif (lihat Section 05).
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

COPY . .
ENV CGO_ENABLED=0 GOOS=linux GOARCH=amd64
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go build -trimpath -ldflags="-s -w" -o /app ./cmd/app

FROM gcr.io/distroless/static-debian13:nonroot
COPY --from=builder /app /app
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/app"]
CMD ["serve"]

Baris paling penting adalah COPY --from=builder /app /app. Instruksi itu mengambil satu artefak dari stage builder, lalu meninggalkan source code, module cache, compiler Go, dan package manager di belakang. Stage builder tidak pernah masuk ke image final.

Setiap flag build punya alasan, bukan ritual salin-tempel:

Build ulang harus cepat saat hanya kode yang berubah

Urutan COPY di Dockerfile menentukan apakah build berikutnya memakai cache atau mengunduh dependency lagi. Ini perbedaan antara rebuild 1 detik dan 40 detik.

Docker menyimpan cache per instruksi (per layer). Dependency Go berubah lebih jarang daripada file handler atau service. Karena itu go.mod dan go.sum disalin lebih dulu, lalu go mod download dijalankan sebelum source code lain masuk. Selama kedua file itu tidak berubah, layer download dipakai ulang.

Potongan Dockerfile: urutan layer yang benarSalin
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /app ./cmd/app

flowchart TD
  A["Ubah internal/order/service.go"] --> B{"go.mod / go.sum berubah?"}
  B -->|Tidak| C["Layer go mod download REUSE"]
  C --> D["Hanya COPY . . dan go build jalan ulang"]
  B -->|Ya| E["Layer go mod download INVALID"]
  E --> F["Download dependency ulang, lalu build"]

Gambar 2. Perubahan kode biasa tidak membatalkan cache download selama go.mod dan go.sum stabil. Hanya menambah dependency yang memicu download ulang.

Layer cache punya batas: ia hilang kalau go.mod berubah. BuildKit cache mount lebih kuat karena persist lintas build dan tahan terhadap perubahan go.mod. Cache mount tidak ikut ke image final, hanya hidup saat build.

Potongan Dockerfile: BuildKit cache mountSalin
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go build -trimpath -ldflags="-s -w" -o /app ./cmd/app

Terakhir, batasi build context dengan .dockerignore. File yang tidak relevan tidak perlu dikirim ke daemon, dan ini juga mencegah .env ikut ter-copy saat COPY . ..

.dockerignoreSalin
.git
.gitignore
*.md
Dockerfile*
compose*.yaml
.dockerignore
bin/
dist/
tmp/
*.test
*.out
coverage.*
.env
.env.*
*.log
.idea/
.vscode/

Pilih base sesuai kebutuhan debug, certificate, dan timezone

Setelah binary jadi, pertanyaan berikutnya: di atas apa ia berjalan? Tiga pilihan umum punya trade-off antara ukuran, keamanan, dan kemudahan debug.

Untuk Go API skincare yang memanggil HTTPS keluar (payment gateway, S3, SMTP), CA certificate wajib ada. Tanpa root CA, request HTTPS gagal dengan error x509: certificate signed by unknown authority. Distroless static sudah membawanya, jadi ia adalah default yang dianjurkan.

Kalau kamu memilih scratch (ukuran paling kecil), salin certificate dan timezone manual dari stage builder:

Potongan Dockerfile: scratch dengan CA dan timezoneSalin
FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo
COPY --from=builder /app /app
USER 65532:65532
EXPOSE 8080
ENTRYPOINT ["/app"]
CMD ["serve"]

Alpine adalah pilihan ketiga, dipakai saat tim masih butuh shell untuk investigasi di staging, atau saat aplikasi butuh cgo dengan musl. Harganya: permukaan serangan lebih besar dan kadang ada edge case resolusi DNS musl.

Potongan Dockerfile: Alpine sebagai kompromi debugSalin
FROM alpine:3.23
RUN apk add --no-cache ca-certificates tzdata \
    && addgroup -S app && adduser -S -G app app
COPY --from=builder /app /usr/local/bin/app
USER app
EXPOSE 8080
ENTRYPOINT ["/usr/local/bin/app"]
CMD ["serve"]

Hardening minimum dan cara container melaporkan kesehatannya

Image yang kecil belum tentu aman. Tiga instruksi berikut menentukan apakah container kamu siap production atau menjadi liability.

EXPOSE 8080 hanya metadata dan dokumentasi, ia tidak benar-benar membuka port. Publikasi nyata dilakukan lewat -p 8080:8080 di docker run atau ports: di Compose. Jangan mengandalkan EXPOSE untuk membuka akses.

Untuk healthcheck, ingat bahwa distroless dan scratch tidak punya shell atau curl. Maka healthcheck harus berupa subperintah di binary Go itu sendiri, bukan curl.

cmd/app/main.go (subperintah healthcheck)Salin
func runHealthcheck() {
	addr := getenv("HTTP_ADDR", ":8080")
	url := "http://127.0.0.1" + addr + "/health"

	client := &http.Client{Timeout: 3 * time.Second}
	resp, err := client.Get(url)
	if err != nil {
		slog.Error("healthcheck gagal", slog.Any("error", err))
		os.Exit(1)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		slog.Error("healthcheck status bukan 200", slog.Int("status", resp.StatusCode))
		os.Exit(1)
	}
	os.Exit(0)
}

Potongan Dockerfile: HEALTHCHECK lewat binary sendiriSalin
HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=3 \
    CMD ["/app", "healthcheck"]

Image jangan membawa secret, container menerima konfigurasi

Prinsip 12-factor: config hidup di environment, bukan di kode atau image. Satu image yang sama dipromosikan dari dev ke staging ke production tanpa rebuild, yang berubah hanya env-nya.

Dockerfile tidak boleh berisi DATABASE_URL, JWT_SECRET, PAYMENT_SERVER_KEY, atau credential AWS. Nilai yang ter-bake lewat ENV di Dockerfile tertulis permanen di layer image dan terlihat di docker history. ENV hanya untuk nilai default non-sensitif seperti ENV PORT=8080.

TerminalSalin
# Override per variabel saat runtime
docker run --rm -p 8080:8080 \
  -e APP_ENV=local \
  -e HTTP_ADDR=:8080 \
  -e DATABASE_URL="postgres://postgres:postgres@host.docker.internal:5432/skincare?sslmode=disable" \
  skincare-api serve

TerminalSalin
# Muat banyak variabel dari file yang diabaikan git
docker run --rm -p 8080:8080 --env-file .env.local skincare-api serve

.env.localSalin
APP_ENV=local
HTTP_ADDR=:8080
DATABASE_URL=postgres://postgres:postgres@host.docker.internal:5432/skincare?sslmode=disable
JWT_SECRET=local-only-change-me
PAYMENT_SERVER_KEY=local-midtrans-key

Image yang sama, entrypoint berbeda, tanpa port HTTP

Worker skincare (pengirim email, pemroses webhook payment, sinkronisasi inventory) berjalan dari image yang sama persis dengan API. Yang berbeda hanya argumen yang diberikan ke entrypoint.

Karena main.go sudah men-dispatch subperintah, kita tidak butuh Dockerfile kedua. docker run skincare-api worker menimpa CMD ["serve"] default dan menjalankan app worker. Worker tidak membuka port HTTP, jadi tidak perlu -p.

cmd/app/main.go (subperintah worker)Salin
func runWorker() {
	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()

	slog.Info("skincare worker started")
	// consumer.Run memblokir sampai ctx dibatalkan (SIGTERM saat deploy).
	if err := worker.Run(ctx); err != nil {
		slog.Error("worker stopped", slog.Any("error", err))
		os.Exit(1)
	}
	slog.Info("worker drained, exiting")
}

TerminalSalin
# Container API: listen HTTP di 8080
docker run --rm -p 8080:8080 --env-file .env.local skincare-api serve

# Container worker: tanpa port, hanya konsumsi antrian
docker run --rm --env-file .env.local skincare-api worker

flowchart LR
  IMG["Image skincare-api (1 binary)"] --> API["container: app serve"]
  IMG --> WRK["container: app worker"]
  API -->|HTTP :8080| LB["Load Balancer / ALB"]
  WRK -->|poll| Q[("Antrian: SQS / Redis")]
  Q -->|payment & email event| WRK
  API --> DB[("PostgreSQL")]
  WRK --> DB

Gambar 3. Satu image melahirkan dua tipe container. API melayani request HTTP, worker mengonsumsi antrian. Keduanya berbagi binary, config, dan akses database yang sama.

Bangun image lokal, jalankan API dan worker, lalu ukur hasilnya

Sekarang kita jalankan flow minimum yang menjadi dasar pipeline CI/CD di chapter berikutnya: build, run, cek health, inspeksi ukuran, dan verifikasi non-root.

go.modSalin
module github.com/kamu/skincare-backend

go 1.26

TerminalSalin
# BuildKit aktif default di Docker modern; bisa dipaksa via env.
DOCKER_BUILDKIT=1 docker build -t skincare-api:dev .

# Lihat ukuran image final (harapannya hanya beberapa MB).
docker image ls skincare-api

# Jalankan API.
docker run --rm -p 8080:8080 --env-file .env.local skincare-api:dev serve

Di terminal lain, cek health endpoint dan endpoint domain yang nantinya ikut berjalan dalam container yang sama.

TerminalSalin
curl -i http://localhost:8080/health

Verifikasi bahwa container benar-benar berjalan sebagai non-root dengan menjalankan subperintah yang mencetak UID, atau dengan mengintip metadata image.

TerminalSalin
# Inspeksi user default image (harus 65532 / nonroot, bukan root).
docker inspect skincare-api:dev --format '{{.Config.User}}'

# Jalankan worker dari image yang sama, tanpa port.
docker run --rm --env-file .env.local skincare-api:dev worker

Output /health yang diharapkan adalah 200 ok. Untuk skincare, endpoint berikutnya (cart, checkout, auth, webhook payment, admin) ikut berjalan dalam container yang sama. Container tidak mengubah desain domain, ia hanya membungkus proses agar siap dikirim ke CI lalu ke AWS.

Kebanyakan bug container Go datang dari asumsi runtime Node atau PHP

Sebagian besar masalah container Go bukan berasal dari bahasa Go, tapi dari kebiasaan runtime yang terbawa dari Node, React, atau PHP.

Docker bukan tujuan akhir. Docker adalah format pengiriman API dan worker yang membuat testing, CI/CD, dan deploy AWS menjadi konsisten dan dapat diulang.

Untuk proyek skincare, image ini akan membawa API katalog, cart, checkout, auth, webhook payment, dan admin route, plus worker untuk email dan pemrosesan payment, ke pipeline deployment. Container tidak mengubah desain domain yang sudah kamu bangun di Roadmap 1 sampai 7, ia hanya membungkusnya menjadi artefak yang siap dikirim.

Langkah berikutnya di Roadmap 8 (Chapter 2) adalah menggabungkan container API dan worker dengan PostgreSQL dan Redis memakai Docker Compose. Di sana kita mensimulasikan environment production kecil: service saling kenal lewat nama host, depends_on dengan condition: service_healthy, named volume untuk data Postgres, dan env yang lebih terstruktur. Setelah itu, Chapter 3 mengangkat image yang sama ini ke CI pipeline (lint, test, build, push), sebelum akhirnya di-deploy ke ECS Fargate.