Go Docker

You are a Go developer and DevOps engineer. The user wants to create an optimized multi-stage Docker build for Go applications that minimizes image size and build time.

What to check first

• Run go version to confirm Go is installed locally
• Check if Docker is installed with docker --version
• Verify your Go project has a go.mod file in the root directory
• Ensure your main Go file exists (typically main.go)

Steps

1. Create a Dockerfile in your project root with a builder stage using golang:[version]-alpine as the base image
2. In the builder stage, set WORKDIR /app and copy go.mod and go.sum files first to leverage Docker layer caching
3. Run go mod download in the builder stage to fetch dependencies before copying source code
4. Copy all source code and run CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main . to create a static binary
5. Create a second stage using alpine:[version] as the final base image (much smaller than full OS images)
6. Copy only the compiled binary from the builder stage into the final image using COPY --from=builder
7. Set the entrypoint with ENTRYPOINT ["/app/main"] to run the binary directly
8. Build the image with docker build -t myapp:latest . and test with docker run myapp:latest

Code

# Stage 1: Builder
FROM golang:1.21-alpine AS builder

# Install build dependencies
RUN apk add --no-cache git ca-certificates tzdata

WORKDIR /app

# Copy go mod files and download dependencies
COPY go.mod go.sum ./
RUN go mod download

# Copy source code
COPY . .

# Build static binary
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main .

# Stage 2: Final runtime image
FROM alpine:3.18

# Install runtime dependencies (ca-certificates for HTTPS, tzdata for timezone)
RUN apk add --no-cache ca-certificates tzdata

WORKDIR /app

# Copy binary from builder
COPY --from=builder /app/main .

# Copy any static assets if needed
# COPY --from=builder /app/assets ./assets

# Non-root user for security (optional but recommended)
RUN addgroup -g 1000 appuser && adduser -D -u 1000 -G appuser appuser
USER appuser

EXPOSE 8080

ENTRYPOINT ["./main"]

Pitfalls

• CGO_ENABLED=0 is critical — if you forget this flag, your binary will link against libc and fail in the slim Alpine runtime image with "not found" errors
• Alpine base image size trap — while Alpine is small (~5MB), it lacks glibc; use `distro

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change