Docker in 2026: From Zero to Production-Ready Containers

A complete, no-fluff guide to containers, images, Dockerfiles, Compose, volumes, and networking with real Go + Gin + PostgreSQL examples.

Table of contents

1. Why Docker exists the problem it solves
2. Images vs containers the distinction that matters
3. Docker commands cheatsheet
4. Writing your first Dockerfile
5. Docker Compose managing multiple containers
6. Volumes and data persistence
7. Docker networking
8. Putting it all together your complete project

1. Why Docker exists the problem it solves

Every Go developer has lived this moment: you write an API on your MacBook, it compiles and runs perfectly, you push to GitHub, and your teammate pulls it on their Linux workstation. go run main.go panics.

The database connection string that worked on your machine fails on theirs. The libc version is different. The environment variable you set in your .zshrc six months ago and forgot about it's not on their machine. The exact libpq version your PostgreSQL driver expects? Wrong.

Here is why this happens. When you build a Go application, it silently accumulates a set of environmental dependencies:

• A specific version of the Go toolchain (1.21, not 1.20, and definitely not 1.19)
• The gcc compiler for CGO-dependent packages
• System CA certificates for HTTPS calls to external APIs
• Environment variables configured only in your local shell profile
• The exact libpq version your PostgreSQL driver expects

None of these are in your go.mod. They live invisibly on your machine.

Docker solves this by packaging your application together with its entire environment into a single portable unit called a container.

Instead of saying “here is my code, good luck running it”, you now ship: code + Go runtime + system libraries + configuration, all bundled. Wherever that bundle runs your laptop, your teammate’s Windows machine, a CI/CD pipeline, a production server on AWS the behavior is identical.

This is especially valuable in teams where onboarding a new developer used to mean half a day of “install Go, configure PostgreSQL, set environment variables, hope glibc versions match." With Docker, it becomes: docker compose up. Done.

2. Images vs containers — the distinction that matters

This is where most beginners get confused. Docker has two core entities and understanding their relationship is the foundation of everything else.

Docker image

A Docker image is a read-only, static snapshot of what an environment should look like. It is not a running process. Think of it exactly like a struct definition in Go it holds the blueprint but does not allocate any runtime resources by itself.

Images are built from a file called a Dockerfile (covered in section 4). Once built, an image can be shared, versioned with tags, and stored in a registry like Docker Hub.

Docker container

A container is a running instance created from an image. Just as you instantiate a struct in Go, you instantiate containers from images. A single image can produce many containers simultaneously, each isolated from the others.

Image ──────────► Container 1 (running)
──────────► Container 2 (running)
──────────► Container 3 (stopped)

Key differences at a glance

Property Image Container State Static, read-only Dynamic, has runtime state Resources No CPU/RAM consumed Consumes CPU and RAM Mutability Immutable after build Writable layer on top of image Sharing Pushed/pulled from registries Not directly shareable Go analogy struct type definition struct instance in memory

Image layers

Every image is composed of stacked, immutable layers. When Docker builds an image, each instruction in the Dockerfile creates a new layer. This layered architecture has a critical performance benefit: layers are cached and shared.

If you have two images both based on golang:1.21-alpine, Docker only stores that base layer once on your machine. When you pull the second image, it reuses the cached layer instead of downloading it again. This is why pulling a second Go-based image shows "Already exists" for several layers — those layers are shared.

3. Docker commands cheatsheet

Before writing any Dockerfiles, you need to be fluent in the core CLI. Here is a complete reference with explanations for every command.

Working with images

# Pull an image from Docker Hub
docker pull golang:1.21-alpine

docker pull fetches an image from a registry to your local machine. The format is image_name:tag. If you omit the tag, Docker defaults to latest which can be unpredictable. Always specify a version tag for reproducibility.

# List all locally available images
docker images

Shows every image on your machine repository name, tag, image ID, creation date, and size. Watch the SIZE column: a Go binary built with multi-stage builds (section 4) drops from ~350 MB to ~25 MB.

# Remove an image
docker rmi golang:1.21-alpine

Deletes an image. Will fail if a container (even a stopped one) is still using it remove the container first.

# Remove all dangling (untagged) images
docker image prune

Cleans up <none>:<none> images left behind from failed or replaced builds. Run this periodically to reclaim disk space.

Working with containers

# Create and start a container from an image
docker run golang:1.21-alpine

The most fundamental command. It pulls the image if not available locally, creates a container, and runs the default command. For golang:1.21-alpine, that default is go version the container prints it and exits immediately.

# Run a container in detached (background) mode
docker run -d golang:1.21-alpine sleep 3600

The -d flag detaches the container so it runs in the background. The sleep 3600 keeps it alive for an hour so you can inspect it.

# Run a container interactively with a shell
docker run -it golang:1.21-alpine sh

-i keeps stdin open; -t allocates a pseudo-TTY. Together, -it gives you an interactive shell inside the container. Inside, try go version and cat /etc/os-release to see the isolated environment.

# Run with port binding
docker run -d -p 8080:8080 my-gin-app

-p host_port:container_port maps a port on your machine to a port inside the container. Without this, your Gin app running on port 8080 inside the container would be completely unreachable from your browser or curl.

# Run with an environment variable
docker run -d \
-e DATABASE_URL="host=localhost user=admin password=secret dbname=appdb port=5432 sslmode=disable" \
my-gin-app

-e sets an environment variable inside the container at runtime. Go applications read these with os.Getenv(). This is how you inject secrets and configuration without hardcoding them into the image.

# Give the container a human-readable name
docker run -d --name gin-api my-gin-app

By default, Docker assigns a random name like peaceful_darwin. Using --name makes subsequent commands much easier.

# List running containers
docker ps

# List ALL containers (including stopped)
docker ps -a

# Stop a running container (graceful SIGTERM, then SIGKILL after 10s)
docker stop gin-api

# Start a stopped container
docker start gin-api

# Remove a stopped container
docker rm gin-api

# Force-remove a running container
docker rm -f gin-api

Inspecting and debugging

# View logs of a container
docker logs gin-api

# Follow logs in real time
docker logs -f gin-api

docker logs is your first stop when a container misbehaves. It captures everything the process wrote to stdout and stderr. For Gin, this includes HTTP request logs and panic stack traces.

# Execute a command inside a running container
docker exec -it gin-api sh

docker exec runs an additional command inside an already running container you are not creating a new container, you are attaching to an existing one. Try env to see all environment variables, or cat /etc/resolv.conf to see DNS configuration.

# Inspect detailed container metadata
docker inspect gin-api | jq '.[0].NetworkSettings'

Returns a JSON payload covering network settings, volume mounts, environment variables, resource limits. Pipe through jq for readable output.

# Display real-time resource usage (CPU, memory, network I/O)
docker stats

Managing networks and volumes

# List all Docker networks
docker network ls

# Create a custom network
docker network create app-network

# Remove a network
docker network rm app-network

# List all volumes
docker volume ls

# Create a named volume
docker volume create pg-data

# Remove unused volumes
docker volume prune

4. Writing your first Dockerfile

A Dockerfile is a plain text file containing instructions that Docker executes top-to-bottom to build your image. Each instruction creates a new layer.

The application we are dockerizing

A minimal Gin REST API that stores and retrieves users from PostgreSQL.

main.go

package main

import (
"net/http"
"os"
"time"

"github.com/gin-gonic/gin"
"gorm.io/driver/postgres"
"gorm.io/gorm"
)

type User struct {
ID uint `json:"id" gorm:"primaryKey"`
Name string `json:"name"`
Email string `json:"email"`
CreatedAt time.Time `json:"created_at"`
}

var DB *gorm.DB

func initDB() {
dsn := os.Getenv("DATABASE_URL")
if dsn == "" {
dsn = "host=localhost user=admin password=secret dbname=appdb port=5432 sslmode=disable"
}
var err error
DB, err = gorm.Open(postgres.Open(dsn), &gorm.Config{})
if err != nil {
panic("failed to connect database: " + err.Error())
}
DB.AutoMigrate(&User{})
}

func main() {
initDB()
r := gin.Default()

r.GET("/users", func(c *gin.Context) {
var users []User
DB.Find(&users)
c.JSON(http.StatusOK, users)
})

r.POST("/users", func(c *gin.Context) {
var user User
if err := c.ShouldBindJSON(&user); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
}
DB.Create(&user)
c.JSON(http.StatusCreated, user)
})

r.Run(":8080")
}

go.mod

module gin-docker-demo

go 1.21

require (
github.com/gin-gonic/gin v1.9.1
gorm.io/driver/postgres v1.5.4
gorm.io/gorm v1.25.5
)

The Dockerfile — with multi-stage builds

Multi-stage builds are the most important Go-specific Docker technique. The core idea: use one stage to compile the binary (needs the full Go toolchain), and a second stage to run it (needs almost nothing). The final image only ships the compiled binary.

# ── Stage 1: Build stage ──────────────────────────────────────────────
FROM golang:1.21-alpine AS builder

FROM ... AS builder names this stage. golang:1.21-alpine is the official Go 1.21 image based on Alpine Linux (~350 MB). The AS builder alias lets us reference this stage's filesystem in stage 2.

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

Alpine uses apk as its package manager. --no-cache prevents storing the package index in the layer. git is needed for fetching some Go modules; ca-certificates enables HTTPS validation during go mod download.

WORKDIR /app

Sets the working directory for all subsequent instructions. Think of it as cd /app if the directory doesn't exist, Docker creates it.

# Copy dependency files first — critical for layer caching
COPY go.mod go.sum ./

We copy go.mod and go.sum before the source code. This is deliberate. Docker caches each layer if go.mod hasn't changed, the next go mod download step will be served entirely from cache, saving 30-60 seconds on every build.

RUN go mod download

Downloads all modules into the local module cache. Because this layer is cached, subsequent builds where only .go files changed skip this step entirely.

COPY . .

Now we copy the application source. Changing .go files only invalidates this layer and below not the expensive go mod download step above.

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

This is the key compilation step for Go containers:

• CGO_ENABLED=0 disables CGO, producing a fully static binary with zero dynamic library dependencies
• GOOS=linux targets Linux regardless of the build machine's OS (important if you're building on macOS)
• -aforces rebuilding all packages for a clean static result
• -installsuffix cgo keeps the build cache separate from CGO builds
• -o mainoutputs the binary named main

The result: a single executable that runs anywhere without any runtime dependencies.

# ── Stage 2: Final minimal image ─────────────────────────────────────
FROM alpine:latest

We start fresh from alpine:latest (~5 MB). No Go toolchain. No source code. No module cache. The final image will only contain what's needed to run the binary.

RUN apk --no-cache add ca-certificates
WORKDIR /root/

Even a minimal image needs CA certificates for outbound HTTPS calls (payment APIs, webhooks, auth services).

# Pull the compiled binary from stage 1
COPY --from=builder /app/main .

--from=builder reaches into the filesystem of stage 1 and copies exactly one file the compiled main binary. That's it. No source, no compiler, no temporary files.

EXPOSE 8080
CMD ["./main"]

EXPOSE 8080 documents which port the application listens on. CMD in exec form (JSON array) makes your binary PID 1 directly it receives OS signals correctly, enabling graceful shutdown when Docker sends SIGTERM.

Full Dockerfile

# Stage 1 — Build
FROM golang:1.21-alpine AS builder
RUN apk add --no-cache git ca-certificates
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main .

# Stage 2 — Run
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/main .
EXPOSE 8080
CMD ["./main"]

Build and verify the size difference

# Build the image
docker build -t gin-app:1.0 .

# See the dramatic size difference
docker images
# REPOSITORY TAG SIZE
# gin-app 1.0 ~25MB ← multi-stage: tiny
# golang 1.21 ~350MB ← full image: huge

# Run a container
docker run -d \
-p 8080:8080 \
-e DATABASE_URL="host=localhost user=admin password=secret dbname=appdb port=5432 sslmode=disable" \
--name gin-api \
gin-app:1.0

.dockerignore

# .dockerignore
*.md
.git/
.env
.env.example
tmp/
vendor/

Without this, Docker sends your entire project directory to the build daemon as the build context, slowing every build. With it, only the files Docker actually needs are transferred.

5. Docker Compose — managing multiple containers

Running a single container with docker run is manageable. But a real application has multiple services a Go API, a PostgreSQL database, a monitoring UI. Running each with a long docker run command, keeping them on the same network, managing startup order this becomes painful fast.

Meet Rahul, a backend engineer who just joined your team. On his first day, he clones the repository and runs docker compose up -d. Three minutes later, he has a fully working local environment: the Gin API on port 8080, PostgreSQL on port 5432, pgAdmin on port 8081. No "install PostgreSQL" guide. No "configure your local environment" wiki page. One command.

Docker Compose makes this possible by letting you define your entire multi-container application in a single YAML file.

The docker-compose.yml file

services:

# ── Go/Gin API ────────────────────────────────────────────────────
api:
build: .
container_name: gin-api
ports:
- "8080:8080"
environment:
- DATABASE_URL=host=postgres user=admin password=secret dbname=appdb port=5432 sslmode=disable
- GIN_MODE=release
depends_on:
postgres:
condition: service_healthy # Wait until Postgres healthcheck passes
networks:
- app-network
restart: unless-stopped

# ── PostgreSQL database ───────────────────────────────────────────
postgres:
image: postgres:15-alpine
container_name: pg-db
environment:
- POSTGRES_DB=appdb
- POSTGRES_USER=admin
- POSTGRES_PASSWORD=secret
ports:
- "5432:5432"
volumes:
- pg-data:/var/lib/postgresql/data
- ./init.sql:/docker-entrypoint-initdb.d/init.sql
networks:
- app-network
healthcheck:
test: ["CMD-SHELL", "pg_isready -U admin -d appdb"]
interval: 5s
timeout: 5s
retries: 5

# ── pgAdmin (database UI) ─────────────────────────────────────────
pgadmin:
image: dpage/pgadmin4
container_name: pg-admin
environment:
- PGADMIN_DEFAULT_EMAIL=admin@admin.com
- PGADMIN_DEFAULT_PASSWORD=admin
ports:
- "8081:80"
networks:
- app-network
depends_on:
- postgres

networks:
app-network:
driver: bridge

volumes:
pg-data:

Breaking down the key concepts

Service names as hostnames The key postgres under services automatically becomes a DNS hostname inside the Docker network. This is why DATABASE_URL uses host=postgresCompose resolves postgres to that container's internal IP address. No hardcoded IPs needed.

depends_on with condition: service_healthy The plain depends_on only guarantees startup order. With condition: service_healthy, Compose actually waits until the healthcheck on the postgres service passes before starting the api. This prevents the Go app from panicking on startup because the database isn't ready yet.

healthcheck on postgrespg_isready -U admin -d appdb probes whether PostgreSQL is actually accepting connections, not just whether the process is running. It retries every 5 seconds up to 5 times.

restart: unless-stopped If the api container crashes (e.g., a panic before the database is ready on a very slow machine), Docker restarts it automatically. Combined with the healthcheck condition, this makes the startup bulletproof.

init.sql mount The official PostgreSQL image runs every .sql file in /docker-entrypoint-initdb.d/ on first initialization. Mount your schema file there and your tables are created automatically.

Core Compose commands

# Start all services — builds images if needed
docker compose up -d

# Show running services and their status
docker compose ps

# Follow logs across all services
docker compose logs -f

# Follow logs for a specific service only
docker compose logs -f api

# Open a psql shell inside the running postgres container
docker compose exec postgres psql -U admin -d appdb

# Rebuild the api image after code changes
docker compose up -d --build api

# Stop services (containers preserved)
docker compose stop

# Stop and remove containers + networks (volumes preserved)
docker compose down

# Stop, remove containers + networks + volumes
docker compose down -v

Environment variables and .env files

# .env — never committed to Git
POSTGRES_PASSWORD=my_strong_password
PGADMIN_PASSWORD=admin_password
DATABASE_URL=host=postgres user=admin password=my_strong_password dbname=appdb port=5432 sslmode=disable

# .env.example — committed to Git, no real values
POSTGRES_PASSWORD=
PGADMIN_PASSWORD=
DATABASE_URL=host=postgres user=admin password= dbname=appdb port=5432 sslmode=disable

# docker-compose.yml — references variables, not values
postgres:
environment:
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

New team members run cp .env.example .env, fill in their own values, and docker compose up -d. Clean, secure, repeatable.

6. Volumes and data persistence

By default, a Docker container has a writable layer on top of its image. Any files your application writes database rows, uploaded files, logs live in this layer. The problem: when you remove the container with docker rm, that writable layer is permanently deleted. Every restart of your PostgreSQL container means an empty database.

Volumes are Docker’s solution to data persistence. They exist independently of any container’s lifecycle.

The three types of volume mounts

1. Named volumes — recommended for databases

volumes:
- pg-data:/var/lib/postgresql/data

Docker manages the storage location internally. You reference it by name. Named volumes are the preferred approach for persistent data because Docker handles creation, cleanup, and lifecycle you never need to know the exact host path.

docker volume create pg-data
docker volume inspect pg-data
# Shows the actual path: /var/lib/docker/volumes/pg-data/_data

2. Bind mounts — recommended for development

volumes:
- ./api:/app

Binds a host directory directly into the container. Changes on either side are instantly reflected on the other. Ideal during development edit a .go file in your editor, and a tool like air (Go live reload) picks it up inside the container without rebuilding the image.

docker run -d \
-v $(pwd)/api:/app \
-p 8080:8080 \
gin-app:1.0

3. Anonymous volumes — ephemeral temporary storage

volumes:
- /app/tmp

Docker assigns a random hex name. Removed when the container is removed. Used when you need temporary isolated storage that should not persist.

Verifying persistence

# Start the stack
docker compose up -d

# Insert a user
curl -X POST http://localhost:8080/users \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "email": "alice@example.com"}'

# Verify
curl http://localhost:8080/users
# [{"id":1,"name":"Alice","email":"alice@example.com","created_at":"2026-05-20T10:30:00Z"}]

# Tear down containers — volumes are preserved
docker compose down

# Bring everything back up
docker compose up -d

# Alice is still there
curl http://localhost:8080/users
# [{"id":1,"name":"Alice","email":"alice@example.com","created_at":"2026-05-20T10:30:00Z"}]

Without the named volume, the second query returns an empty array. With it, Alice survives container deletion.

# Clean up unused volumes
docker volume prune

# Nuclear option — remove containers AND volumes
docker compose down -v

7. Docker networking

Every container you run gets connected to a Docker network. Networking governs how containers communicate with each other, with your host machine, and with the outside world.

Default networks Docker creates

docker network ls
# NETWORK ID NAME DRIVER SCOPE
# abc123 bridge bridge local
# def456 host host local
# ghi789 none null local

bridge (default) Every container without an explicit network joins this. Containers can communicate by IP address but not by name there is no automatic DNS. Always create custom bridge networks instead.

hostThe container shares the host's network stack directly. No isolation the container's port 8080 is the host's port 8080, no -p mapping needed. Useful for performance-sensitive scenarios but sacrifices isolation.

noneComplete isolation. No network interfaces except loopback. Used for batch containers that should have zero network access.

Custom bridge networks — always use these

When containers share a custom bridge network, Docker provides automatic DNS resolution. Containers reach each other by service name.

# Create a custom network
docker network create app-network

# Run postgres on it
docker run -d \
--name postgres \
--network app-network \
-e POSTGRES_PASSWORD=secret \
postgres:15-alpine

# Run Gin app on the same network
# It reaches postgres using the hostname "postgres"
docker run -d \
--name gin-api \
--network app-network \
-p 8080:8080 \
-e DATABASE_URL="host=postgres user=admin password=secret dbname=appdb port=5432 sslmode=disable" \
gin-app:1.0

Container ports are internal by default. A Gin app on port 8080 inside a container is unreachable from your browser without explicit binding.

docker run -p 8080:8080 gin-app:1.0
# ^ ^
# host container

# Bind a different host port if 8080 is taken
docker run -p 9090:8080 gin-app:1.0

Critical rule: Two containers cannot bind the same host port. Starting a second container on port 8080 when one is already using it throws a “port already allocated” error. Each container needs a unique host port, even when their internal container ports are the same.

Inspecting networking

# See all containers on a network and their IPs
docker network inspect app-network

# See which networks a container is on
docker inspect gin-api | jq '.[0].NetworkSettings.Networks'

# Add a running container to an additional network
docker network connect app-network my-other-container

# Remove it
docker network disconnect app-network my-other-container

How Compose handles networking automatically

Compose creates a default bridge network named <project-name>_default and connects every service automatically. Service names become resolvable hostnames with no extra configuration.

Declaring a custom network explicitly (as in section 5) is still recommended it gives a predictable name, makes intent clear, and lets you run docker network inspect app-network to debug connectivity issues.

8. Putting it all together — your complete project

After working through all seven sections, your project should be organized like this:

gin-docker-demo/
├── main.go
├── go.mod
├── go.sum
├── Dockerfile
├── docker-compose.yml
├── .env ← not committed to Git
├── .env.example ← template for new developers
├── .dockerignore
└── init.sql ← database initialization script

init.sql

CREATE TABLE IF NOT EXISTS users (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Mounted into docker-entrypoint-initdb.d/, PostgreSQL runs this automatically on first startup. Your schema is always ready before the Go app connects.

The complete developer workflow

# Clone on any machine
git clone https://github.com/you/gin-docker-demo
cd gin-docker-demo

# Set up environment variables
cp .env.example .env
# Fill in POSTGRES_PASSWORD and DATABASE_URL in .env

# Build images and start everything
docker compose up -d --build

# Verify all services are healthy
docker compose ps

# Watch the Go app logs — confirm it connected to PostgreSQL
docker compose logs -f api
# [GIN-debug] Listening and serving HTTP on :8080
# [GIN] 200 | GET /users

# Test the API
curl http://localhost:8080/users

# Open pgAdmin
# http://localhost:8081
# Login: admin@admin.com / admin
# Add server: host=postgres, port=5432, user=admin, password=<from .env>

# Rebuild after code changes (only the api service)
docker compose up -d --build api

# Done for the day
docker compose stop

# Full cleanup — containers and networks removed, volumes preserved
docker compose down

Quick reference card

Final thoughts

Docker has gone from a niche DevOps tool to a baseline expectation in professional software development. The mental model shift it demands from “software installed on a machine” to “software packaged with its environment” is the only real hurdle. Once that clicks, the rest follows naturally.

The five principles to internalize:

1. Images are blueprints. Containers are instances. One image, many containers just like a struct type and its instances.
2. Layers are your cache. Order Dockerfile instructions from least to most frequently changed. Dependencies before source code, always.
3. Multi-stage builds are non-negotiable for Go. CGO_ENABLED=0 + a scratch or alpine final stage takes you from 350 MB to 25 MB.
4. Networks are how containers talk. Always use custom bridge networks. Service names resolve automatically in Compose.
5. Volumes are how data survives. Named volumes for databases, bind mounts for development hot-reload.

Master these five principles and you have everything you need to containerize any Go application, eliminate “works on my machine” incidents, and hand your project to any pipeline CI/CD, staging, or production with confidence.

Found this useful? Share it with a Go developer who is still manually installing PostgreSQL. They will thank you.

Docker in 2026: From Zero to Production-Ready Containers was originally published in Coinmonks on Medium, where people are continuing the conversation by highlighting and responding to this story.