How to Create a Docker Image: A Practical Guide
Docker images are the foundation of containerized applications. Whether you're packaging a web app, a microservice, or a data pipeline, knowing how to build a Docker image is a core skill in modern software development and deployment. Here's what the process actually involves — and why the right approach varies considerably depending on your setup.
What Is a Docker Image?
A Docker image is a read-only template that contains everything needed to run an application: the operating system layer, runtime environment, application code, libraries, and configuration. When you run an image, Docker creates a live container from it.
Images are built in layers. Each instruction in your build file adds a layer on top of the previous one. Docker caches these layers, which means rebuilds are often fast — only the layers that changed get rebuilt.
Images are stored locally on your machine or pushed to a container registry (like Docker Hub, Amazon ECR, or GitHub Container Registry) so others can pull and run them.
The Core Tool: The Dockerfile
The primary way to create a Docker image is by writing a Dockerfile — a plain text file with a specific set of instructions that Docker reads top to bottom.
Essential Dockerfile Instructions
| Instruction | What It Does |
|---|---|
FROM | Sets the base image (e.g., ubuntu, node, python) |
WORKDIR | Sets the working directory inside the container |
COPY / ADD | Copies files from your host machine into the image |
RUN | Executes a command during the build (e.g., install packages) |
ENV | Sets environment variables |
EXPOSE | Documents which port the app listens on |
CMD / ENTRYPOINT | Defines the default command when the container starts |
A minimal example for a Python web app might look like this:
FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-requires dependencies-r requirements.txt COPY . . CMD ["python", "app.py"] The FROM line is always first. Choosing a slim or alpine base image (like python:3.11-slim) keeps your final image smaller — which matters for storage, transfer speed, and security surface area.
Building the Image
Once your Dockerfile is written, you build the image using the Docker CLI:
docker build -t my-app:1.0 . -ttags the image with a name and optional version.tells Docker to use the current directory as the build context — the set of files it can access during the build
Docker will execute each instruction in sequence, showing output for each step. On success, you'll have a local image you can verify with:
docker images Key Variables That Affect Your Build 🔧
Creating a Docker image isn't one-size-fits-all. Several factors shape how you structure your Dockerfile and what choices make sense.
Base Image Choice
Your starting point matters significantly. Options range from full OS images (larger, more compatible) to distroless or scratch images (minimal, harder to debug). Alpine-based images are popular for being small, but they use musl libc instead of glibc, which occasionally causes compatibility issues with certain binaries or Python packages.
Multi-Stage Builds
For compiled languages (Go, Java, Rust, C++) or apps with heavy build dependencies, multi-stage builds let you use one image to compile and a separate, smaller image to run. The final image ships without compilers or dev tools — just the built artifact.
FROM golang:1.21 AS builder WORKDIR /app COPY . . RUN go build -o myapp FROM alpine:3.18 COPY --from=builder /app/myapp /myapp CMD ["/myapp"] This approach can reduce final image size dramatically.
Build Context Size
The build context is everything Docker sends to the daemon at build time. If your project folder includes large files (logs, datasets, node_modules), your builds will be slow. A .dockerignore file works like .gitignore — list what to exclude, and Docker won't send those files.
Architecture Compatibility 🖥️
If you're building on an Apple Silicon Mac (ARM64) and deploying to an x86 server, you may need to build for multiple platforms. The docker buildx command supports multi-platform builds, letting you target linux/amd64, linux/arm64, or both simultaneously.
After the Build: Tagging and Pushing
A locally built image is useful for testing, but deployment usually means pushing to a registry:
docker tag my-app:1.0 yourusername/my-app:1.0 docker push yourusername/my-app:1.0 From there, any machine with Docker installed can pull and run it. In CI/CD pipelines, this build-tag-push sequence is typically automated.
Where Experience Level Changes the Outcome
A developer building their first image typically starts with a broad base image, includes everything in a single stage, and troubleshoots interactively. That's a perfectly reasonable starting point.
As requirements grow — smaller images, faster CI builds, tighter security, multi-arch support — the Dockerfile becomes more deliberate. Layer ordering matters (put instructions that change frequently later to maximize cache hits). Package versions get pinned. Non-root users get specified with USER. Health checks get added with HEALTHCHECK.
The gap between a functional image and a production-hardened image is real, and how much of it matters depends entirely on what you're building, where it runs, and who maintains it.
Your specific stack, deployment environment, team conventions, and performance requirements are what determine which of these techniques apply — and in what order they're worth addressing.