Docker Crash on Boot — API Connects Before Postgres Ready

Environment drift is the root cause of most 'works on my machine' failures. A different Node version, a missing library, an environment variable pointing nowhere — these are not skill problems, they are infrastructure problems. Docker eliminates this class of issue by packaging the entire runtime environment into a portable, immutable container.

Containers are not VMs. They share the host OS kernel and use Linux namespaces and cgroups for isolation. This means containers start in milliseconds and use megabytes of memory, making microservices architectures economically viable. On the same machine that runs three VMs, you can run thirty containers.

Common misconceptions: containers are not inherently insecure (misconfiguration is the problem, not the technology), data inside containers is not persistent by default (you need volumes), and Docker Compose is not just for development (it works in production for single-host deployments).

Why Docker Compose Depends on Application-Level Retry, Not Just Container Order

Docker Compose's depends_on only controls container startup order, not service readiness. When your Java API container starts, it may attempt to connect to Postgres before Postgres is actually ready to accept connections. This is not a Docker bug — it's a fundamental design choice: Compose considers a container 'started' the moment its main process begins, not when the service inside is healthy.

In practice, this means your Spring Boot or Micronaut app will fail its initial connection pool initialization, crash, and potentially enter a restart loop. The fix isn't to add sleep commands — that's fragile and wastes seconds in CI. Instead, use healthcheck blocks in your Compose file to probe actual readiness (e.g., pg_isready for Postgres), then combine with depends_on.condition: service_healthy. Even then, your application code must implement retry logic with exponential backoff for the first connection, because health checks have a polling interval and can still race.

This pattern matters in every multi-service local dev environment and CI pipeline. Without it, you'll see intermittent 'Connection refused' errors that disappear on manual restart — wasting developer time and breaking automated tests. The rule: never trust container order alone; always pair health checks with application-level retry.

Containers vs Virtual Machines: Why Docker Is a Fundamentally Different Idea

Most people learn Docker by running commands without understanding the architectural shift underneath. That's fine for getting started, but it bites you the moment something breaks.

A virtual machine (VM) runs a full guest operating system — its own kernel, drivers, system processes — on top of a hypervisor. Your app sits at the top of this tower. Booting a VM can take minutes. It consumes gigabytes of RAM even before your app starts. Scaling ten microservices with VMs means ten full operating systems running simultaneously.

Docker containers take a different path. They share the host machine's kernel directly. Each container gets its own isolated view of the filesystem (via union file system layers), its own network namespace, and its own process tree — but there's no duplicated OS. A container starts in milliseconds. It uses megabytes of overhead instead of gigabytes.

The practical implication: on the same machine where you could run three VMs, you can run thirty containers. That's not a minor efficiency gain — it's the reason microservices architectures became economically viable. When AWS charges you per second of compute, that difference compounds fast.

Containers are not inherently less secure than VMs — they're just differently isolated. A misconfigured container is dangerous, just as a misconfigured VM is. The security story depends on your configuration, not the technology itself.

Kernel sharing trade-off: Because containers share the host kernel, a kernel vulnerability (like CVE-2022-0185 or Dirty Pipe) affects all containers on that host. VMs have a separate kernel per instance, so a kernel vulnerability in one VM does not affect others. For high-security multi-tenant environments (running untrusted code), VMs provide stronger isolation. For single-tenant application workloads, container isolation is sufficient.

# Compare startup time and resource footprint — run these and watch the difference

# Pull a minimal Linux image (only ~5MB compressed)
docker pull alpine:3.19

# Start a container, run a command, and exit — time the whole thing
time docker run --rm alpine:3.19 echo "Container is alive"
# --rm tells Docker to delete the container after it exits (no cleanup needed)
# alpine:3.19 is the image — think of it as the blueprint
# 'echo ...' is the command to run inside the container

# Now check how much memory the container used at peak
# Run it in the background with resource stats
docker run -d --name resource-demo alpine:3.19 sleep 30
# -d runs in detached (background) mode
# --name gives it a human-readable name instead of a random hash

docker stats resource-demo --no-stream
# --no-stream prints one snapshot instead of a live feed
# Look at the MEM USAGE column — typically under 1MB for alpine doing nothing

# Clean up
docker stop resource-demo && docker rm resource-demo

Containerization vs Virtualization Comparison Table

The table below summarizes the key differences between traditional virtual machines and Docker containers. These trade-offs directly impact how you architect, deploy, and secure your applications.

When choosing between them, consider your workload's isolation requirements, startup latency tolerance, and operational overhead budget. For most web applications and APIs running on a single tenancy infrastructure, containers offer a 10-100x resource efficiency improvement over VMs.

Docker Architecture: From CLI to Running Container

When you type docker run, a chain of components works together to create and start a container. Understanding this flow helps you troubleshoot startup failures (like the ECONNREFUSED scenario) and optimize build performance.

1. Docker CLI (your terminal) sends a REST API request to the Docker daemon. The CLI uses the DOCKER_HOST environment variable to know where the daemon is listening (default: unix:///var/run/docker.sock).
2. Docker daemon (dockerd) receives the request, checks local image cache, and pulls the image if necessary. It then calls containerd via gRPC to create a container.
3. containerd is the industry-standard container runtime (used by Docker, Kubernetes, and others). It manages the entire container lifecycle — image transfer, storage, network interfaces, and process orchestration. It calls runc to actually start the container.
4. runc is the low-level OCI runtime that spawns the container process on the host. It uses Linux namespaces (PID, mount, network, user) and cgroups (CPU, memory, I/O) to isolate the process. Once the container is running, runc exits and the process runs directly under the host kernel.

The diagram below visualizes this flow. The important detail: the Docker daemon is not involved in the running container's process — it only coordinates setup. This makes containers lightweight and fast.

``mermaid graph TD A[User runs docker run] --> B[Docker CLI] B -->|REST API on /var/run/docker.sock| C[Docker Daemon (dockerd)] C -->|gRPC| D[containerd] D -->|OCI runc call| E[runc] E -->|clone() with namespaces & cgroups| F[Container Process] F --> G[Host Kernel] C -->|image pull| H[Registry (Docker Hub)] H --> C ``

First 5 Docker Commands Every Developer Should Know

If you're new to Docker, these five commands will cover 90% of your daily workflow. Master them before diving into advanced topics like multi-stage builds or healthchecks.

1. docker pull — Download an image from a registry (default Docker Hub). Always specify a tag; never use latest in scripts.
2. ```bash
3. docker pull postgres:16-alpine
4. ```
5. docker run — Create and start a container from an image. Common flags: -d (detach), -p (port mapping), --name, -v (volume), -e (environment variable).
6. ```bash
7. docker run -d --name my-postgres -p 5432:5432 -e POSTGRES_PASSWORD=secret postgres:16-alpine
8. ```
9. docker ps — List running containers. Add -a to include stopped containers. Use --format for custom output.
10. ```bash
11. docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
12. ```
13. docker logs — View logs from a container. Use -f to follow (tail -f style). Combine with --tail for performance.
14. ```bash
15. docker logs -f my-postgres --tail 20
16. ```
17. docker exec — Run a command inside a running container. The -it flags allocate an interactive terminal (useful for debugging).
18. ```bash
19. docker exec -it my-postgres psql -U postgres
20. ```

These commands are the foundation. Once comfortable, add docker compose, docker build, docker images, and docker system prune to your toolkit.

# 1. Pull an image
$ docker pull alpine:3.19

# 2. Run a container interactively
$ docker run -it alpine:3.19 sh
/ # echo "Hello from inside container"
Hello from inside container
/ # exit

# 3. List running containers
$ docker ps
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS   PORTS   NAMES

# 4. View logs of a container (replace <container-id>)
$ docker logs <container-id>

# 5. Execute a command in a running container
$ docker run -d --name test alpine:3.19 sleep 30
$ docker exec test echo "Alive!"
Alive!
$ docker stop test && docker rm test

Images, Layers and Dockerfiles: How Docker Actually Builds Your App

A Docker image is a read-only blueprint for creating containers. A container is a running instance of an image — the same relationship as a class and an object in OOP, or a recipe and a meal.

Images are built in layers. Every instruction in a Dockerfile creates a new layer on top of the previous one. Docker caches these layers aggressively. This is the single most important thing to understand about Dockerfile efficiency: if layer 3 changes, Docker rebuilds from layer 3 downward. Layers 1 and 2 are served from cache instantly.

This is why experienced engineers always copy dependency manifests (package.json, requirements.txt, go.mod) and install dependencies BEFORE copying application source code. Source code changes every commit; dependencies change rarely. Put the slow, stable work near the top of your Dockerfile so it stays cached.

Multi-stage builds are the other major pattern worth knowing early. You use one image (with compilers, build tools, dev dependencies) to build your app, then copy only the compiled output into a minimal runtime image. Your final image contains zero build tooling — smaller, faster, and with a dramatically reduced attack surface.

Let's build a realistic Node.js API with both patterns applied — this is what a production-ready Dockerfile actually looks like, not the toy examples you usually see.

Layer cleanup in the same RUN: Each RUN creates a new layer. If you download a 200MB package in one RUN and delete it in the next RUN, the 200MB still exists in the first layer — layers are additive. Always chain download and cleanup in the same RUN with &&.

# ── STAGE 1: Build Stage ──────────────────────────────────────────────────────
# Use the full Node image with build tools available
FROM node:20-alpine AS builder
# 'AS builder' names this stage so we can reference it later
# node:20-alpine uses Alpine Linux — much smaller than node:20-bullseye

# Set the working directory inside the container
WORKDIR /app

# COPY dependency files FIRST — before application code
# Docker caches this layer. If package.json hasn't changed, npm install
# won't re-run even if your source code changed. This saves minutes per build.
COPY package.json package-lock.json ./

# Install only production dependencies (saves ~200MB vs installing devDependencies)
RUN npm ci --omit=dev
# npm ci is faster and stricter than npm install — it respects package-lock.json exactly

# NOW copy application source code
# Changing any source file only invalidates from this line forward
COPY src/ ./src/

# ── STAGE 2: Production Runtime Stage ─────────────────────────────────────────
# Start fresh from a minimal image — no build tools, no npm, no package manager cruft
FROM node:20-alpine AS production

# Run as a non-root user — critical for production security
# node:alpine ships with a 'node' user built in
USER node

WORKDIR /app

# Copy only what we need from the builder stage — not the entire filesystem
COPY --from=builder --chown=node:node /app/node_modules ./node_modules
COPY --from=builder --chown=node:node /app/src ./src
COPY --chown=node:node package.json ./
# --chown ensures the node user owns these files, not root

# Document which port the app listens on (informational — doesn't actually publish it)
EXPOSE 3000

# Define the command to run when a container starts from this image
# Use array form (exec form) — NOT string form — to ensure signals are handled correctly
CMD ["node", "src/server.js"]

Volumes and Docker Compose: Persistence and Multi-Container Orchestration

Containers are ephemeral by design. When a container stops, any data written inside it vanishes. That's perfect for stateless services, but databases, file uploads, and logs need to survive container restarts. Docker volumes solve this by mounting a storage location from the host (or a managed volume) into the container's filesystem.

There are three storage mechanisms: bind mounts (link a specific host directory into the container — great for local development where you want live code reloading), named volumes (Docker manages the storage location — best for databases in production), and tmpfs mounts (in-memory only — useful for sensitive data you never want written to disk).

Real applications are never a single container. You have an API, a database, a cache, maybe a background worker. Running and networking these manually with individual docker run commands is error-prone and impossible to reproduce reliably. Docker Compose lets you define your entire multi-container application in one YAML file and bring it all up with a single command.

Here's a complete, realistic Compose setup for a Node.js API backed by PostgreSQL and Redis — the stack you'll encounter in most backend roles.

The depends_on trap: depends_on without condition: service_healthy only waits for the container to START — not for the process inside to be READY. Postgres takes 5-15 seconds to initialize. Without service_healthy, your API will crash on boot trying to connect to a database that is not accepting connections yet. This is the single most common cause of flaky Docker Compose environments.

# Docker Compose V2 format (no 'version' key needed with modern Docker Desktop)
services:

  # ── The API service ───────────────────────────────────────────────────────
  api:
    build:
      context: .           # Build from the Dockerfile in the current directory
      target: production   # Use the 'production' stage from our multi-stage Dockerfile
    container_name: my-api
    ports:
      - "3000:3000"        # Map host port 3000 -> container port 3000
    environment:
      # Reference values from a .env file — never hardcode secrets in Compose files
      NODE_ENV: production
      DATABASE_URL: postgresql://api_user:${DB_PASSWORD}@postgres:5432/app_db
      REDIS_URL: redis://redis:6379
      # 'postgres' and 'redis' are the service names below — Docker's internal
      # DNS resolves them automatically within the shared network
    depends_on:
      postgres:
        condition: service_healthy   # Wait until postgres passes its health check
      redis:
        condition: service_started
    restart: unless-stopped          # Restart on crash, but not if manually stopped

  # ── PostgreSQL database ───────────────────────────────────────────────────
  postgres:
    image: postgres:16-alpine        # Always pin a specific version — never use 'latest'
    container_name: my-postgres
    environment:
      POSTGRES_DB: app_db
      POSTGRES_USER: api_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}   # Pulled from .env file
    volumes:
      - postgres_data:/var/lib/postgresql/data
      # Named volume — Docker manages where this lives on the host.
      # Database files survive 'docker compose down' and container rebuilds.
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
      # Bind mount an init script — runs once when the DB is first created.
      # :ro makes it read-only inside the container (good security habit)
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U api_user -d app_db"]
      interval: 5s     # Check every 5 seconds
      timeout: 5s      # Fail if no response in 5 seconds
      retries: 5       # Mark unhealthy after 5 consecutive failures
      start_period: 30s  # Grace period before health checks start

  # ── Redis cache ───────────────────────────────────────────────────────────
  redis:
    image: redis:7-alpine
    container_name: my-redis
    command: redis-server --appendonly yes
    # --appendonly yes enables AOF persistence — data survives Redis restarts
    volumes:
      - redis_data:/data

# Named volumes must be declared at the top level
# Docker creates and manages these — they persist across 'docker compose down'
volumes:
  postgres_data:
  redis_data:

Why Your Docker Builds Break at 2 AM: The Registry Rate-Limit Ambush

You've tuned Dockerfiles, layered images, and pinned base tags. Then your CI pipeline fails at 3 AM because Docker Hub throttled your pull. That's not a networking glitch — it's a rate limit. Default anonymous pulls max out at 100 per six hours per IP. Authenticated free users get 200. Your build server is sharing an office IP with twenty other devs. You're screwed.

Fix this before it bites. Authenticate every Docker client that pulls images — even from your local laptop. Add credsStore to ~/.docker/config.json and log in via docker login. For CI, inject a read-only PAT as a secret. Never rely on anonymous pulls for production builds. If you use a mirror registry like Docker's own registry-1.docker.io, you still get throttled. Run your own pull-through cache with Nexus or Harbor. That way your CI pulls once, caches locally, and never hits the public limit again.

// io.thecodeforge — devops tutorial

version: '3.8'
services:
  registry:
    image: registry:2
    ports:
      - "5000:5000"
    environment:
      REGISTRY_PROXY_REMOTEURL: https://registry-1.docker.io
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
    volumes:
      - registry_data:/data

volumes:
  registry_data:

Stop Using Latest: How Unpinned Tags Corrode Your Deployments

image: postgres:latest looks harmless on day one. Six weeks later, a latest tag silently maps to Postgres 16 while your code expects Postgres 14. Your staging environment passes tests because you haven't rebuilt the image. Production pulls the new tag, crashes on a breaking change, and your pager goes off. That's not a CI failure — it's a trust failure.

Every tag except a digest is mutable. latest, alpine, bullseye — all of them get overwritten by maintainers. Pin to a digest (sha256:abc123...). Or at minimum pin to a minor version: postgres:14.10. Never use latest in any environment you care about. Not dev, not staging, not prod. If you use Docker Compose for local dev, still pin it. The same bug applies when a co-worker pulls the compose file on a fresh machine three months later.

Automate your image update policy with Renovate or Dependabot. They open PRs for digest bumps. You review, approve, and know exactly what changed. No surprises.

// io.thecodeforge — devops tutorial

version: '3.8'
services:
  db:
    image: postgres@sha256:f9183f69e6ca1b1b2f9d1e0faee24f466ce5e92ec1cd20e7cd6e3a0f0a0b5e7c
    # not: image: postgres:latest
    environment:
      POSTGRES_DB: payments
      POSTGRES_USER: app
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

The Hidden Cost of `docker exec` in Production Debugging

You SSH into a box, run docker exec -it web bash, and start poking around. Maybe you install curl. Maybe you grep logs. Ten minutes later you forget to exit. That container is now a snowflake — modified, untracked, and unreproducible. When you restart the service, those changes vanish. But if you scaled up replicas, only one has your ad-hoc tools. The next on-call engineer is confused. The deployment pipeline can't rebuild your state. You've broken reproducibility.

Production debugging with docker exec is a crutch you should break. Instead, run a sidecar container with the debugging tools you need, controlled by its own health check. Or ship all logs to a central aggregator (ELK, Loki, Datadog) before you need them. If you absolutely must inspect a running process, use docker cp to copy files out, or docker logs --tail 1000 -f to stream output. Never mutate a running production container.

If you're tempted to install packages inside a container, that's a signal your base image is missing essential debugging tools. Add them to your Dockerfile behind a build arg: ARG DEBUG_TOOLS=true and RUN apt-get install -y netcat strace tcpdump. Rebuild when you need them.

// io.thecodeforge — devops tutorial

version: '3.8'
services:
  api:
    image: payments-api:1.2.3
    # debug tools built-in via Dockerfile
    build:
      context: .
      args:
        DEBUG_TOOLS: "true"
  debug:
    image: alpine:3.18
    command: ["sleep", "infinity"]
    network_mode: "service:api"
    # share network namespace with api for tcpdump, netcat, etc.
    depends_on:
      - api
    profiles:
      - debug # only start with: docker compose --profile debug up