Local Dev Basics

This page is the one-stop intro to running a containerized service on your own machine: building images, wiring dependencies with Compose, and staying close to production so the same image ships everywhere.

Prerequisites

• Docker Engine 29.x with BuildKit (the default build backend).
• Compose v2 - invoked as docker compose (a subcommand, not the old docker-compose binary).
• A local Kubernetes for the K8s-specific checks: kind, minikube, or k3d (optional but recommended).
• kubectl matched to your cluster minor (1.34-1.36 for a 1.36 control plane).

Quick check that your toolchain is ready:

docker version
docker compose version
kubectl version --client

Basic Examples

1. A minimal, production-shaped Dockerfile

A multi-stage build keeps build tools out of the runtime image.

# syntax=docker/dockerfile:1
FROM node:22-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:22-bookworm-slim AS runtime
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

• # syntax= opts into the current Dockerfile frontend so newer features work under BuildKit.
• Two stages: build compiles, runtime ships only the artifacts.
• USER node runs as a non-root user, matching production security defaults.
• Pinning node:22-bookworm-slim keeps the base predictable; pin by digest for stricter parity.

2. Build and run the image

Build once, then run it exactly as CI would.

docker build -t api:dev .
docker run --rm -p 3000:3000 -e LOG_LEVEL=debug api:dev

• -t api:dev names the image; the same recipe produces the image CI builds.
• --rm cleans up the container on exit so you do not accumulate stopped containers.
• -e LOG_LEVEL=debug injects config at run time - the app binary is unchanged.
• -p 3000:3000 publishes the container port to your host.

3. Inspect a running container

You debug containers by looking inside them, not by guessing.

docker ps
docker logs -f <container-id>
docker exec -it <container-id> sh

• docker ps lists running containers and their published ports.
• docker logs -f streams stdout/stderr, which is where a twelve-factor app should log.
• docker exec -it ... sh opens a shell inside the running container to inspect files or env.

4. Compose for multi-service wiring

Real apps have dependencies; Compose declares them as one graph.

services:
  api:
    build: .
    ports:
      - "3000:3000"
    env_file: .env.dev
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: devsecret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 5

• build: . builds the API from your Dockerfile; image: pulls Postgres.
• env_file supplies dev config so no secrets are baked into the image.
• depends_on with condition: service_healthy waits for the healthcheck to pass.
• Compose v2 is the current spec; run it with docker compose up.

5. Start, view, and tear down a stack

The everyday inner-loop commands.

docker compose up -d --build
docker compose logs -f api
docker compose down -v

• up -d --build rebuilds changed images and starts everything detached.
• logs -f api tails a single service.
• down -v stops the stack and removes named volumes, giving a clean slate.

6. Persist data with a named volume

Databases need their data to survive container restarts.

services:
  db:
    image: postgres:17
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

• A named volume pgdata is managed by Docker and outlives the container.
• Mounting it at Postgres's data directory keeps your local schema between runs.
• Use docker compose down (without -v) to keep the data, -v to wipe it.

7. Keep secrets and config out of the image

Config differs by environment, so it must not be baked in.

# .env.dev  (git-ignored)
DATABASE_URL=postgres://postgres:devsecret@db:5432/app
LOG_LEVEL=debug

• The .env.dev file feeds Compose via env_file, never the image.
• The same image reads DATABASE_URL in prod from a Kubernetes Secret instead.
• Add these files to .gitignore so credentials never reach the repo.

Intermediate Examples

8. Run the production image locally

The strongest local check is running the real prod image, not a dev variant.

docker build -t api:prod --target runtime .
docker run --rm -p 3000:3000 --read-only --tmpfs /tmp \
  -e DATABASE_URL=postgres://... api:prod

• --target runtime builds the final stage, the exact artifact you deploy.
• --read-only mirrors a hardened prod filesystem so you catch write-path bugs early.
• --tmpfs /tmp grants the one writable path most apps still need.

9. Load your image into a local Kubernetes

Some behavior (probes, limits, policy) only appears in Kubernetes.

kind create cluster
kind load docker-image api:prod
kubectl run api --image=api:prod --port=3000 --image-pull-policy=Never

• kind load docker-image injects your locally built image into the cluster's containerd.
• --image-pull-policy=Never tells Kubernetes to use the loaded image, not pull it.
• Remember the runtime here is containerd via the CRI, not Docker Engine.

10. Add a health probe and resource limits

Give the pod the same guardrails production uses.

apiVersion: v1
kind: Pod
metadata:
  name: api
spec:
  containers:
    - name: api
      image: api:prod
      readinessProbe:
        httpGet: { path: /healthz, port: 3000 }
        initialDelaySeconds: 3
      resources:
        requests: { cpu: "100m", memory: "128Mi" }
        limits: { memory: "256Mi" }

• The readiness probe keeps traffic away until the app reports healthy.
• requests inform scheduling; the memory limit triggers an OOM kill if exceeded.
• Testing these locally catches crash-loops that Compose can never reproduce.

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).