Container Basics

This page is a one-page tour of the core objects you touch every day - images, containers, registries, and the orchestrator - and how they connect.

Every example is minimal and runnable so you can build the mental map quickly.

Prerequisites

Docker Engine 29.6.1 with BuildKit (default) for building and running locally.
Compose v2 (docker compose, not docker-compose) for multi-container dev.
kubectl matching your cluster (Kubernetes 1.36.2 here) for the orchestrator examples.
A local cluster (kind, minikube, or k3d) if you want to run the pod examples.

Quick check that your toolchain is live:

docker version --format '{{.Server.Version}}'
kubectl version --client -o yaml | grep gitVersion

Basic Examples

1. Build an image from a Dockerfile

An image is a read-only, layered filesystem plus config; a Dockerfile is the recipe.

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
USER node
CMD ["node", "server.js"]

FROM picks a base layer; each instruction adds a cache-friendly layer on top.
COPY package*.json before the source lets npm ci stay cached when only app code changes.
USER node runs the app as a non-root user, a security default worth setting early.
CMD is the default process; it becomes PID 1 in the container.

2. Build and tag it

Tags name an image so you and the registry can find it.

docker build -t myapp:1.0.0 .
docker images myapp

-t name:tag sets a human tag; prefer semantic, immutable tags over latest.
The build runs on BuildKit by default, which parallelizes and caches layers.
The same content also has an immutable digest (sha256:...) you can pin later.

3. Run a container

A container is a running instance of an image - an isolated process with that image's filesystem.

docker run --rm -p 8080:3000 --name web myapp:1.0.0

-p 8080:3000 maps host port 8080 to the container's port 3000.
--rm deletes the container on exit so you do not accumulate stopped ones.
--name web gives it a stable name for docker logs web and docker exec.

4. Inspect and interact

You debug containers by looking at logs and stepping inside.

docker ps
docker logs web
docker exec -it web sh

docker ps lists running containers; add -a to see stopped ones.
docker logs streams stdout/stderr, which is where a good container writes everything.
docker exec -it ... sh opens a shell in the live container for inspection.

5. Push to a registry

A registry stores and distributes images so other machines and clusters can pull them.

docker tag myapp:1.0.0 registry.example.com/team/myapp:1.0.0
docker push registry.example.com/team/myapp:1.0.0

The tag's host prefix (registry.example.com) tells Docker where to push.
Registries include Docker Hub, GHCR, ECR, GAR, and self-hosted Harbor.
Nodes later pull this same reference; keep names consistent across environments.

6. Persist data with a volume

Container filesystems are ephemeral, so durable data lives in volumes.

docker volume create appdata
docker run --rm -v appdata:/var/lib/app myapp:1.0.0

A named volume outlives the container and survives restarts and re-creates.
Anything written outside the volume vanishes when the container is removed.
In Kubernetes the same idea appears as PersistentVolumes and PersistentVolumeClaims.

7. Wire up services with Compose

Compose v2 runs several containers together for local development.

services:
  web:
    build: .
    ports:
      - "8080:3000"
    depends_on:
      - db
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: devsecret
    volumes:
      - dbdata:/var/lib/postgresql/data
volumes:
  dbdata:

docker compose up builds and starts everything on a shared network.
Services reach each other by service name (db) over that network.
Compose is a dev and CI tool; the orchestrator handles production.

Intermediate Examples

8. Run the image as a Kubernetes Pod

The orchestrator schedules containers onto nodes and keeps them running.

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  containers:
    - name: web
      image: registry.example.com/team/myapp:1.0.0
      ports:
        - containerPort: 3000
      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"
        limits:
          memory: "256Mi"

The kubelet pulls the image and asks containerd (via the CRI) to run it - not Docker.
requests drive scheduling; limits become cgroup ceilings that cap the process.
A bare Pod is for learning; production uses a Deployment to manage replicas.

9. Manage replicas with a Deployment

A Deployment keeps a desired number of Pods running and handles rollouts.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: registry.example.com/team/myapp:1.0.0
          readinessProbe:
            httpGet:
              path: /healthz
              port: 3000

replicas: 3 tells the controller to maintain three Pods at all times.
The readinessProbe gates traffic until the container reports healthy.
Updating the image triggers a rolling update, replacing Pods a few at a time.

10. Expose it with a Service

A Service gives a stable virtual IP and DNS name in front of changing Pods.

apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 3000

The selector matches Pod labels, so the Service tracks Pods as they come and go.
Other Pods reach it at web (or web.namespace.svc) via cluster DNS.
For external traffic, add an Ingress or a Gateway API route in front.

The connective tissue is one loop: a Dockerfile builds an image, a registry stores it, a runtime turns it into a container, and the orchestrator schedules and heals those containers across nodes.

Learn these five nouns well and the rest of the platform is composition on top of them.

Docker Get Started - Official Docker beginner path.
Docker Docs - Official Docker documentation (Engine, Desktop, Compose, Build, Hub).
Open Container Initiative (OCI) - Standards body for container image and runtime specifications.
Learn Docker in a Month of Lunches, 2nd Edition - Elton Stoneman.
Docker Deep Dive - Nigel Poulton.

Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).

Every example is minimal and runnable so you can build the mental map quickly.

Prerequisites

Docker Engine 29.6.1 with BuildKit (default) for building and running locally.
Compose v2 (docker compose, not docker-compose) for multi-container dev.
kubectl matching your cluster (Kubernetes 1.36.2 here) for the orchestrator examples.
A local cluster (kind, minikube, or k3d) if you want to run the pod examples.

Quick check that your toolchain is live:

docker version --format '{{.Server.Version}}'
kubectl version --client -o yaml | grep gitVersion

Basic Examples

1. Build an image from a Dockerfile

An image is a read-only, layered filesystem plus config; a Dockerfile is the recipe.

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
USER node
CMD ["node", "server.js"]

FROM picks a base layer; each instruction adds a cache-friendly layer on top.
COPY package*.json before the source lets npm ci stay cached when only app code changes.
USER node runs the app as a non-root user, a security default worth setting early.
CMD is the default process; it becomes PID 1 in the container.

2. Build and tag it

Tags name an image so you and the registry can find it.

docker build -t myapp:1.0.0 .
docker images myapp

-t name:tag sets a human tag; prefer semantic, immutable tags over latest.
The build runs on BuildKit by default, which parallelizes and caches layers.
The same content also has an immutable digest (sha256:...) you can pin later.

3. Run a container

A container is a running instance of an image - an isolated process with that image's filesystem.

docker run --rm -p 8080:3000 --name web myapp:1.0.0

-p 8080:3000 maps host port 8080 to the container's port 3000.
--rm deletes the container on exit so you do not accumulate stopped ones.
--name web gives it a stable name for docker logs web and docker exec.

4. Inspect and interact

You debug containers by looking at logs and stepping inside.

docker ps
docker logs web
docker exec -it web sh

docker ps lists running containers; add -a to see stopped ones.
docker logs streams stdout/stderr, which is where a good container writes everything.
docker exec -it ... sh opens a shell in the live container for inspection.

5. Push to a registry

A registry stores and distributes images so other machines and clusters can pull them.

docker tag myapp:1.0.0 registry.example.com/team/myapp:1.0.0
docker push registry.example.com/team/myapp:1.0.0

The tag's host prefix (registry.example.com) tells Docker where to push.
Registries include Docker Hub, GHCR, ECR, GAR, and self-hosted Harbor.
Nodes later pull this same reference; keep names consistent across environments.

6. Persist data with a volume

Container filesystems are ephemeral, so durable data lives in volumes.

docker volume create appdata
docker run --rm -v appdata:/var/lib/app myapp:1.0.0

A named volume outlives the container and survives restarts and re-creates.
Anything written outside the volume vanishes when the container is removed.
In Kubernetes the same idea appears as PersistentVolumes and PersistentVolumeClaims.

7. Wire up services with Compose

Compose v2 runs several containers together for local development.

services:
  web:
    build: .
    ports:
      - "8080:3000"
    depends_on:
      - db
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: devsecret
    volumes:
      - dbdata:/var/lib/postgresql/data
volumes:
  dbdata:

docker compose up builds and starts everything on a shared network.
Services reach each other by service name (db) over that network.
Compose is a dev and CI tool; the orchestrator handles production.

Intermediate Examples

8. Run the image as a Kubernetes Pod

The orchestrator schedules containers onto nodes and keeps them running.

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  containers:
    - name: web
      image: registry.example.com/team/myapp:1.0.0
      ports:
        - containerPort: 3000
      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"
        limits:
          memory: "256Mi"

The kubelet pulls the image and asks containerd (via the CRI) to run it - not Docker.
requests drive scheduling; limits become cgroup ceilings that cap the process.
A bare Pod is for learning; production uses a Deployment to manage replicas.

9. Manage replicas with a Deployment

A Deployment keeps a desired number of Pods running and handles rollouts.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: registry.example.com/team/myapp:1.0.0
          readinessProbe:
            httpGet:
              path: /healthz
              port: 3000

replicas: 3 tells the controller to maintain three Pods at all times.
The readinessProbe gates traffic until the container reports healthy.
Updating the image triggers a rolling update, replacing Pods a few at a time.

10. Expose it with a Service

A Service gives a stable virtual IP and DNS name in front of changing Pods.

apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 3000

The selector matches Pod labels, so the Service tracks Pods as they come and go.
Other Pods reach it at web (or web.namespace.svc) via cluster DNS.
For external traffic, add an Ingress or a Gateway API route in front.

The connective tissue is one loop: a Dockerfile builds an image, a registry stores it, a runtime turns it into a container, and the orchestrator schedules and heals those containers across nodes.

Learn these five nouns well and the rest of the platform is composition on top of them.

Docker Get Started - Official Docker beginner path.
Docker Docs - Official Docker documentation (Engine, Desktop, Compose, Build, Hub).
Open Container Initiative (OCI) - Standards body for container image and runtime specifications.
Learn Docker in a Month of Lunches, 2nd Edition - Elton Stoneman.
Docker Deep Dive - Nigel Poulton.

Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).

Container Basics

Search Documentation

Container Basics