matt-riley/agent-skills

go-docker-builds

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

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/matt-riley/agent-skills --skill go-docker-builds

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

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

du même dépôt

Autres Skills

Tous les Skills