matt-riley/agent-skills

go-docker-builds

Containerize Go services with production-ready multi-stage Docker builds.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/matt-riley/agent-skills --skill go-docker-builds

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Go Docker builds

Use this skill when containerizing a Go service for production. It covers the canonical multi-stage build pattern, static compilation, minimal base images, health checks, secrets handling, and CI integration for image builds.

Use this skill when

  • Writing a new Dockerfile for a Go service or API.
  • Debugging a Go Docker build that fails during compilation, linking, or the final image stage.
  • Switching a Go Docker image from a full base image to scratch or distroless.
  • Adding health checks, signals, or graceful shutdown handling to a Go container.
  • Pushing Go images to a registry from CI (GitHub Actions).
  • Handling CGO dependencies in a Go Docker build.
  • Setting up multi-platform builds for Go services.

Do not use this skill when

  • The task is running a local multi-service stack for development — use `docker-compose-dev`.
  • The Dockerfile is for a non-Go service (Node, Python, Ruby, etc.).
  • The Go service fails to build outside Docker — use `testing-workflows`.
  • The main task is configuring CI workflows that happen to include a Docker step — use `github-actions-failure-triage`.

Routing boundary

SituationUse this skill?Route instead
New Dockerfile for a Go API, starting from scratchYes—
Go Docker build fails on go build inside the builder stageYes—
Switching from golang:alpine base to scratch for a Go binaryYes—
Local dev with docker compose up for PostgreSQL + appNo`docker-compose-dev`
go build fails locally, outside DockerNo`testing-workflows`

Inputs to gather

Required before editing

  • The Go module path and binary name (from go.mod and main.go).
  • Whether the service uses CGO (check for import "C", CGO_ENABLED, or C library dependencies).
  • The target registry and image name (e.g. ghcr.io/owner/repo).
  • Whether the build is single-platform or multi-platform.

Helpful if present

  • The existing Dockerfile and any .dockerignore.
  • The Go version pinned in go.mod (go 1.26 → use golang:1.26-alpine).
  • The CI workflow that builds and pushes the image.

Only investigate if encountered

  • Whether the service needs CA certificates in the final image (scratch images lack them).
  • Whether the binary needs to run as non-root.
  • Whether timezone data is required in the final image.

First move

  1. Check go.mod for the Go version, CGO_ENABLED usage, and the binary name.
  2. Identify whether the existing Dockerfile follows the canonical multi-stage pattern or needs restructuring.
  3. Determine the minimal base image needed: scratch for pure Go, alpine for CGO or CA certs, distroless for extra hardening.

Workflow

1. Canonical multi-stage build

The standard Go Dockerfile for a pure-Go service with no CGO:

dockerfile
FROM golang:1.26-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .

RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server

FROM scratch

COPY --from=builder /app/server /server
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

EXPOSE 8080
ENTRYPOINT ["/server"]

Key rules:

  • Pin the Go version to match go.mod (e.g. go 1.26 → golang:1.26-alpine).
  • go mod download as a separate layer before COPY . . so dependency changes don't invalidate the source cache.
  • CGO_ENABLED=0 for static binaries that run on scratch.
  • -ldflags="-s -w" strips debug info, reducing binary size (~30% smaller).
  • COPY --from=builder /etc/ssl/certs/ca-certificates.crt is required when the service makes HTTPS outbound calls from a scratch image.
  • The scratch base has no shell, no package manager, and no CA certs — only add what the binary actually needs.

2. CGO builds

When the service requires CGO (sqlite via go-sqlite3, etc.):

dockerfile
FROM golang:1.26-alpine AS builder

RUN apk add --no-cache gcc musl-dev

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .

RUN CGO_ENABLED=1 go build -ldflags="-s -w" -o /app/server ./cmd/server

FROM alpine:3.21

RUN apk add --no-cache ca-certificates tzdata

COPY --from=builder /app/server /server

EXPOSE 8080
ENTRYPOINT ["/server"]

Key differences from pure-Go:

  • gcc and musl-dev are required in the builder stage for CGO compilation.
  • The final image must be alpine, not scratch, because CGO binaries dynamically link musl libc.
  • tzdata is often needed for timezone-aware applications; add it explicitly.

3. Non-root user

Run the binary as a non-root user for defense in depth:

dockerfile
FROM alpine:3.21

RUN apk add --no-cache ca-certificates tzdata
RUN addgroup -S app && adduser -S app -G app

COPY --from=builder /app/server /server

USER app
EXPOSE 8080
ENTRYPOINT ["/server"]

For scratch images, copy /etc/passwd from the builder or use a numeric UID:

dockerfile
FROM scratch
COPY --from=builder /etc/passwd /etc/passwd
COPY --from=builder /etc/group /etc/group
COPY --from=builder /app/server /server
USER 1000:1000
EXPOSE 8080
ENTRYPOINT ["/server"]

4. Health checks

Add a health check that calls the service's own /health endpoint:

dockerfile
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD /server health || exit 1

For scratch images with no shell, the binary must support a health subcommand that exits 0 on success. For alpine images, use wget or the binary directly. Read `references/health-check-patterns.md` for alternatives.

5. Multi-platform builds

For multi-platform images (amd64 + arm64), use docker buildx:

bash
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --tag ghcr.io/owner/repo:latest \
    --push .

In .goreleaser.yaml, multi-platform Docker builds are configured under dockers:

yaml
dockers:
  - image_templates:
      - "ghcr.io/owner/repo:{{ .Tag }}"
      - "ghcr.io/owner/repo:latest"
    dockerfile: Dockerfile
    build_flag_templates:
      - "--platform=linux/amd64,linux/arm64"

6. CI integration (GitHub Actions)

The canonical GitHub Actions job for building and pushing a Go Docker image:

yaml
jobs:
  docker:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }},ghcr.io/${{ github.repository }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

Key rules:

  • Set packages: write permission for GHCR pushes.
  • Use ${{ secrets.GITHUB_TOKEN }} — no need for a personal access token.
  • Enable GitHub Actions cache for faster rebuilds.
  • Tag with both ${{ github.sha }} for traceability and latest for convenience.

7. .dockerignore

Always include a .dockerignore to keep the build context small:

.git
.github
*.md
.env
.env.*
tmp/
*.log
node_modules/

The builder only needs Go source — keep everything else out of the context.

Outputs

  • A production-ready multi-stage Dockerfile for a Go service.
  • A .dockerignore that keeps the build context minimal.
  • CI workflow configuration for building and pushing the image on push/PR.
  • Health check wired in the Dockerfile or documented as a binary subcommand.

Guardrails

  • Must use CGO_ENABLED=0 for static binaries targeting scratch.
  • Must pin the Go version in the builder stage to match go.mod.
  • Must not use :latest Go image tags; pin to a specific minor version.
  • Must add CA certificates to scratch images when the service makes outbound HTTPS calls.
  • Should run as non-root in the final image.
  • Should separate go mod download into its own layer before COPY . ..
  • Should strip debug info with -ldflags="-s -w".
  • May use distroless instead of scratch when additional hardening is desired.

Validation

  • Run docker build -t test . from the repo root and confirm the image builds without errors.
  • Run docker run --rm test and confirm the binary starts and responds on the expected port.
  • Run docker run --rm test /server health (or the health endpoint) to verify the health check works.
  • If CI is configured, confirm the workflow pushes to the registry on merge to main.
  • Smoke test:
  • should trigger: "Write a Dockerfile for this Go API service that builds a static binary and runs on scratch."
  • should trigger: "This Go Docker build fails because of CGO linking — it needs sqlite3."
  • should trigger: "Add a health check and non-root user to this Go service's Dockerfile."
  • should not trigger: "Run docker compose up to start PostgreSQL and the app for local dev." (→ docker-compose-dev)
  • should not trigger: "go build fails outside Docker with a GOROOT mismatch." (→ testing-workflows)

Examples

  • "Containerize this Go chi API — I want a minimal scratch image with a health check."
  • "My Go service uses go-sqlite3 and the Docker build fails on CGO_ENABLED=0. Fix the Dockerfile."
  • "Set up GitHub Actions to build and push this Go service's Docker image to GHCR on every push to main."

Reference files

같은 저장소의 Skills

더 많은 Skills

모든 Skills