Master Docker for Go Microservices: Real‑World Project Walkthrough

Introduction

This guide shows how to containerize a real‑world Go microservice project named easyms with Docker. It covers Dockerfile design, multi‑stage builds, and Docker Compose orchestration for a set of services that include Consul for service discovery, PostgreSQL for persistence, and several business services (auth‑svc, user‑svc, api‑gateway).

Project Architecture

The docker-compose.yml defines the complete microservice topology:

version: "3.9"
services:
  consul:
    image: consul:1.16
    ports:
      - "8500:8500"

  auth-db:
    image: postgres:15
    environment:
      POSTGRES_USER: authuser
      POSTGRES_PASSWORD: authpass
      POSTGRES_DB: authdb
    ports:
      - "5432:5432"

  auth-svc:
    build:
      context: .
      dockerfile: ./cmd/auth-svc/Dockerfile
    environment:
      POSTGRES_DSN: postgres://authuser:authpass@auth-db:5432/authdb?sslmode=disable
      CONSUL_ADDR: consul:8500
    depends_on:
      - auth-db
      - consul

  user-svc:
    build:
      context: .
      dockerfile: ./cmd/user-svc/Dockerfile
    environment:
      POSTGRES_DSN: postgres://authuser:authpass@auth-db:5432/authdb?sslmode=disable
      CONSUL_ADDR: consul:8500
    depends_on:
      - auth-db
      - consul

  api-gateway:
    build:
      context: .
      dockerfile: ./cmd/api-gateway/Dockerfile
    ports:
      - "8080:8080"
    depends_on:
      - auth-svc
      - user-svc

Dockerfile for user‑svc

A two‑stage Dockerfile builds the Go binary in a lightweight Alpine environment and then copies the statically linked binary into a scratch image.

# syntax=docker/dockerfile:1
FROM golang:1.22-alpine AS build
WORKDIR /src
COPY . .
RUN apk add --no-cache git ca-certificates \
    && CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /bin/service ./cmd/user-svc

FROM scratch
COPY --from=build /bin/service /bin/service
EXPOSE 8081
ENTRYPOINT ["/bin/service"]

Key points

Multi‑stage build keeps the final image minimal.

Alpine provides a small build environment. scratch runtime eliminates unnecessary packages, reducing attack surface.

Static linking ( CGO_ENABLED=0) ensures the binary runs in scratch.

Dockerfile Optimization Techniques

Leverage build cache

# Copy only module files first
COPY go.mod go.sum ./
RUN go mod download

# Then copy the rest of the source
COPY . .

Combine commands to reduce layers

RUN apk add --no-cache git ca-certificates \
    && go build -o /bin/service ./cmd/user-svc

Run as non‑root

# Create a low‑privilege user
RUN adduser -D -s /bin/sh appuser
USER appuser

Advanced Docker Compose Configuration

Network Isolation

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge

services:
  api-gateway:
    networks:
      - frontend
      - backend

Data Persistence

volumes:
  db-data:

services:
  auth-db:
    volumes:
      - db-data:/var/lib/postgresql/data

Resource Limits

services:
  auth-svc:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "0.5"

Common Docker Compose Commands

Basic workflow

# Build images and start all services
docker-compose up

# Run in detached mode
docker-compose up -d

# Stop and remove containers, networks, and volumes
docker-compose down

# List container status
docker-compose ps

# View logs of a specific service
docker-compose logs auth-svc

# Restart a single service
docker-compose restart user-svc

Advanced usage

# Build images only (no containers)
docker-compose build

# Force rebuild without using cache
docker-compose build --no-cache

# Execute a shell inside a running container
docker-compose exec auth-svc sh

# Scale a service to multiple replicas
docker-compose up --scale auth-svc=3

Microservice Deployment Best Practices

Image versioning

services:
  auth-svc:
    image: mycompany/auth-svc:1.2.3

Health checks

services:
  auth-svc:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Configuration management

services:
  auth-svc:
    env_file:
      - ./config/.env

Performance Optimization Strategies

Image size – Use minimal base images (Alpine, scratch), apply multi‑stage builds, and regularly prune dangling images with docker image prune.

Resource usage – Define appropriate memory and cpus limits, share volumes for read‑only data, and monitor containers via docker stats or third‑party tools.

Network efficiency – Create dedicated bridge networks, limit exposed ports to only those required, and enable network compression if supported by the runtime.

Troubleshooting Tips

Log analysis

# Follow live logs
docker-compose logs -f auth-svc

# Show the last 100 lines
docker-compose logs --tail=100 auth-svc

Container inspection

# Detailed container metadata
docker inspect easyms_auth-svc_1

# Real‑time resource consumption
docker stats

Reference

Source code repositories:

GitHub: https://github.com/louis-xie-programmer/easyms.golang

Gitee: https://gitee.com/louis_xie/easyms.golang