Go and Docker are a powerful combination for building, packaging, and deploying modern applications.
Go applications compile into standalone binaries, while Docker packages applications into portable containers that can run consistently across development, testing, staging, and production environments.
If you are building a Go REST API, backend service, web application, microservice, worker, or command-line application, Docker can make deployment and environment management much easier.
In this complete guide, you will learn what Docker is, why Docker works well with Go, how to Dockerize a Go application, create Dockerfiles, use multi-stage builds, reduce image size, manage environment variables, connect PostgreSQL or MySQL, use Docker Compose, work with volumes and networks, add health checks, debug containers, improve security, and prepare Go containers for production.
What Is Docker?
Docker is a platform for packaging and running applications inside isolated environments called containers.
A container contains the application and the files it needs to run.
Instead of manually configuring every server with:
Go
System dependencies
Configuration
Runtime files
Application code
you can package the application into a Docker image.
That image can then be used to create containers.
Conceptually:
Go Application
|
v
Docker Image
|
v
Docker Container
|
v
Application Running
What Is a Docker Image?
A Docker image is a packaged, read-only template used to create containers.
It can contain:
Application binary
Runtime files
System libraries
Certificates
Configuration defaults
For example:
my-go-app:1.0
could be an image containing your compiled Go application.
What Is a Docker Container?
A container is a running instance of an image.
Think of it as:
Dockerfile
↓
Docker Image
↓
Docker Container
You build an image once and can start multiple containers from it.
Docker Image vs Container
An image is the package.
A container is a running instance of that package.
For example:
Image:
go-api:1.0
Containers:
go-api-container-1
go-api-container-2
go-api-container-3
Multiple containers can be created from the same image.
Why Use Docker with Go?
Go already has a simple deployment model because it can compile applications into binaries.
Docker adds additional benefits.
Consistent Environments
Without Docker:
Works on my laptop
↓
Different production environment
↓
Unexpected problems
With Docker:
Same Image
↓
Development
↓
Testing
↓
Staging
↓
Production
The environment becomes much more predictable.
Easy Deployment
Instead of installing Go and configuring the entire environment on every server, you can deploy a container image.
The server primarily needs a compatible container runtime.
Isolation
Different applications can run with separate:
Dependencies
Processes
Filesystems
Environment variables
Networks
Resource limits
This reduces conflicts between applications.
Portability
A Dockerized Go application can run across many environments that support containers.
Examples include:
Developer laptop
Linux server
Cloud VM
Managed container platform
Kubernetes cluster
CI/CD environment
Go Produces Small Binaries
Go applications can often be compiled into self-contained binaries.
This makes it possible to create relatively small runtime container images.
Fast Startup
Go applications generally start quickly, which works well with containerized deployments and horizontal scaling.
What Can You Dockerize with Go?
Docker can package many types of Go applications, including:
REST APIs
Web servers
Microservices
Background workers
gRPC services
WebSocket servers
CLI applications
Scheduled jobs
Authentication services
Database-backed applications
Prerequisites
Before continuing, you should have:
Go installed
Docker installed
Basic Go knowledge
Basic terminal knowledge
Check Go:
go version
Check Docker:
docker --version
You can also verify Docker is running:
docker info
Create a Simple Go Application
Let’s create a small HTTP server.
Create the project:
mkdir go-docker-app
cd go-docker-app
Initialize the Go module:
go mod init go-docker-app
Create:
main.go
Add:
package main
import (
"encoding/json"
"log"
"net/http"
"os"
)
func homeHandler(w http.ResponseWriter, r *http.Request) {
w.Header().Set(
"Content-Type",
"application/json",
)
json.NewEncoder(w).Encode(
map[string]string{
"message": "Hello from Go and Docker!",
},
)
}
func main() {
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
mux := http.NewServeMux()
mux.HandleFunc(
"GET /",
homeHandler,
)
log.Printf(
"Server running on port %s",
port,
)
log.Fatal(
http.ListenAndServe(
":"+port,
mux,
),
)
}
Run locally:
go run .
Open:
http://localhost:8080
Response:
{
"message": "Hello from Go and Docker!"
}
Now we can Dockerize the application.
What Is a Dockerfile?
A Dockerfile contains instructions Docker uses to build an image.
Create:
Dockerfile
inside the project.
Your structure becomes:
go-docker-app/
│
├── Dockerfile
├── go.mod
└── main.go
Your First Go Dockerfile
A simple Dockerfile could be:
FROM golang:1.25
WORKDIR /app
COPY . .
RUN go build -o app .
EXPOSE 8080
CMD ["./app"]
Use a Go image version compatible with the version specified by your project.
Understanding the Dockerfile
Let’s understand every instruction.
FROM
FROM golang:1.25
FROM defines the base image.
Here we are using an official Go image containing the Go toolchain.
WORKDIR
WORKDIR /app
This sets:
/app
as the working directory inside the image.
Future commands run relative to this directory.
COPY
COPY . .
This copies the current project files into the container build environment.
RUN
RUN go build -o app .
This compiles the Go application during the image build.
The resulting binary is:
app
EXPOSE
EXPOSE 8080
This documents that the application is expected to listen on port:
8080
Important:
EXPOSE does not automatically publish the port to your computer.
You still need:
docker run -p 8080:8080 ...
when running locally.
CMD
CMD ["./app"]
This specifies the default command that runs when the container starts.
Build the Docker Image
Run:
docker build -t go-docker-app .
Here:
docker build
builds the image.
-t go-docker-app
assigns the image a name.
.
means Docker should use the current directory as the build context.
View Docker Images
Run:
docker images
You may see:
REPOSITORY TAG IMAGE ID
go-docker-app latest abc123...
Run the Go Container
Run:
docker run \
-p 8080:8080 \
go-docker-app
Open:
http://localhost:8080
Your Go application is now running inside Docker.
Understanding Port Mapping
This:
-p 8080:8080
means:
Host Port Container Port
8080 → 8080
Traffic sent to:
localhost:8080
is forwarded to port:
8080
inside the container.
You could also use:
docker run \
-p 9000:8080 \
go-docker-app
Then access:
localhost:9000
while the Go application still listens on 8080 inside the container.
View Running Containers
Run:
docker ps
To include stopped containers:
docker ps -a
Run Container in Background
Use:
docker run \
-d \
-p 8080:8080 \
--name go-api \
go-docker-app
-d runs the container in detached mode.
View Container Logs
Run:
docker logs go-api
Follow logs continuously:
docker logs -f go-api
Stop a Container
docker stop go-api
Start It Again
docker start go-api
Remove a Container
docker rm go-api
If it is currently running:
docker rm -f go-api
Remove a Docker Image
docker rmi go-docker-app
Why the First Dockerfile Is Not Ideal
Our first Dockerfile uses the full Go development image to run the final application.
That means the production image may contain:
Go compiler
Build tools
Source code
Other unnecessary build dependencies
The final application only needs the compiled binary and any required runtime files.
This is where multi-stage builds become useful.
What Is a Multi-Stage Docker Build?
A multi-stage build uses one image to compile the application and another smaller image to run it.
Architecture:
Stage 1
Go Builder Image
|
| go build
v
Go Binary
|
v
Stage 2
Small Runtime Image
|
v
Production Container
Multi-Stage Dockerfile for Go
A better Dockerfile:
FROM golang:1.25 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 \
GOOS=linux \
go build \
-trimpath \
-ldflags="-s -w" \
-o server \
.
FROM scratch
COPY --from=builder \
/app/server \
/server
EXPOSE 8080
ENTRYPOINT ["/server"]
If your project does not yet have go.sum, either run:
go mod tidy
first or adjust the Dockerfile accordingly.
What Is the Builder Stage?
This:
FROM golang:1.25 AS builder
creates the build stage.
It contains everything required to compile Go.
Why Copy go.mod and go.sum First?
Notice:
COPY go.mod go.sum ./
RUN go mod download
COPY . .
instead of immediately doing:
COPY . .
Docker builds images in layers.
If your Go dependencies have not changed, Docker can often reuse the cached dependency layer even when your application source code changes.
This can significantly improve rebuild speed.
Why CGO_ENABLED=0?
This:
CGO_ENABLED=0
asks Go to build without cgo.
For applications whose dependencies support a pure-Go build, this often produces a binary that is easier to run in minimal Linux images.
However, not every Go application can disable cgo.
Some libraries require native C dependencies.
Always test your specific application.
What Does GOOS=linux Do?
GOOS=linux
builds the binary for Linux.
Docker production containers commonly run Linux binaries.
What Is -trimpath?
-trimpath
removes local filesystem paths from the compiled executable where possible.
It can improve build reproducibility and avoid embedding unnecessary build paths.
What Does -ldflags="-s -w" Do?
This can reduce binary size by removing some debugging and symbol information.
Use it when smaller production binaries are useful.
For development or debugging builds, you may prefer keeping debugging information.
What Is the scratch Image?
scratch is an empty Docker base image.
It contains essentially nothing.
No:
Shell
Package manager
Debugging utilities
Operating system command tools
Your compiled binary becomes almost the entire container.
This can produce very small images.
Limitations of scratch
scratch is not always the best choice.
Your application may require:
CA certificates
Timezone information
Shared libraries
Shell utilities
Runtime debugging tools
If your Go application makes HTTPS requests, ensure the runtime contains the required CA certificates.
Using a Distroless Runtime
Instead of scratch, you can use a minimal runtime image designed for applications.
Conceptually:
FROM golang:1.25 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 \
GOOS=linux \
go build \
-o server \
.
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=builder \
/app/server \
/server
EXPOSE 8080
ENTRYPOINT ["/server"]
A distroless image can provide some runtime essentials while still keeping the image small.
Alpine Runtime
Another option is Alpine Linux.
Example:
FROM golang:1.25-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 \
go build \
-o server \
.
FROM alpine:3.22
RUN apk add \
--no-cache \
ca-certificates
WORKDIR /app
COPY --from=builder \
/app/server \
/app/server
EXPOSE 8080
CMD ["/app/server"]
Alpine includes a small Linux userspace and package manager.
Scratch vs Alpine vs Distroless
There is no universally best runtime image.
Use scratch when:
Your binary is fully self-contained
You want an extremely minimal image
You do not need shell access
Use Alpine when:
You need a small Linux environment
You need packages or shell utilities
You understand musl/cgo compatibility
Use distroless when:
You want a minimal production runtime
You want fewer unnecessary tools
You need common runtime essentials
Choose based on your application rather than image size alone.
Create a .dockerignore File
Docker sends the build context to the builder.
You usually do not want unnecessary files included.
Create:
.dockerignore
Example:
.git
.gitignore
.env
*.log
tmp/
coverage/
bin/
README.md
This can:
Reduce build context
Improve build speed
Avoid copying unnecessary files
Reduce accidental secret exposure
Never rely on .dockerignore as your only secret-management strategy.
Environment Variables with Docker
Applications should not hardcode configuration.
Our Go server already uses:
port :=
os.Getenv("PORT")
Run the container with:
docker run \
-e PORT=9000 \
-p 9000:9000 \
go-docker-app
Inside the container:
PORT=9000
Using an Environment File
Create:
.env
Example:
PORT=8080
APP_ENV=development
DATABASE_URL=postgres://...
Run:
docker run \
--env-file .env \
-p 8080:8080 \
go-docker-app
Do not commit sensitive .env files to a public repository.
Never Put Secrets Directly in the Dockerfile
Bad:
ENV DATABASE_PASSWORD=my-secret-password
Also avoid embedding secrets using build arguments.
Secrets can leak through:
Image metadata
Build history
Source repositories
CI logs
Cached layers
Use an appropriate secrets-management mechanism for your deployment environment.
Docker Networks
Containers need networking to communicate with each other.
For example:
Go API
|
v
PostgreSQL
When both are containers, the Go application should not normally connect to the database using:
localhost
Why?
Because inside the Go container:
localhost
refers to the Go container itself.
Create a Docker Network
Run:
docker network create app-network
Start PostgreSQL:
docker run \
-d \
--name postgres \
--network app-network \
-e POSTGRES_USER=appuser \
-e POSTGRES_PASSWORD=appsecret \
-e POSTGRES_DB=appdb \
postgres
Then start the Go application on the same network.
The Go application can reach PostgreSQL using:
postgres:5432
because:
postgres
is the container name.
PostgreSQL Connection String
Inside Docker:
postgres://appuser:appsecret@postgres:5432/appdb?sslmode=disable
Notice:
@postgres
not:
@localhost
This is a very common beginner mistake.
Go with PostgreSQL and Docker
Install the PostgreSQL driver:
go get github.com/jackc/pgx/v5/stdlib
Example:
package main
import (
"database/sql"
"log"
"os"
_ "github.com/jackc/pgx/v5/stdlib"
)
func openDatabase() *sql.DB {
databaseURL :=
os.Getenv(
"DATABASE_URL",
)
db, err :=
sql.Open(
"pgx",
databaseURL,
)
if err != nil {
log.Fatal(err)
}
if err :=
db.Ping();
err != nil {
log.Fatal(err)
}
return db
}
The connection configuration comes from the environment instead of source code.
What Is Docker Compose?
Running many containers manually becomes inconvenient.
Imagine your project needs:
Go API
PostgreSQL
Redis
Background Worker
You could run several long docker run commands.
Docker Compose lets you define the application stack in one YAML file.
Go + PostgreSQL with Docker Compose
Create:
compose.yaml
Example:
services:
api:
build:
context: .
ports:
- "8080:8080"
environment:
PORT: "8080"
DATABASE_URL:
"postgres://appuser:appsecret@db:5432/appdb?sslmode=disable"
depends_on:
db:
condition: service_healthy
db:
image: postgres
environment:
POSTGRES_USER: appuser
POSTGRES_PASSWORD: appsecret
POSTGRES_DB: appdb
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test:
[
"CMD-SHELL",
"pg_isready -U appuser -d appdb"
]
interval: 5s
timeout: 5s
retries: 5
volumes:
postgres_data:
For production, manage database credentials through a proper secrets mechanism instead of hardcoding them in the Compose file.
Start Docker Compose
Run:
docker compose up
Run in background:
docker compose up -d
Stop the Stack
docker compose down
Stop and Remove Volumes
Be careful with:
docker compose down -v
The -v option removes Compose-managed volumes.
For a database, this can delete your local persisted database data.
Why Does the Database Host Become db?
In:
services:
api:
db:
Compose creates networking where services can reach each other using their service names.
Therefore:
db
can act as the database hostname.
The Go application connects to:
db:5432
instead of:
localhost:5432
depends_on Does Not Mean the Application Is Ready
A container being started does not always mean the application inside it is ready.
For example:
PostgreSQL container starts
|
v
PostgreSQL initializes
|
v
Database becomes ready
Your Go service may start before PostgreSQL accepts connections.
Health checks and application-level retry strategies help handle this.
Add Database Retry Logic
A simple approach:
func waitForDatabase(
db *sql.DB,
) error {
var err error
for attempt := 1;
attempt <= 10;
attempt++ {
err =
db.Ping()
if err == nil {
return nil
}
log.Printf(
"database not ready, attempt %d",
attempt,
)
time.Sleep(
2 * time.Second,
)
}
return err
}
In production, use bounded retries and sensible backoff rather than retrying forever.
Docker Volumes
Containers are designed to be replaceable.
If PostgreSQL stores all data only inside its container filesystem and the container is removed, the data may be lost.
Volumes provide persistent storage.
Example:
volumes:
- postgres_data:/var/lib/postgresql/data
Now the database data can survive container recreation.
Named Volumes
List volumes:
docker volume ls
Inspect:
docker volume inspect postgres_data
Remove:
docker volume rm postgres_data
Be careful when removing database volumes.
Bind Mounts
A bind mount maps a host directory into the container.
Example:
volumes:
- ./static:/app/static
This can be useful during development.
However, production deployments usually rely more on immutable images and dedicated persistent storage.
Go with MySQL and Docker Compose
You can also use MySQL.
Example:
services:
api:
build: .
ports:
- "8080:8080"
environment:
MYSQL_DSN:
"appuser:appsecret@tcp(db:3306)/appdb"
depends_on:
db:
condition: service_healthy
db:
image: mysql
environment:
MYSQL_ROOT_PASSWORD: rootsecret
MYSQL_DATABASE: appdb
MYSQL_USER: appuser
MYSQL_PASSWORD: appsecret
volumes:
- mysql_data:/var/lib/mysql
healthcheck:
test:
[
"CMD",
"mysqladmin",
"ping",
"-h",
"localhost"
]
interval: 5s
timeout: 5s
retries: 10
volumes:
mysql_data:
Connect MySQL from Go
Install:
go get github.com/go-sql-driver/mysql
Import:
import (
"database/sql"
_ "github.com/go-sql-driver/mysql"
)
Connect:
db, err :=
sql.Open(
"mysql",
os.Getenv(
"MYSQL_DSN",
),
)
Inside Compose, the database host is:
db
Add Redis
Suppose your application needs caching.
Architecture:
Go API
|
+----> PostgreSQL
|
+----> Redis
Compose:
services:
api:
build: .
environment:
REDIS_ADDR: "redis:6379"
redis:
image: redis
The Go application can connect to:
redis:6379
Health Checks for Go Applications
Add a health endpoint:
func healthHandler(
w http.ResponseWriter,
r *http.Request,
) {
w.Header().Set(
"Content-Type",
"application/json",
)
json.NewEncoder(w).Encode(
map[string]string{
"status": "ok",
},
)
}
Route:
mux.HandleFunc(
"GET /health",
healthHandler,
)
Response:
{
"status": "ok"
}
Docker Health Check
If your runtime image contains a suitable HTTP client, a health check can call the endpoint.
For example:
HEALTHCHECK \
--interval=30s \
--timeout=3s \
CMD wget \
--spider \
http://localhost:8080/health \
|| exit 1
However, scratch and many distroless images do not include wget or curl.
An alternative is to:
Use platform-native HTTP health checks
Create a small Go health-check binary
Use a runtime image containing the required tool
Do not add a large collection of utilities only for one health check unless necessary.
Liveness and Readiness
For production systems, you may create:
/health/live
/health/ready
Liveness:
Is the Go process alive?
Readiness:
Can this instance currently handle requests?
Readiness may depend on critical resources such as a database connection.
Graceful Shutdown Inside Docker
Containers receive termination signals when they are stopped.
Your Go application should handle them properly.
Example:
server :=
&http.Server{
Addr:
":8080",
Handler:
mux,
}
Run the server:
go func() {
if err :=
server.ListenAndServe();
err != nil &&
err != http.ErrServerClosed {
log.Fatal(err)
}
}()
Listen for termination:
stop :=
make(
chan os.Signal,
1,
)
signal.Notify(
stop,
os.Interrupt,
syscall.SIGTERM,
)
<-stop
Shutdown:
ctx, cancel :=
context.WithTimeout(
context.Background(),
10*time.Second,
)
defer cancel()
if err :=
server.Shutdown(ctx);
err != nil {
log.Printf(
"shutdown error: %v",
err,
)
}
This allows active requests time to complete before the container exits.
Use Exec Form for ENTRYPOINT and CMD
Prefer:
ENTRYPOINT ["/server"]
over:
ENTRYPOINT /server
The JSON/exec form allows signals to reach the Go process more directly.
This helps graceful shutdown work correctly.
Run as a Non-Root User
Production containers should generally avoid running the application as root when it is unnecessary.
For example, a distroless non-root image:
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=builder \
/app/server \
/server
USER nonroot:nonroot
ENTRYPOINT ["/server"]
Some base images already define a non-root user.
Check the documentation for the image you choose.
Docker Container Security
Important practices include:
Use trusted base images
Use minimal runtime images
Run as non-root
Never bake secrets into images
Keep dependencies updated
Pin important versions
Scan images for vulnerabilities
Avoid unnecessary Linux capabilities
Use read-only filesystems when possible
Limit CPU and memory
Avoid exposing unnecessary ports
Keep build and runtime stages separate
Do Not Copy Unnecessary Files
Bad:
COPY . .
in the final runtime stage can accidentally include:
Source code
.env files
Git metadata
Tests
Documentation
Development files
Secrets
With a multi-stage build, copy only what the application needs.
For example:
COPY --from=builder \
/app/server \
/server
Pin Docker Image Versions
Using:
FROM golang:latest
can make builds less predictable because latest changes.
Prefer a deliberate version:
FROM golang:1.25
For stronger reproducibility, production systems may pin image digests as well.
Keep Docker Images Small
Smaller images can provide:
Faster image pulls
Less storage usage
Fewer unnecessary packages
Reduced attack surface
Use:
Multi-stage builds
Minimal runtime images
.dockerignore
Only required runtime files
Appropriate compiler flags
But do not sacrifice required functionality merely to achieve the smallest possible image.
Check Docker Image Size
Run:
docker images
You can compare:
Full Go image
vs
Alpine runtime
vs
Distroless runtime
vs
Scratch
Multi-stage builds can significantly reduce final image size.
Docker Build Cache
Docker caches build layers.
A Dockerfile like:
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o server .
is usually better for caching than:
COPY . .
RUN go mod download
RUN go build -o server .
Why?
Your dependencies change less frequently than your source code.
BuildKit Cache for Go Modules
For more advanced builds, BuildKit cache mounts can speed up repeated builds.
Example:
RUN --mount=type=cache,target=/go/pkg/mod \
go mod download
And:
RUN --mount=type=cache,target=/root/.cache/go-build \
go build -o server .
This can improve CI/CD and local build performance.
Development with Docker
Production Docker images and development containers have different goals.
Production:
Small
Immutable
Secure
Minimal
Optimized
Development:
Fast iteration
Source mounts
Debugging tools
Automatic reload
Do not force one Dockerfile or container setup to solve every environment if separate configurations are clearer.
Live Reload During Development
Normally, changing Go source code requires rebuilding or restarting the application.
Development tools can watch files and restart the application automatically.
A development Compose setup might mount:
volumes:
- .:/app
Then a development-only reload tool can run inside the container.
Keep such tooling out of the final production image.
Docker Logs
Go applications should generally log to:
stdout
stderr
Docker captures these streams.
View:
docker logs go-api
Follow:
docker logs -f go-api
Avoid writing important application logs only to files inside ephemeral containers unless you have a deliberate log collection strategy.
Structured Logging
Go provides:
log/slog
Example:
slog.Info(
"server started",
"port",
8080,
)
Error:
slog.Error(
"database query failed",
"error",
err,
)
Structured logs are easier for production logging systems to process.
Container Resource Limits
Containers should not always have unlimited access to host resources.
Example:
docker run \
--memory=512m \
--cpus=1 \
go-docker-app
This limits the container to approximately:
512 MB memory
1 CPU
Resource limits are especially important when multiple services share infrastructure.
Docker Restart Policies
You can configure restart behavior:
docker run \
-d \
--restart unless-stopped \
go-docker-app
Common policies include:
no
on-failure
always
unless-stopped
Managed orchestration platforms usually provide their own restart and health-management behavior.
Docker Tags
Instead of using only:
go-docker-app:latest
use versioned tags:
go-docker-app:1.0.0
go-docker-app:1.1.0
go-docker-app:2.0.0
Build:
docker build \
-t go-docker-app:1.0.0 \
.
Versioned images make deployments and rollbacks easier to understand.
Docker Registry
To deploy an image to another machine, it is commonly pushed to a container registry.
Flow:
Source Code
|
v
Docker Build
|
v
Docker Image
|
v
Container Registry
|
v
Production Server
Registries can be:
Public
Private
Cloud-managed
Self-hosted
CI/CD with Go and Docker
A common pipeline looks like:
Git Push
|
v
Run Go Tests
|
v
Run Static Checks
|
v
Build Docker Image
|
v
Scan Image
|
v
Push Image
|
v
Deploy
Example Go test command:
go test ./...
Race detector:
go test -race ./...
Static analysis:
go vet ./...
Build Image in CI
Example command:
docker build \
-t my-go-api:${VERSION} \
.
Then push it to your configured registry.
The exact authentication and push commands depend on the registry provider.
Database Migrations with Docker
Your Go application may require schema migrations.
A common deployment flow is:
Build Image
|
v
Deploy
|
v
Run Migration
|
v
Start/Update Application
Or migrations may run as a separate controlled job.
Avoid blindly running incompatible schema changes from every application instance simultaneously.
Docker and Go Microservices
Docker becomes especially useful with microservices.
Example:
User Service
|
+---- Container
Product Service
|
+---- Container
Order Service
|
+---- Container
Payment Service
|
+---- Container
Each service can have:
Its own image
Its own version
Its own environment variables
Its own resource limits
Its own deployment lifecycle
Docker Compose for Microservices
A local development setup might look like:
services:
user-service:
build:
context: ./user-service
product-service:
build:
context: ./product-service
order-service:
build:
context: ./order-service
postgres:
image: postgres
redis:
image: redis
Compose is extremely useful for running a multi-service environment locally.
Docker vs Virtual Machines
Virtual machines virtualize hardware and typically run a full guest operating system.
Containers share the host operating system kernel while isolating processes.
Conceptually:
Virtual Machines
Hardware
|
Host OS
|
Hypervisor
|
Guest OS
|
Application
Containers:
Hardware
|
Host OS
|
Container Runtime
|
Containers
|
Applications
Containers are generally lighter and faster to start than full virtual machines.
Docker vs Kubernetes
Docker helps package and run containers.
Kubernetes helps orchestrate many containers across infrastructure.
Docker:
Build image
Run container
Manage local containers
Kubernetes:
Deploy containers
Scale replicas
Restart failed workloads
Service discovery
Rolling updates
Configuration
Secrets
Load balancing integration
You do not need Kubernetes to start using Docker with Go.
Debugging Go Docker Containers
If a container exits unexpectedly:
docker ps -a
Then inspect logs:
docker logs <container-name>
Inspect configuration:
docker inspect <container-name>
Open a Shell Inside a Container
For images containing a shell:
docker exec \
-it \
<container-name> \
sh
For Bash-based images:
docker exec \
-it \
<container-name> \
bash
Remember:
scratch and distroless images usually do not contain a shell.
That is a security advantage but changes how debugging is performed.
Common Error: Connection Refused
Suppose Go reports:
connection refused
Check:
Is the database running?
Are both containers on the same network?
Is the hostname correct?
Is the port correct?
Is the database ready?
Is the connection string correct?
Inside Docker, do not automatically use localhost for another container.
Common Error: Executable Not Found
If you see an error similar to:
/server: no such file or directory
possible causes include:
Binary copied to wrong path
Wrong ENTRYPOINT
Wrong operating system
Wrong CPU architecture
Missing dynamic libraries
cgo-related dependencies
Check how the binary was built and what the runtime image contains.
CPU Architecture Problems
If building for a specific Linux server, architecture matters.
Examples:
amd64
arm64
You can build Go directly for an architecture:
GOOS=linux \
GOARCH=amd64 \
go build .
or:
GOOS=linux \
GOARCH=arm64 \
go build .
Docker also supports multi-platform build workflows.
Multi-Architecture Images
Modern applications may need to run on both:
linux/amd64
linux/arm64
Docker Buildx can build multi-platform images.
For example:
docker buildx build \
--platform \
linux/amd64,linux/arm64 \
-t your-registry/go-api:1.0.0 \
--push \
.
This is useful when supporting different server architectures.
Go Templates and Static Files in Docker
If your Go web application uses:
templates/
static/
and they are not embedded into the binary, you must copy them into the runtime image.
Example:
COPY --from=builder \
/app/server \
/app/server
COPY templates \
/app/templates
COPY static \
/app/static
Otherwise, your application may compile correctly but fail to find its files at runtime.
Use Go Embed Instead
You can embed files:
import "embed"
//go:embed templates/*
var templateFiles embed.FS
You can also embed static assets.
This can simplify your container because fewer runtime files need to be copied.
Production-Ready Dockerfile Example
A practical Dockerfile could look like:
FROM golang:1.25 AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 \
GOOS=linux \
go build \
-trimpath \
-ldflags="-s -w" \
-o /out/server \
./cmd/api
FROM gcr.io/distroless/static-debian12:nonroot
WORKDIR /app
COPY --from=builder \
/out/server \
/app/server
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/app/server"]
If your application entry point is in the project root rather than ./cmd/api, change the build command accordingly.
Production Go Server Configuration
Docker cannot replace correct application configuration.
Your Go HTTP server should still use sensible timeouts.
Example:
server :=
&http.Server{
Addr:
":8080",
Handler:
mux,
ReadHeaderTimeout:
5 * time.Second,
ReadTimeout:
10 * time.Second,
WriteTimeout:
15 * time.Second,
IdleTimeout:
60 * time.Second,
}
You should also implement graceful shutdown.
Production Architecture Example
A real deployment might look like:
Internet
|
v
Load Balancer
|
+----------+----------+
| |
v v
Go Container 1 Go Container 2
| |
+----------+----------+
|
v
PostgreSQL
|
v
Redis
The Go containers should ideally be stateless where possible.
Persistent data should live in dedicated systems such as databases or object storage.
Docker Best Practices for Go
For production Go applications:
Use multi-stage builds
Use a minimal runtime image
Run as non-root
Use .dockerignore
Keep secrets outside images
Use environment-based configuration
Pin deliberate base image versions
Configure HTTP timeouts
Implement graceful shutdown
Add health endpoints
Log to stdout/stderr
Use structured logs
Persist database data outside app containers
Use Docker networks for service communication
Set resource limits
Test the exact image before deployment
Scan images for vulnerabilities
Use versioned image tags
Keep images immutable
Common Beginner Mistakes
Avoid:
Running the full Go SDK image in production unnecessarily
Using localhost to connect to another container
Hardcoding database passwords
Copying .env into production images
Ignoring .dockerignore
Running everything as root
Using latest everywhere
Keeping database data only inside a disposable container
Forgetting port mappings
Assuming EXPOSE publishes ports
Ignoring graceful shutdown
Ignoring server timeouts
Not handling database startup delays
Copying unnecessary source files into runtime images
Creating huge images
Ignoring CPU architecture
Using Docker without understanding networking
Go + Docker Development Workflow
A practical workflow is:
Write Go Code
|
v
Run Locally
|
v
Run Tests
|
v
Create Dockerfile
|
v
Build Image
|
v
Run Container
|
v
Add Database
|
v
Create Compose Stack
|
v
Test Complete Environment
|
v
Push Image
|
v
Deploy
|
v
Monitor
Go with Docker Learning Roadmap
If you are a beginner, learn in this order:
Go Basics
↓
Go Modules
↓
Go Web Server
↓
REST API
↓
Docker Basics
↓
Dockerfile
↓
Docker Images
↓
Docker Containers
↓
Port Mapping
↓
Environment Variables
↓
Multi-Stage Builds
↓
Docker Networks
↓
Docker Volumes
↓
Docker Compose
↓
PostgreSQL/MySQL
↓
Health Checks
↓
Security
↓
CI/CD
↓
Container Registry
↓
Production Deployment
↓
Kubernetes
Practice Project
A good project for learning Go with Docker is a Todo REST API.
Build:
Go REST API
|
v
PostgreSQL
Features:
Create user
Login
JWT authentication
Create todo
Get todos
Update todo
Delete todo
Then Dockerize:
Go API
PostgreSQL
Redis
using Docker Compose.
Add:
Environment variables
Persistent volumes
Health checks
Graceful shutdown
Database migrations
Structured logging
Multi-stage builds
Non-root container
This gives you practical experience with a realistic Go deployment workflow.
Frequently Asked Questions
Can Go run inside Docker?
Yes.
Go applications work very well in Docker and can be compiled into small Linux binaries for containerized deployment.
Do I need Docker to run Go?
No.
Go applications can run directly as compiled binaries.
Docker is useful for packaging, deployment, isolation, and consistent environments.
Why use Docker if Go already creates a binary?
A Go binary simplifies deployment, but Docker additionally packages the runtime environment, networking configuration, filesystem expectations, and deployment unit into a consistent image.
Which Docker image is best for Go?
There is no single best image.
Use the official Go image for building.
For runtime, common choices include:
scratch
Alpine
Distroless
Choose based on runtime dependencies and security requirements.
Should I use the full Go image in production?
Usually not.
A multi-stage build lets you compile using the Go image and copy only the required binary into a smaller runtime image.
What is a multi-stage Docker build?
It uses multiple FROM stages.
One stage builds the Go application.
Another stage contains only the files required to run it.
Why does my Go container not connect to PostgreSQL on localhost?
Because localhost inside the Go container refers to the Go container itself.
If PostgreSQL is another Compose service called db, use:
db:5432
instead.
Can Docker Compose run Go and PostgreSQL together?
Yes.
This is one of the most common local development setups.
Can I use MySQL instead of PostgreSQL?
Yes.
Go and Docker work with PostgreSQL, MySQL, Redis, MongoDB, and many other data stores.
Should database data be stored inside the container?
Persistent database data should generally use a Docker volume or an external managed database rather than relying on a disposable container filesystem.
Can I use .env with Docker?
Yes.
Docker can load environment variables from an environment file.
Do not commit sensitive production environment files to public repositories.
Should secrets be stored in a Dockerfile?
No.
Do not bake passwords, API keys, JWT signing keys, or database credentials into Docker images.
Can Go Docker containers run on Kubernetes?
Yes.
Docker-compatible OCI container images can be deployed through Kubernetes and many other container platforms.
Do I need Kubernetes after learning Docker?
Not necessarily.
Many applications can run successfully using simpler managed container services or virtual machines.
Learn Kubernetes when your deployment and orchestration requirements justify it.
How can I reduce my Go Docker image size?
Use:
Multi-stage builds
Minimal runtime image
CGO_ENABLED=0 when compatible
-trimpath
Appropriate linker flags
.dockerignore
Only required runtime files
Should a Go Docker container run as root?
Usually not.
Run as a non-root user whenever the application does not require root privileges.
How should Go applications log inside Docker?
Logging to stdout and stderr is generally preferred.
Docker and container platforms can then collect the logs.
Conclusion
Go and Docker work extremely well together.
Go provides:
Fast compiled binaries
Strong performance
Concurrency
Simple deployment
Small runtime requirements
Docker provides:
Consistent environments
Isolation
Portable images
Networking
Volumes
Deployment packaging
A basic workflow starts with:
Go Source Code
|
v
go build
|
v
Go Binary
|
v
Docker Image
|
v
Container
For production applications, a better approach is:
Go Source
|
v
Builder Stage
|
v
Optimized Go Binary
|
v
Minimal Runtime Image
|
v
Non-Root Container
|
v
Production
When multiple services are involved:
Docker Network
|
+----------+----------+
| | |
v v v
Go API PostgreSQL Redis
Docker Compose can make this environment easy to reproduce locally.
The most important concepts to learn are not just docker build and docker run. You should understand multi-stage builds, networking, environment variables, volumes, database persistence, health checks, graceful shutdown, security, image optimization, logging, and deployment.
Start by Dockerizing one simple Go web server. Then add PostgreSQL or MySQL with Docker Compose. Once you are comfortable with that workflow, move into CI/CD, registries, production deployment, microservices, and eventually container orchestration when your application actually needs it.
With these fundamentals, you can build Go applications that are easier to develop, test, package, and deploy consistently across environments.
