Complete guide to container technology β through BuildKit and Swarm
π³ Docker Complete Guide
From what fundamentally separates a container from a VM, through image layer structure, Dockerfiles and multi-stage builds, multi-platform builds with BuildKit/buildx, networking, volumes, Docker Compose, Docker Swarm orchestration, and container security and vulnerability scanning β the practical Docker knowledge you need to have down before moving on to Kubernetes.
Beginner
Updated Oct 1, 2026
~14 min read
18 sections
11 code examples
Web IDE lab included
π³
Docker Web IDE
Run code in the browser with nothing to install and learn through step-by-step examples.
From what fundamentally separates a container from a VM, through image layer structure, Dockerfiles and multi-stage builds, multi-platform builds with BuildKit/buildx, networking, volumes, Docker Compose, Docker Swarm orchestration, and container security and vulnerability scanning β the practical Docker knowledge you need to have down before moving on to Kubernetes. Rather than listing concepts, this guide is organized so you can follow the content in the order you have to make decisions on a real project.
Key perspective
Infrastructure / operations
Rather than memorizing install commands, understand the order in which traffic, runtime, observability, and incident response connect.
Standardizing development environmentsCI/CD pipelines & multi-platform buildsDocker Swarm orchestrationPackaging microservices
Architecture diagrams
To make what you read stick, it helps to capture the flow as a picture first. The two diagrams below are reference maps you can keep coming back to while learning Docker.
Learning flow
Rendering diagramβ¦
Architecture view
Rendering diagramβ¦
What is a container?
When you first open Docker, the big picture matters more than individual commands. This section starts with the problems the concepts ahead were created to solve.
A container is a technology that bundles an application together with the libraries, runtime, and configuration it needs to run into a single isolated unit. Unlike a virtual machine (VM), which virtualizes the hardware itself and boots an entire guest OS, a container shares the host OS kernel as-is and is isolated only at the process level. That is why a VM takes tens of seconds to minutes to boot, while a container, much like starting one process on a kernel that is already running, starts in about a second.
Rendering diagramβ¦
Aspect
VM
Container
Unit of isolation
The whole OS (including the guest OS)
The process (shared kernel)
Startup speed
Tens of seconds to minutes
About 1 second
Image size
Usually in GB
Usually in MB
Density
A few to tens per server
Tens to hundreds per server
Installation
Here you look at Installation alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
On macOS/Windows, Docker Desktop installs Docker Engine, the CLI, and Compose in one go. On Linux servers, Docker Engine is often installed directly, without Docker Desktop.
BASH
# Docker Desktop (macOS/Windows): https://docker.com/get-started# Linux β install Docker Enginecurl -fsSL https://get.docker.com | shsudo usermod -aG docker $USER # run docker commands without sudo (requires logging in again)docker --versiondocker info # check the daemon connection, storage driver, and so on
Basic commands and the container lifecycle
Here you look at Basic commands and the container lifecycle alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
An image is a read-only template for creating containers, and a container is a running instance of that image. You can start any number of containers from the same image, and deleting a container leaves the original image intact.
BASH
docker pull nginx # download the imagedocker run -d -p 80:80 --name web nginx # run in the background + give it a namedocker ps # list running containersdocker ps -a # list everything, including stopped containersdocker logs -f web # follow the logs in real timedocker exec -it web bash # get a shell inside a running containerdocker stop web # graceful stop (SIGTERM)docker rm web # delete the container (must be stopped)docker rmi nginx # delete the image
Command
Role
docker pull
Downloads an image from a registry (Docker Hub and others)
docker run
Creates and starts a container from an image
docker stop / start
Stops a running container / restarts a stopped one
docker rm / rmi
Deletes a container / deletes an image
Images and layer structure
Here you look at Images and layer structure alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
A Docker image is a set of read-only layers, one stacked for each instruction in the Dockerfile. If the same layer is already cached, Docker reuses it instead of rebuilding it, so the later in the Dockerfile you put content that changes often, the faster the build.
Rendering diagramβ¦
Writing a Dockerfile & multi-stage builds
Here you look at Writing a Dockerfile & multi-stage builds alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
A multi-stage build separates the tools needed only for building (compilers, devDependencies) from the output needed to actually run, into different stages. Only the last stage remains in the final image, so you get a much lighter image containing no build tools at all.
DockerfileDOCKERFILE
# Stage 1: build only β includes devDependencies and the full sourceFROM node:20-alpine AS builderWORKDIR /appCOPY package*.json ./RUN npm ciCOPY . .RUN npm run build# Stage 2: runtime only β copies just the build output and production dependenciesFROM node:20-alpine AS runnerWORKDIR /appENV NODE_ENV=productionCOPY package*.json ./RUN npm ci --omit=devCOPY --from=builder /app/dist ./distUSER nodeEXPOSE 3000CMD ["node", "dist/server.js"]
Instruction
Role
FROM
Sets the base image (AS can name the stage)
COPY --from=builder
Selectively copies only the output of an earlier stage
RUN
Runs once at image build time (creates a layer)
CMD vs ENTRYPOINT
CMD is easily overridden wholesale at run time; ENTRYPOINT is used for a fixed executable, with CMD passing only the default arguments
BuildKit & buildx β multi-platform builds
Here you look at BuildKit & buildx β multi-platform builds alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
BuildKit is the next-generation build engine built in by default since Docker 18.09. It analyzes the steps of a Dockerfile as a dependency graph, runs unrelated steps in parallel, and reuses the cache at a much finer grain (per mount rather than per layer). buildx is the plugin that extends BuildKit on the CLI, and its signature feature is the multi-platform build, which lets an image built on an Apple Silicon Mac run unchanged on x86 servers.
Rendering diagramβ¦
Dockerfile β avoiding dependency reinstalls with a cache mountDOCKERFILE
# syntax=docker/dockerfile:1FROM node:20-alpineWORKDIR /appCOPY package*.json ./# Keep the npm cache in a separate cache mount rather than a layer β it does not end up in the image layers# yet is reused across builds, so packages already fetched are not downloaded again even when package.json changesRUN --mount=type=cache,target=/root/.npm \ npm ciCOPY . .CMD ["node", "server.js"]
BASH
# Create & activate a buildx builder (first time only)docker buildx create --name multiarch --use# Build several architectures at once and push straight to the registrydocker buildx build \ --platform linux/amd64,linux/arm64 \ -t myrepo/myapp:1.0.0 \ --push .# Store a remote cache in the registry β reuse the cache even where CI runners start fresh every timedocker buildx build \ --cache-to type=registry,ref=myrepo/myapp:buildcache \ --cache-from type=registry,ref=myrepo/myapp:buildcache \ -t myrepo/myapp:1.0.0 --push .
Feature
Legacy builder
BuildKit/buildx
How builds run
Builds layers sequentially, one at a time
Analyzes the dependency graph and runs unrelated steps in parallel
Cache granularity
Caches only whole layers
Caches specific directories precisely with RUN --mount=type=cache
Passing secrets
Passing them through ARG/ENV risks leaving traces in image layers
Passing them with --secret leaves nothing in the final image
Multi-platform
Build per architecture, then manage manifests by hand
Build + push in one go with buildx build --platform
Docker networking
Here you look at Docker networking alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
A container run with no options is connected to the bridge network by default. Containers on the same bridge network can find each other using the service name like DNS, and to reach a container from the host you must map a port explicitly with -p.
Rendering diagramβ¦
Network driver
Use
bridge (default)
Communication between containers on the same host β most local/single-server environments
host
The container uses the host network directly (no port mapping needed, weaker isolation)
none
Networking fully disabled β for batch jobs and other cases that need no communication
overlay
Container communication across several hosts β Docker Swarm/multi-host environments
Volumes and data persistence
Here you look at Volumes and data persistence alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Deleting a container also deletes the files written inside it. If data must outlive the container lifecycle, like a database or uploaded files, you must separate it onto the host with a volume or a bind mount.
Rendering diagramβ¦
Method
Description
Mostly used for
Named Volume
Storage managed by Docker (-v pgdata:/data)
Data owned by the container, such as databases and application state
Bind Mount
Connects a specific host path as-is (-v ./src:/app/src)
Reflecting source code changes live during local development
tmpfs
Stored only in memory, gone when the container stops
Sensitive temporary data, caches
Multi-container setups with Docker Compose
Here you look at Multi-container setups with Docker Compose alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Docker Compose is a tool for defining an application made of several containers in a single YAML file and starting it all at once. Using depends_on together with healthcheck lets you control the order so the API container starts only after the database is really ready to accept requests.
Here you look at Docker Swarm β architecture alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Docker Swarm is the orchestration mode built into Docker Engine; with no separate installation, a single docker swarm init line ties several servers into one cluster. The cluster is divided into manager nodes, which manage the cluster state (which services should be running, how many of each, and so on) with the Raft consensus algorithm, and worker nodes, which actually run the containers.
Rendering diagramβ¦
BASH
# Initialize the cluster on the first manager nodedocker swarm init --advertise-addr 192.168.1.10# Join worker nodes to the cluster with the printed tokendocker swarm join --token SWMTKN-1-xxxxx 192.168.1.10:2377# The token for joining additional managers is issued separatelydocker swarm join-token manager# Check the list of cluster nodes & their rolesdocker node ls
Item
Manager
Worker
Role
Stores cluster state, makes scheduling decisions, answers the API
Only runs the tasks (containers) assigned to it
Fault tolerance
A majority (quorum) of the N managers must be alive for the cluster to work
If one worker dies, the managers reschedule its tasks on other nodes
Recommended count
An odd number such as 3, 5, or 7 β tolerates up to (N-1)/2 failures
Scale freely to match the workload
Swarm service deployment & rolling updates
Here you look at Swarm service deployment & rolling updates alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
In Swarm, instead of docker run you use docker service create to declare "how many replicas to maintain". If one task (replica) dies, Swarm automatically places a new task on another node to restore the replica count, and when updating the image it replaces a few at a time in sequence rather than taking everything down at once.
Rendering diagramβ¦
BASH
# Create a service β 3 replicas, exposed on port 80 across the whole cluster (ingress mesh)docker service create --name web --replicas 3 -p 80:80 nginx:1.27# Scale immediately to match the loaddocker service scale web=6# Rolling image update β replace 1 at a time, at 10-second intervalsdocker service update \ --image nginx:1.28 \ --update-parallelism 1 \ --update-delay 10s \ --update-failure-action rollback \ web# If the deploy just made has a problem, roll back to the previous version at oncedocker service rollback web# Check the service state & which node each task is placed ondocker service ps web
Flag
Meaning
--replicas
The number of tasks (containers) to maintain β Swarm always recovers automatically to match it
--update-parallelism
How many tasks to replace at the same time
--update-delay
How long to wait between replacement batches β gives the health checks time to settle
--update-failure-action
What to do when an update fails (pause or rollback)
Docker Stack & Swarm vs Kubernetes
Here you look at Docker Stack & Swarm vs Kubernetes alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Docker Stack deploys a Compose file you have already written to a Swarm cluster as-is. It sets up an overlay network automatically so services can talk to each other even when placed across several nodes, and sensitive values such as passwords can be managed separately as secrets instead of being baked into the image.
Rendering diagramβ¦
docker-compose.yml (for Stack deployment)YAML
services: api: image: myrepo/api:1.0.0 ports: ["80:3000"] deploy: replicas: 3 update_config: parallelism: 1 delay: 10s restart_policy: condition: on-failure secrets: - db_password db: image: postgres:16-alpine deploy: placement: constraints: ["node.role == manager"] # pin the data to a specific node secrets: - db_password environment: POSTGRES_PASSWORD_FILE: /run/secrets/db_passwordsecrets: db_password: external: true
BASH
# Register the secret in the cluster first (the value is not committed to Git)echo "s3cr3t" | docker secret create db_password -# Deploy the Compose file as a Stack, unchangeddocker stack deploy -c docker-compose.yml myappdocker stack services myapp # replica status per servicedocker stack ps myapp # which node each task was placed on
Aspect
Docker Swarm
Kubernetes
Installation & learning curve
Built into Docker Engine β start immediately with a few commands
Needs a separate installation, with far more concepts (Pod, Service, Ingress, and so on)
Suitable scale
Tens of nodes, simple service layouts
Hundreds to thousands of nodes, complex multi-team operations
Ecosystem
Compose files can be reused; the ecosystem is relatively small
An overwhelmingly large ecosystem: Helm, Operators, service meshes, and more
When to choose
When you want to get running fast and minimize the operational burden
When you need scalability, fine-grained control, and integration with industry-standard tools
Container security & vulnerability scanning
Here you look at Container security & vulnerability scanning alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
By default a container runs as the root user and shares the kernel with the host. Because of these two traits, lowering the account that runs inside the image and reducing unnecessary privileges and attack surface matter even more than in a VM environment. On top of that, scanning the base image for known vulnerabilities (CVEs) before deployment is an essential step.
BASH
# Docker Scout β view a summary of image vulnerabilities (built into Docker Desktop)docker scout quickview myrepo/myapp:1.0.0# Detailed CVE list (by severity)docker scout cves myrepo/myapp:1.0.0# Recommends whether the base image can be switched to a safer versiondocker scout recommendations myrepo/myapp:1.0.0# In the CI pipeline: fail the build when there are Critical/High vulnerabilitiesdocker scout cves --exit-code --only-severity critical,high myrepo/myapp:1.0.0
Item
What not to do
Do this instead
Run-as account
Running as root unchanged
Set USER in the Dockerfile (e.g. USER node)
Base image
An unnecessarily large full OS image
Minimal images such as alpine or distroless
Secret management
Hardcoding passwords in ENV or Dockerfile ARG
Secrets Manager/environment variable injection, the --secret build option
Image vulnerabilities
Deploying without verification
Scan in CI with docker scout, trivy, and similar tools
Best practices
This section covers Best practices from a practical perspective. Instead of memorizing the concept, focus on the situations in which you would reach for it.
Summed up as a checklist of what you must cover when applying everything so far in practice:
Docker practical design
Docker practical design is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
With Docker, building a reproducible and safe runtime matters more than making the image small. Separate the build stage, runtime user, secrets, and volumes.
Decision point
Question to ask
Practical guideline
Boundaries
Which parts of the Docker code are most likely to change?
Separate input/output, configuration, external integrations, and the core rules.
State
Where is state created and where does it go away?
Make the owner and lifecycle of state visible in the code.
Failure
What does the caller receive on failure?
Decide the timeout, fallback, and error contract first.
Docker operating standards
This section covers Docker operating standards from a practical perspective. Instead of memorizing the concept, focus on the situations in which you would reach for it.
Manage the image cache, layer size, healthcheck, restart policy, log driver, and resource limits.
Docker verification strategy
Docker verification strategy is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
Include Dockerfile linting, vulnerability scans, reproducible builds, and container smoke tests.
Quality axis
How to verify
Definition of done
Correctness
Automate the normal/failure cases.
The core scenarios pass reproducibly.
Regression prevention
When fixing a bug, leave the same case behind as a test.
The same failure is not deployed again.
Operability
Check the logs, metrics, and alerts.
There is a path for tracing the cause when a problem occurs.
Docker: frequently asked questions
What is the difference between Docker and a virtual machine (VM)?
A virtual machine virtualizes hardware and runs a whole operating system of its own, while a container shares the host kernel and isolates only the processes. That is why containers start in seconds and their images are small. Because the kernel is shared, a VM gives stronger isolation. Use a VM when you need a different operating system kernel or strong isolation, and use containers when you want to start and deploy many copies of the same application quickly.
What is the difference between a Docker image and a container?
An image is a read-only template that bundles an application with the files it needs to run, and a container is a running instance of that image. One image can start many containers. Files changed inside a container live only in that container's writable layer, so they disappear when the container is removed. Data you need to keep goes in a volume.
Data disappears when I delete a container. How do I keep it?
Create a volume and mount it at the container's data path. For example, mounting a named volume with docker run -v mydata:/var/lib/postgresql/data keeps the data even after the container is removed and recreated. When you want a container to see a source folder on the host during development, use a bind mount. Commands that also remove volumes, such as docker compose down -v, delete the data, so use them deliberately.
Should I use Docker Compose or Kubernetes?
Docker Compose is the simple choice for running several containers together on one server or a development machine. Kubernetes is for running across several servers with self-healing, zero-downtime deployments, and scaling with load. A common setup is Compose for local development and Kubernetes in production; the services, environment variables, and volumes you define in Compose map to Deployments, ConfigMaps, and PersistentVolumeClaims in Kubernetes.
Next steps
This section covers Next steps from a practical perspective. Instead of memorizing the concept, focus on the situations in which you would reach for it.
π
After Docker comes Kubernetes
Once you know how to build one container well, the next problem is running many containers reliably across many servers β automatic restarts on failure, autoscaling with traffic, and zero-downtime deployment are hard to handle with Docker alone.