DEV Community: Shubham Sharma

Install Docker on macOS, Windows (WSL2), and Linux: One Guide, Three Paths

Shubham Sharma — Sat, 10 Oct 2026 14:00:02 +0000

Almost every guide on this site starts the same way: "make sure Docker is installed." This is the post that earns that line. One install, three operating systems, and a single command at the end that proves it worked. No prior containers knowledge needed, and nothing here assumes you have used Docker before.

The end state is the same on every OS: a working Docker Engine and a green docker run hello-world. How you get there differs. On macOS and Windows you install Docker Desktop, an app that runs the engine inside a small Linux VM for you. On Linux you install the engine natively, straight onto the machine. Pick your section below and skip the other two.

Tip

Key takeaways

macOS and Windows: install Docker Desktop. It bundles the engine, the CLI, and Compose behind one app.

Windows specifically: use the WSL2 backend, and run your docker commands from inside a WSL2 Linux distro.

Linux: install Docker Engine from Docker's own apt repository, not the old docker.io package.

On Linux, add yourself to the docker group so you can drop sudo. That group is root-equivalent, so treat it with respect.

You are done when docker run hello-world prints "Hello from Docker!" That output looks the same on all three, apart from one line that names your CPU.

Prerequisites

A machine you can install software on, with admin or sudo rights.
A few GB of free disk and RAM (Docker Desktop asks for at least 4 GB on macOS, 8 GB on Windows).
A terminal. On macOS that is Terminal or iTerm, on Windows it is PowerShell plus your WSL2 shell, on Linux it is your normal shell.

macOS: Docker Desktop

On an Apple Silicon or Intel Mac, Docker Desktop is the path. It runs the Linux engine inside a lightweight VM and gives you the docker CLI, Compose, and a menu-bar app.

1. Check requirements. You need a currently supported macOS (the current release and the two before it) and at least 4 GB of RAM. On Apple Silicon, Rosetta 2 is recommended but no longer strictly required.

2. Download the right disk image. From Docker's official macOS install page, grab the build that matches your chip: the Apple Silicon (ARM64) Docker.dmg for M1 and later, or the Intel (AMD64) one for older Macs. Installing the wrong architecture is the most common first mistake.

3. Install it. Open the .dmg, drag the Docker icon into your Applications folder, then launch Docker from Applications. Accept the Docker Subscription Service Agreement, keep the recommended settings, and enter your password when prompted so it can finish setting up.

4. Wait for the engine. A whale icon appears in your menu bar. While it is animating, the engine is still starting. Once it settles and the Docker menu says it is running, you are ready.

5. Verify. Open a terminal and run:

docker --version
docker run hello-world

You should see a version line followed by the "Hello from Docker!" message shown later in this guide. If the whale icon is not steady yet, give it a few more seconds and try again.

Info

Docker Desktop is not the only option on macOS. Alternatives like OrbStack and Colima also give you a real Docker Engine and the same docker CLI. Every command in this series works the same against them. If you are new, start with Docker Desktop; it is the path the official docs assume.

Windows: Docker Desktop with the WSL2 backend

On Windows, Docker Desktop runs on top of WSL2 (the Windows Subsystem for Linux, version 2). This is the modern, faster backend, and it is what you want.

1. Check requirements. Docker lists 64-bit Windows 10 (22H2, build 19045) or Windows 11 (23H2, build 22631) or newer, a 64-bit CPU with SLAT, 8 GB of RAM, and hardware virtualization enabled in your BIOS or UEFI. If virtualization is off, containers will not start, so enable it now.

2. Install WSL2. Open PowerShell as Administrator and run:

wsl --install

That command installs WSL2 and a default Ubuntu distribution. If WSL is already present, update it and confirm the version instead:

wsl --update
wsl --version

You want WSL version 2.1.5 or later. Reboot if it asks you to.

3. Download and run Docker Desktop. Get Docker Desktop Installer.exe for your architecture (x86_64 for most machines) from Docker's official Windows install page. Run it, and on the configuration screen make sure "Use WSL 2 instead of Hyper-V" is selected. Finish the wizard and let it authorize.

4. Start it. Search for Docker in the Start menu, open Docker Desktop, and accept the agreement. Give the engine a moment to come up.

5. Verify from inside WSL2. This is the step people miss. Open your WSL2 Linux shell (for example, launch "Ubuntu" from the Start menu), not plain PowerShell, and run:

docker --version
docker run hello-world

Warning

Run docker from inside your WSL2 distro, not from PowerShell. With the WSL2 backend, Docker Desktop wires the docker command into your Linux distributions. Working from the WSL2 shell is where your project files, paths, and performance all line up. Running from PowerShell can work, but the Linux shell is the intended home.

Linux: Docker Engine (the native path)

On Linux there is no Desktop VM in the middle. You install Docker Engine directly, and it is the leanest, fastest option. The steps below are the classic .list form of Docker's official apt-repository method on Ubuntu 24.04 LTS (the current docs also show a newer deb822 .sources variant; both install the same engine). Every command and its output here was captured on a real Ubuntu 24.04.5 LTS system (a fresh VM).

Warning

Do not apt install docker.io. Ubuntu's built-in docker.io package is older and misses Compose v2 and buildx. Use Docker's own repository, below, to get the current engine and plugins.

1. Add Docker's official apt repository. First the prerequisites and the signing key:

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Then add the repository. This one-liner fills in your architecture and Ubuntu codename automatically, so it is correct on both amd64 servers and arm64 machines:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

On the test machine that wrote:

deb [arch=arm64 signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu noble stable

2. Install the engine and plugins.

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3. Confirm the versions and that the service is running. Docker Engine installs as a systemd service that starts on boot:

docker --version
docker compose version
systemctl is-enabled docker
systemctl is-active docker

Captured output:

Docker version 29.8.0, build 88096ef
Docker Compose version v5.5.1
enabled
active

4. Verify.

sudo docker run hello-world

You will see the "Hello from Docker!" message below. Note the sudo: right after install, only root can talk to the Docker socket. The next section fixes that.

Run Docker without sudo (Linux post-install)

Typing sudo before every docker command gets old fast. Add your user to the docker group so the CLI can reach the daemon socket directly. This is one of Docker's official Linux post-install steps:

sudo groupadd docker          # usually already exists
sudo usermod -aG docker $USER

Group membership is only picked up in a new login session. Either log out and back in, or start a fresh group session in place:

newgrp docker

Now docker works without sudo. On the test machine, running hello-world as the normal user succeeded, printing the usual message, including:

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

Warning

The docker group is root-equivalent. Anyone in it can start a container that mounts the whole host filesystem, which is effectively root access. Only add trusted users, and on a shared server consider rootless Docker (next) instead.

Optional: rootless Docker (Linux)

Rootless mode runs the daemon as your user, not root, which shrinks the blast radius if a container is compromised. Install the extras and run Docker's setup tool as your normal user (not with sudo):

sudo apt-get install -y uidmap docker-ce-rootless-extras
dockerd-rootless-setuptool.sh install

Two real gotchas showed up during testing, both worth knowing:

Info

Rootless refuses to install while rootful Docker is running. The tool aborts with "rootful Docker is running and accessible" if the system daemon still holds /var/run/docker.sock. Stop it first with sudo systemctl disable --now docker.service docker.socket, then run the setup tool again.

It also needs subuid/subgid ranges. If the tool complains about missing system requirements, your user has no entry in /etc/subuid and /etc/subgid. A normally created Ubuntu user already has these; if yours does not, add them (echo "$USER:100000:65536" | sudo tee -a /etc/subuid /etc/subgid) and rerun.

Once it finishes it creates a rootless CLI context and prints two environment lines to add to your shell profile. After starting the user service, docker run hello-world runs entirely as your user, and docker info reports rootless under its security options.

What a working install looks like

On every OS, success looks essentially like this. This is the real output of docker run hello-world, trimmed after the four numbered steps:

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm64v8)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

The (arm64v8) line just names the host CPU architecture. On an Intel or amd64 machine it reads (amd64) instead, and the rest is the same.

Those four lines are worth reading once, because they describe the whole system in miniature: a client (the docker command), a daemon (the engine), an image pulled from a registry (Docker Hub), and a container created from that image. That is the mental model the rest of this series builds on.

That registry is also the fun part. Docker Hub is the default public one, and it holds thousands of ready to run images: databases like Postgres, Redis, and MySQL, tools like nginx and Grafana, and whole self-hosted apps. Most of them are a single docker run away, which is what makes Docker so useful once it is installed.

Common gotchas, by OS

macOS: "Cannot connect to the Docker daemon"

The engine is not up yet. Check the whale icon in the menu bar; if it is still animating, wait for it to settle, then retry. If it never starts, quit and reopen Docker Desktop.

Windows: containers will not start

Almost always virtualization is disabled in BIOS/UEFI, or WSL2 is out of date. Enable virtualization, then run wsl --update and reboot.

Windows: `docker` not found in PowerShell

Run it from your WSL2 Linux shell instead. That is where the WSL2 backend exposes the command.

Linux: "permission denied while trying to connect to the Docker daemon socket"

You are not in the docker group yet, or you have not started a new session. Run newgrp docker or log out and back in.

Linux: apt cannot find `docker-ce`

The Docker repository was not added correctly. Recheck the keyring and the docker.list file from the Linux section, then run sudo apt-get update again.

Where to go next

You have a working engine. The natural next step is to actually drive it: start containers, look inside them, and clean them up.

Next in this series: Run Your First Containers, where we use docker run, ps, logs, exec, stop, and rm to build the real mental model of images versus containers.

Verified on 2026-09-10. The Linux path was run end to end on a real Ubuntu 24.04.5 LTS arm64 system (a fresh VM): the classic apt-repository install, the captured versions (Docker Engine 29.8.0, Compose v5.5.1, containerd 2.3.5), the systemd service showing enabled and active, docker run hello-world, the non-root docker group step, and rootless mode (including the two gotchas above). The macOS verification output was confirmed against the OrbStack engine on Apple Silicon (the same Docker Engine that Docker Desktop ships, wrapped in a different app), not Docker Desktop itself; the Docker Desktop screens follow Docker's official macOS docs. The Windows and WSL2 steps follow Docker's official Windows docs and were not captured on Windows hardware in this run.

Run Your First Containers: docker run, ps, logs, exec, stop, rm

Shubham Sharma — Wed, 07 Oct 2026 14:00:05 +0000

You have Docker installed and hello-world printed its greeting. That container did its one job and exited immediately, which is not very interesting. Real containers stay up, serve traffic, and need starting, inspecting, and cleaning up. This post walks the everyday container lifecycle on a single command you will use constantly: a web server you can actually open.

By the end you will be able to start a container, see it running, talk to it, look inside it, stop and restart it, and remove it, all with a handful of docker commands. Every command and its output below was captured on a real Ubuntu 24.04 machine running Docker Engine 29.8.0.

Tip

Key takeaways

An image is the read-only template. A container is a running instance of it. One image, many containers.

docker run creates and starts a container. -d runs it in the background, -p publishes a port, --name gives it a friendly name.

docker ps lists running containers, docker ps -a includes stopped ones.

docker logs, docker exec, docker stop, docker start, and docker rm are the rest of the daily toolkit.

--rm auto-deletes a container when it exits, which keeps throwaway runs from piling up.

Prerequisites

Docker installed and working. If docker run hello-world prints "Hello from Docker!", you are set. If not, start with Install Docker on macOS, Windows (WSL2), and Linux.
On Linux, either be in the docker group or prefix these commands with sudo. The install guide covers the group step.

Images versus containers, in one minute

This is the one idea that makes everything else click. An image is a packaged, read-only snapshot: an application plus everything it needs to run. A container is a live, running copy created from that image, with its own writable layer on top. You can start ten containers from the same image, and each one is independent.

When you run docker run nginx, Docker looks for the nginx image locally, pulls it from Docker Hub (the default public registry, home to thousands of ready to run images) if it is missing, then creates and starts a container from it. Let us do exactly that, but with a real web server you can open in a browser.

Start a container

Run the official nginx web server, in the background, with its port published to your machine:

docker run -d -p 8080:80 --name web nginx

Three flags are doing the work here. -d (detached) runs the container in the background and hands you back your prompt. -p 8080:80 maps port 8080 on your machine to port 80 inside the container, where nginx listens. --name web gives the container a name so you do not have to use its ID for every later command.

On the first run, Docker pulls the image, then prints the new container's full ID:

Status: Downloaded newer image for nginx:latest
22bc7448b0bc864f0fbe6fce4966fa99a07ca7e017a11d6bcdadf5d738f7cb51

See it running

docker ps

docker ps lists running containers. Here is the row for the one we just started (columns trimmed to fit):

CONTAINER ID   IMAGE     STATUS         PORTS                    NAMES
22bc7448b0bc   nginx     Up Less than a second   0.0.0.0:8080->80/tcp     web

That 0.0.0.0:8080->80/tcp is the port mapping in action. Note the short container ID (22bc7448b0bc); it is just the first 12 characters of the full ID from the run command.

Talk to it

The container is serving nginx on port 8080. Ask it for a page:

curl -s localhost:8080 | grep -i title

<title>Welcome to nginx!</title>

That is a real HTTP response from software running inside the container. Open http://localhost:8080 in a browser and you will see the nginx welcome page.

Look inside

Two commands cover most of what you need to inspect a running container.

Read its logs with docker logs. nginx writes each request to its access log, so the curl above shows up:

docker logs web

172.17.0.1 - - [10/Sep/2026:10:12:07 +0000] "GET / HTTP/1.1" 200 896 "-" "curl/8.5.0" "-"

Get a shell inside with docker exec. The -it flags give you an interactive terminal:

docker exec -it web sh

Now you are inside the container. Poke around, then type exit to leave. For a quick one-off you can also run a single command without an interactive shell:

docker exec web whoami
docker exec web nginx -v

root
nginx version: nginx/1.31.5

Info

exec runs inside a container that is already running. It does not start a new one. If the container is stopped, start it first. This is the difference between docker run (create a new container) and docker exec (step into an existing one), which trips up a lot of beginners.

Stop, start, and see stopped containers

Stop the container. Docker asks nginx to shut down gracefully and returns the name once it has:

docker stop web

web

A stopped container does not vanish. It still exists, just not running. docker ps alone will not show it, but docker ps -a will:

docker ps -a

NAMES     STATUS
web       Exited (0)

Exited (0) means it stopped cleanly (exit code 0). Because the container still exists, you can start it again without recreating it, and it keeps its name and configuration:

docker start web
docker ps

NAMES     STATUS         PORTS
web       Up Less than a second   0.0.0.0:8080->80/tcp

Clean up

When you are done, remove the container. A running container will not be removed unless you force it, so -f stops and removes in one step:

docker rm -f web

web

Now docker ps -a no longer lists web. The container is gone; the nginx image stays cached locally for next time.

Warning

Stopped containers pile up. Every docker run without --rm leaves a container behind after it exits, and they accumulate quietly. Run docker ps -a now and then to see them, and remove the ones you do not need.

For anything short-lived, skip the cleanup entirely with --rm, which deletes the container the moment it exits. This runs a tiny Alpine Linux container, prints one line, and removes itself:

docker run --rm alpine echo "hello from a throwaway container"

hello from a throwaway container

After that, docker ps -a shows nothing new. The container ran and cleaned up after itself. This is the pattern for one-off commands and scripts.

The lifecycle at a glance

That is the whole loop you will use every day:

docker run creates and starts a container (add -d, -p, --name, --rm as needed).
docker ps / docker ps -a list running / all containers.
docker logs reads its output.
docker exec -it <name> sh opens a shell inside it.
docker stop / docker start pause and resume it.
docker rm -f removes it.

Common gotchas

"port is already allocated"

Something else is using host port 8080. Either stop that process or publish a different port, for example -p 8081:80, then browse to 8081.

`docker exec` says the container is not running

exec only works on a running container. Check docker ps -a; if it shows Exited, run docker start <name> first.

The name is already in use

Container names are unique. If docker run --name web fails because web exists (even stopped), remove the old one with docker rm web or pick a new name.

Changes inside a container disappear

Anything you write inside a container is lost when it is removed. That is by design. Persisting data needs volumes, which is a later topic in this series.

Where to go next

You can now drive a single container through its whole life. Real applications are rarely one container though; they are an app plus a database plus a cache, wired together. That is what Docker Compose is for.

Next in this series: Docker Compose, where we bring up a web app, Postgres, and Redis together with one docker compose up.

Verified on 2026-09-10 on a real Ubuntu 24.04.5 LTS system running Docker Engine 29.8.0. Every command in this post was run in order against the official nginx image (container 22bc7448b0bc, nginx 1.31.5) and the alpine image: docker run -d -p 8080:80 --name web nginx, docker ps, curl localhost:8080 returning the nginx welcome page, docker logs showing the captured GET / 200, docker exec returning root and the nginx version, docker stop (Exited 0), docker start, docker rm -f, and a --rm throwaway run.

Operating Containers: Healthchecks, Resource Limits, Restart Policies, and Env Config

Shubham Sharma — Sun, 04 Oct 2026 14:00:01 +0000

A container that runs is not the same as a container that behaves. In development, "it started" is enough. In production you want more: the container should know when it is broken, stay within a memory and CPU budget, come back on its own after a crash, and get its config cleanly without secrets baked into the image. This post adds all four to a real stack, with commands and output captured on a live Docker Engine.

Tip

Key takeaways

A healthcheck lets Docker report a container as healthy or unhealthy, and Compose can hold a dependent back until its dependency is healthy.

Resource limits (--memory, --cpus, or deploy.resources.limits in Compose) cap what a container can use. Exceed memory and it is killed with exit code 137.

A restart policy (restart: unless-stopped or on-failure) brings a crashed container back automatically.

Load config from an env file so it stays out of the image, and know the precedence: a -e flag beats --env-file.

Prerequisites

Docker installed and running. See Install Docker on macOS, Windows (WSL2), and Linux.
Comfort with Compose, from Docker Compose: Run a Multi-Service Stack.

Info

Get the code. The full stack for this post (compose file, health endpoint, env file) is in the docker-foundations repo, under 07-operating/. Clone it to follow along.

Healthchecks: does the container actually work?

A running container is not necessarily a working one. A web server can be up while its process is deadlocked. A healthcheck is a command Docker runs inside the container on an interval; if it passes, the container is healthy, if it fails enough times, unhealthy.

Here is the smallest demonstration. Run a container whose health depends on a file existing, then create and remove that file to flip its state:

docker run -d --name svc \
  --health-cmd="test -f /tmp/ok" --health-interval=2s --health-retries=2 \
  alpine sh -c "touch /tmp/ok; sleep 3600"
docker ps --format "{{.Names}}  {{.Status}}"

svc  Up 5 seconds (healthy)

Now break the check by deleting the file, wait for the interval to run, and look again:

docker exec svc rm /tmp/ok
docker ps --format "{{.Names}}  {{.Status}}"

svc  Up 12 seconds (unhealthy)

Recreate the file and it recovers:

docker exec svc touch /tmp/ok
docker ps --format "{{.Names}}  {{.Status}}"

svc  Up 19 seconds (healthy)

The status column tracks the health state live. In a real image you set this once with a HEALTHCHECK instruction in the Dockerfile, or a healthcheck: block in Compose.

Health-gated startup in Compose

The real payoff is dependency ordering. In the Compose post we saw that depends_on waits for a container to start, not to be ready. A healthcheck fixes that: depends_on with condition: service_healthy holds a service back until its dependency reports healthy.

Our stack has a web service that depends on a Postgres db with a pg_isready healthcheck. Bring it up:

docker compose up -d

 Container op-demo-db-1   Started
 Container op-demo-db-1   Waiting
 Container op-demo-db-1   Healthy
 Container op-demo-web-1  Starting
 Container op-demo-web-1  Started

Read that order: Compose started db, then waited until it was healthy, and only then started web. No more racing a database that has not finished booting.

docker compose ps --format "table {{.Service}}\t{{.Status}}"

SERVICE   STATUS
db        Up 7 seconds (healthy)
web       Up 4 seconds (healthy)

Resource limits: stay in budget

By default a container can use all the host's memory and CPU. One runaway process can starve everything else on the box. Limits fix that.

Memory

Cap memory with --memory (and --memory-swap to also cap swap). When a container tries to exceed its memory limit, the kernel kills it. Watch it happen: this Python container asks for 200MB with a 64MB cap.

docker run --name oom --memory=64m --memory-swap=64m \
  python:3-alpine python -c "bytearray(200*1024*1024)"
docker inspect oom --format 'OOMKilled={{.State.OOMKilled}}  ExitCode={{.State.ExitCode}}'

OOMKilled=true  ExitCode=137

OOMKilled=true and exit code 137 are the signature of a container killed for exceeding its memory limit. If you ever see a container mysteriously exit with 137, this is almost always why.

CPU

Cap CPU with --cpus. This container runs a busy loop that would otherwise peg a whole core, limited to half a CPU:

docker run -d --name cpuhog --cpus=0.5 alpine sh -c "while true; do :; done"
docker stats --no-stream --format "{{.Name}}  CPU={{.CPUPerc}}"

cpuhog  CPU=49.71%

The busy loop is held right at its half-a-CPU ceiling instead of consuming everything.

Limits in Compose

In a Compose file you set the same limits per service under deploy.resources.limits, which docker compose up applies (you do not need Swarm). After bringing the stack up, you can confirm the limit landed on the container:

docker inspect op-demo-web-1 --format 'memory={{.HostConfig.Memory}}  nanocpus={{.HostConfig.NanoCpus}}'

memory=134217728  nanocpus=500000000

That is the 128MB (134217728 bytes) and half-CPU (500000000 nanocpus) budget from the compose file, enforced on the running container.

Restart policies: self-healing

Processes crash. A restart policy tells Docker to bring the container back automatically. unless-stopped restarts it on any exit except a deliberate docker stop, and on-failure restarts only on a non-zero exit, optionally up to a retry cap.

Watch a crashing container recover. This one runs for a few seconds, then exits with an error, with a cap of three retries:

docker run -d --name crasher --restart on-failure:3 alpine sh -c "sleep 3; exit 1"
docker inspect crasher --format 'RestartCount={{.RestartCount}} Status={{.State.Status}}'
# ... a few crash-and-restart cycles later ...
docker inspect crasher --format 'RestartCount={{.RestartCount}} Status={{.State.Status}} ExitCode={{.State.ExitCode}}'

RestartCount=0 Status=running
RestartCount=3 Status=exited ExitCode=1

Docker restarted the crashing container three times, then stopped because it hit the :3 cap. On a real service you would use restart: unless-stopped (no cap) so it keeps recovering, which is what our compose file sets on both services.

Info

A restart policy is not a healthcheck. A restart policy reacts to the container process exiting. A healthcheck reacts to the app being unresponsive while the process is still up. Production services usually want both: restart: unless-stopped to recover from crashes, and a healthcheck so orchestrators and depends_on know when the app is actually ready.

Env config without secrets in the image

Hardcoding config into an image is a mistake: it bakes environment-specific values (and often secrets) into an artifact you push to a registry. Load them at run time instead. Docker pulls environment values from three places (the image's own ENV, an --env-file, and -e flags), and the precedence matters: a -e flag beats --env-file, and both beat a value baked into the image with ENV:

printf "GREETING=from_env_file\nONLY_IN_FILE=yes\n" > envfile
docker run --rm --env-file envfile -e GREETING=from_flag alpine env

ONLY_IN_FILE=yes
GREETING=from_flag
# (PATH, HOSTNAME, HOME and other standard vars omitted)

GREETING came out as from_flag: the explicit -e won over the file. ONLY_IN_FILE passed through untouched. The same order holds in Compose: a service's environment: block overrides its env_file:. Keep the file (.env) out of git, commit an .env.example template, and your secrets never enter the image.

The whole thing in one Compose file

All four behaviors live together in the stack's docker-compose.yml:

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: demo
      POSTGRES_DB: demo
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U demo"]
      interval: 3s
      timeout: 3s
      retries: 5
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: "0.50"

  web:
    image: node:22-alpine
    working_dir: /app
    command: node server.js
    volumes:
      - ./app:/app
    env_file: .env
    ports:
      - "8080:3000"
    depends_on:
      db:
        condition: service_healthy   # web starts only once db reports healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O- http://localhost:3000/health || exit 1"]
      interval: 3s
      timeout: 3s
      retries: 5
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 128M
          cpus: "0.50"

docker compose up -d, and both services come up healthy, budgeted, self-healing, and configured from .env.

Common gotchas

Container exits with code 137

It was killed for exceeding its memory limit (or received a SIGKILL). Check docker inspect --format '{{.State.OOMKilled}}'. If true, raise the limit or fix the leak.

Healthcheck passes but the app is broken

Your check is too shallow. pg_isready proves Postgres accepts connections; a check that only pings the port proves less. Point the healthcheck at an endpoint that actually exercises the app, like a /health route that touches its dependencies.

`depends_on: condition: service_healthy` does nothing

The dependency has no healthcheck, so it can never report healthy. Add a healthcheck: block to the service you are waiting on.

The container keeps restarting forever

A restart policy plus a container that crashes instantly is a crash loop. Use on-failure:<n> to cap retries while you debug, check docker logs, and fix the underlying crash before switching back to unless-stopped.

My `.env` changes are ignored

Compose reads .env from the project directory for variable substitution, and env_file: for what a service sees. Make sure you edited the right one, and recreate the container (docker compose up -d again) so it picks up the new values.

Where to go next

Your containers now behave: they report health, respect limits, recover from crashes, and take config cleanly. The next step is making them safe.

Next in this series: Docker Security Basics, running as non-root, mounting the filesystem read-only, dropping capabilities, and keeping secrets out of images.

Verified on 2026-09-11 on a real Ubuntu 24.04.5 LTS system (arm64) with Docker Engine 29.8.0 and Compose v5.5.1. Captured: healthcheck transitions healthy/unhealthy/healthy; a Compose stack where db went Started to Waiting to Healthy before web started; a memory-limited container OOM-killed with ExitCode 137; a --cpus=0.5 busy loop held at 49.71% in docker stats; a crashing container restarted to RestartCount 3 under on-failure:3; -e overriding --env-file; and deploy.resources.limits applied as 134217728 bytes / 500000000 nanocpus on the web container.

Where Your Data Lives: Docker Volumes, Bind Mounts, and Networks

Shubham Sharma — Thu, 01 Oct 2026 14:00:09 +0000

Here is a fact that surprises people the first time it bites them: when you remove a container, everything it wrote is gone. A container's filesystem is a temporary layer that is thrown away with the container. Restart your database container after an upgrade and, if you did nothing special, your data went with it.

The fix is to keep data outside the container. Docker gives you two ways to do that, volumes and bind mounts, plus a private network so your containers can find each other. This post covers all three, with real commands and output captured on a live Docker Engine.

Tip

Key takeaways

A container's own filesystem is ephemeral. Anything you want to keep must live in a volume or a bind mount.

Named volumes are managed by Docker and are the right default for databases and app data. They survive docker rm.

Bind mounts map a specific host folder into the container, ideal for serving or editing live files during development.

Back up a volume by running a throwaway container that tars its contents. Restore is the same trick in reverse.

On a user-defined network, containers reach each other by name through Docker's built-in DNS. The default bridge does not do this.

Info

Get the code. The compose file, scripts, and net-demo are in the docker-foundations repo, under 06-volumes-networks/. Clone it to follow along.

Prerequisites

Docker installed and running. See Install Docker on macOS, Windows (WSL2), and Linux.
The basics of starting and removing containers from Run Your First Containers.

Named volumes: data that survives

A named volume is storage that Docker manages for you, separate from any container. You attach it with -v <name>:<path-in-container>. Let us prove it survives a container being destroyed and recreated.

Create a volume and start Postgres on it:

docker volume create demo_pgdata
docker run -d --name pg \
  -e POSTGRES_PASSWORD=demo -e POSTGRES_USER=demo -e POSTGRES_DB=demo \
  -v demo_pgdata:/var/lib/postgresql/data postgres:16-alpine

Give Postgres a few seconds to initialize, then write a row:

docker exec pg psql -U demo -d demo \
  -c "CREATE TABLE notes(id serial primary key, body text);
      INSERT INTO notes(body) VALUES ('survives a container rebuild');"

CREATE TABLE
INSERT 0 1

Now destroy the container completely, then start a brand new one on the same volume and read the row back:

docker rm -f pg
docker run -d --name pg2 \
  -e POSTGRES_PASSWORD=demo -e POSTGRES_USER=demo -e POSTGRES_DB=demo \
  -v demo_pgdata:/var/lib/postgresql/data postgres:16-alpine
docker exec pg2 psql -U demo -d demo -c "SELECT * FROM notes;"

 id |             body
----+------------------------------
  1 | survives a container rebuild
(1 row)

The container was deleted and a new one created, and the data was still there. That is the whole point of a named volume. This is also why, in the Compose post, Postgres used a pgdata volume: without it, tearing the stack down and bringing it back up would start from an empty database.

Bind mounts: live files from the host

A bind mount maps a specific folder on your machine into the container. Changes on the host show up instantly inside the container, which is perfect for development. The syntax is the same -v, but the left side is a host path instead of a volume name.

Serve a folder with nginx:

echo "<h1>version one</h1>" > ./site/index.html
docker run -d --name web -p 8080:80 \
  -v "$PWD/site":/usr/share/nginx/html:ro nginx:alpine
curl -s localhost:8080

<h1>version one</h1>

Now edit the file on the host and request the page again. No restart, no rebuild:

echo "<h1>version two, edited on the host</h1>" > ./site/index.html
curl -s localhost:8080

<h1>version two, edited on the host</h1>

The container is serving your host files directly. The :ro on the end mounts them read only, which is a good habit when the container has no business writing back.

Info

Which one do I use? Use a named volume for data the application owns, like a database, a cache, or uploaded files. You do not care where on disk it lives, only that it persists and is easy to back up. Use a bind mount when you need a specific host folder, most often your source code during development or a config file you edit by hand. Rule of thumb: named volumes for state, bind mounts for code and config.

Back up and restore a volume

Because a named volume is just a directory Docker manages, you can back it up by running a tiny throwaway container that mounts the volume and tars it to a folder on your host.

Back it up:

docker run --rm \
  -v demo_pgdata:/data:ro \
  -v "$PWD/backup":/backup \
  alpine tar czf /backup/demo_pgdata.tar.gz -C /data .
du -h backup/demo_pgdata.tar.gz

6.4M    backup/demo_pgdata.tar.gz

The alpine container mounts the volume at /data and your host folder at /backup, tars one into the other, and exits. Restore is the same move in reverse: create a fresh volume and untar into it.

docker volume create demo_pgdata_restored
docker run --rm \
  -v demo_pgdata_restored:/data \
  -v "$PWD/backup":/backup \
  alpine sh -c "tar xzf /backup/demo_pgdata.tar.gz -C /data"

Prove the restored copy is real by running Postgres on it and checking the row:

docker run -d --name pg3 \
  -e POSTGRES_PASSWORD=demo -e POSTGRES_USER=demo -e POSTGRES_DB=demo \
  -v demo_pgdata_restored:/var/lib/postgresql/data postgres:16-alpine
docker exec pg3 psql -U demo -d demo -c "SELECT body FROM notes;"

             body
------------------------------
 survives a container rebuild
(1 row)

You can wrap these two commands in small backup-volume.sh and restore-volume.sh scripts to reuse the pattern on any volume.

Warning

For a live database, prefer its own dump tool. Tarring the volume is perfect for static data and for moving a volume between machines. For a database that is actively being written to, a consistent backup is safer with the database's own tool (pg_dump for Postgres) so you do not capture a half-written file. Tar the volume when the container is stopped, or use pg_dump while it runs.

Networks: containers that find each other by name

By default, containers you start with docker run land on the default bridge network, where they can only reach each other by IP address. Create your own user-defined network and you get something much better: Docker runs an embedded DNS server, so containers resolve each other by name.

docker network create appnet
docker run -d --name web1 --network appnet nginx:alpine

From another container on the same network, look up web1 by name:

docker run --rm --network appnet busybox nslookup web1

Address:    127.0.0.11:53
Non-authoritative answer:
Name:   web1
Address: 172.18.0.2

That answer came from Docker's built-in resolver at 127.0.0.11. And because the name resolves, you can just talk to the service:

docker run --rm --network appnet alpine \
  sh -c "wget -qO- http://web1 | grep -i '<title>'"

<title>Welcome to nginx!</title>

docker network inspect shows who is attached:

docker network inspect appnet --format '{{range .Containers}}{{.Name}} -> {{.IPv4Address}}{{println}}{{end}}'

web1 -> 172.18.0.2/16

This is exactly why Compose works the way it does: Compose puts your services on a user-defined network automatically, which is why the API in the Compose post could connect to postgres by name without ever knowing its IP.

Warning

The default bridge has no name resolution. Containers started without --network share the default bridge, where DNS by name does not work; you would have to use IP addresses, which change. Always create a user-defined network (or use Compose, which does it for you) when containers need to talk.

Doing it in Compose

You rarely type these flags by hand for a real app. In Compose, a named volume and a bind mount look like this, and the network is created for you:

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: demo
      POSTGRES_DB: demo
    volumes:
      - pgdata:/var/lib/postgresql/data   # named volume: managed by Docker, survives rebuilds

  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro   # bind mount: serves live files from the host

volumes:
  pgdata:

docker compose up creates the pgdata volume, wires the bind mount, and puts both services on a shared network where web could reach db by name.

Common gotchas

My data still disappeared

You probably used an anonymous volume or none at all. Check that the -v name:/path left side is a real volume name, and that the path on the right is where the app actually writes (/var/lib/postgresql/data for Postgres). docker volume ls shows your named volumes.

`docker compose down -v` wiped my database

That is what -v does: it removes named volumes along with the containers. Use plain docker compose down to keep your data, and reserve -v for a deliberate clean slate.

Bind mount shows an empty directory

The host path was wrong or did not exist. Docker creates a missing bind-mount source as an empty directory rather than failing, so a typo silently mounts nothing. Use an absolute path (or $PWD/...) and confirm the folder exists.

Permission denied inside the container

The container process runs as a specific user, and bind-mounted host files keep their host ownership. If the container cannot read or write them, line up the ownership, or use a named volume (which Docker initializes with the right permissions) instead.

Containers cannot reach each other

They are on the default bridge. Put them on the same user-defined network (docker network create then --network, or let Compose do it) so name resolution works.

Where to go next

Your data now outlives your containers and your services can find each other. The series continues with getting images off your machine and operating containers day to day.

Next in this series: Docker Images and Registries, tagging and pushing an image so you can pull it anywhere.

Verified on 2026-09-10 on a real Ubuntu 24.04.5 LTS system (arm64) with Docker Engine 29.8.0. Captured: a named volume (demo_pgdata) retaining a Postgres row across a full docker rm -f and recreate; a bind mount serving version one then version two after a host edit with no restart; a volume backed up to a 6.4M tar.gz via an alpine sidecar and restored into a new volume with the row intact; and on a user-defined network, nslookup web1 resolving to 172.18.0.2 via Docker's 127.0.0.11 resolver plus wget http://web1 returning the nginx welcome page.

Lean Docker Images: Multi-Stage Builds and Layer Caching

Shubham Sharma — Mon, 28 Sep 2026 14:00:02 +0000

In the last post we ran a Node API with Compose using a stock node image and a bind mount. That is great for development, but it is not how you ship. To deploy, you build an image: a self-contained artifact with your code and its dependencies baked in. The catch is that the obvious way to write that Dockerfile produces an image that is enormous and slow to rebuild.

In this post we build the same API two ways. First the naive version that just works, then an optimized multi-stage version, and we measure the difference. Every number below was captured on a real Docker Engine.

Tip

Key takeaways

A naive FROM node:22 image here was 1.62GB. The multi-stage, Alpine-based version was 233MB, about 7 times smaller.

Most of the size is the base image. node:22 is 1.62GB; node:22-alpine is 227MB.

Order your Dockerfile for the cache. Copy package.json and the lockfile first, install, then copy the rest. A code change should not reinstall your dependencies.

Multi-stage builds let you install and build in one stage and ship only the result, so build tools never reach the final image.

Add a .dockerignore so junk like node_modules and .git never enters the build.

Info

Get the code. Both Dockerfiles and the app are in the docker-foundations repo, under 04-dockerfiles/. Clone it to follow along.

Prerequisites

Docker installed and running. See Install Docker on macOS, Windows (WSL2), and Linux if you need it.
The app from Docker Compose: Run a Multi-Service Stack. We reuse its server.js and package.json. You do not need Postgres or Redis running to build the image; we are packaging the app, not starting it.

Attempt 1: the naive Dockerfile

Here is the version almost everyone writes first. It works, and that is the problem: it hides how much room there is to improve.

# The naive way: everything works, nothing is optimized.
FROM node:22
WORKDIR /app
COPY . .
RUN npm install
EXPOSE 3000
CMD ["node", "server.js"]

Build it and check the size:

docker build -f Dockerfile.naive -t demo-api:naive .
docker images demo-api --format "table {{.Repository}}:{{.Tag}}\t{{.Size}}"

REPOSITORY:TAG   SIZE
demo-api:naive   1.62GB

1.62GB for a tiny API. Two problems are baked in:

The base image is huge. FROM node:22 pulls the full Debian-based Node image, which is 1.62GB on its own. Our app adds almost nothing on top, so the base is essentially the whole image.
The layer order defeats the cache. COPY . . copies your source before npm install runs. Docker caches each instruction, but a layer's cache is invalid the moment any input changes. Since your source changes constantly, that COPY busts on every edit, which forces npm install to run again every single build.

Attempt 2: the optimized multi-stage Dockerfile

Now the version you actually want. It fixes both problems: a small base, and an order that keeps dependencies cached.

# The optimized way: multi-stage build, slim base, production deps only,
# and cache-friendly ordering so code changes do not reinstall dependencies.

# Stage 1: install only production dependencies.
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

# Stage 2: the final runtime image. It carries only the app and its
# production node_modules, on a small Alpine base.
FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY server.js ./
EXPOSE 3000
CMD ["node", "server.js"]

And a .dockerignore so the build context stays clean:

node_modules
npm-debug.log
.git
.gitignore
.env
Dockerfile*
.dockerignore

Build it and compare:

docker build -f Dockerfile -t demo-api:slim .
docker images demo-api --format "table {{.Repository}}:{{.Tag}}\t{{.Size}}"

REPOSITORY:TAG   SIZE
demo-api:slim    233MB
demo-api:naive   1.62GB

233MB versus 1.62GB. Same app, about one seventh the size. Three changes did the work.

1. A smaller base image

node:22-alpine is 227MB against node:22 at 1.62GB. Alpine is a minimal Linux distribution, so you drop a whole Debian userland you were not using. For most Node apps, Alpine is all you need. When you want to go even smaller and more locked down, distroless images are the next step, but Alpine is the easy, safe default.

2. Multi-stage: build in one stage, ship another

The file has two FROM lines, so two stages. The deps stage installs dependencies. The final stage starts fresh from a clean Alpine and copies in only what it needs with COPY --from=deps. Anything that existed only in the build stage never reaches the final image: caches, temporary files, dev tooling. Our app is simple, but this is the pattern that keeps compilers and build caches out of production images for TypeScript, Go, and everything else.

3. Production dependencies only

npm ci --omit=dev installs just the runtime dependencies and skips devDependencies like test runners and linters. (This demo only declares two runtime dependencies, so --omit=dev changes nothing here; it is the habit that pays off the moment you add real devDependencies.) Combined with ENV NODE_ENV=production, the final image carries only what it needs to run. npm ci also requires a committed package-lock.json, which makes the install reproducible: the same versions every time, on every machine.

Prove the cache works

Size is the headline, but the day-to-day win is rebuild speed. Make a one-line change and rebuild both images:

echo "// a small change" >> server.js
docker build --progress=plain -f Dockerfile.naive -t demo-api:naive .   # naive
docker build --progress=plain -f Dockerfile -t demo-api:slim .           # optimized

On the naive build, the COPY . . layer sees the changed file, so its cache is invalid and everything after it re-runs, including npm install:

#7 [3/4] COPY . .
#7 DONE 0.1s
#8 [4/4] RUN npm install
#8 DONE 1.6s

On the optimized build, the code change only affects the final COPY server.js. The dependency stage did not change, so BuildKit reuses it:

#6 [deps 3/4] COPY package.json package-lock.json ./
#6 CACHED
#8 [deps 4/4] RUN npm ci --omit=dev
#8 CACHED
#9 [stage-1 3/4] COPY --from=deps /app/node_modules ./node_modules
#9 CACHED
#10 [stage-1 4/4] COPY server.js ./
#10 DONE 0.2s

That CACHED on npm ci is the whole point. Your dependencies are installed once and reused until package.json or the lockfile actually changes.

Info

Be honest about the numbers. Because this demo app depends on just two small packages, the rebuild time difference here is only about a second. The payoff scales with your dependency tree: on a real app with hundreds of packages, a cached dependency layer turns a minute-long reinstall into an instant rebuild. The image-size win, on the other hand, is large no matter what.

Look at the layers

docker history shows what each layer contributes to the final image:

docker history demo-api:slim

SIZE     CREATED BY
0B       CMD ["node" "server.js"]
0B       EXPOSE [3000/tcp]
4.1kB    COPY server.js ./
5.71MB   COPY /app/node_modules ./node_modules
0B       ENV NODE_ENV=production
0B       WORKDIR /app
...      (node:22-alpine base layers, ~227MB)

Your application is the top few layers: a 4.1kB source file and a 5.71MB node_modules. Everything else is the Alpine base. There is nothing left to trim without changing the base image itself.

Common gotchas

`npm ci` fails with "no package-lock.json found"

npm ci requires a committed lockfile. Generate one with npm install (or npm install --package-lock-only) and commit package-lock.json. This is a feature: it is what makes the build reproducible.

Alpine build fails on a native module

Some npm packages compile native code and expect the GNU C library, while Alpine uses musl. If a dependency fails to build on Alpine, either add the build toolchain in the deps stage (apk add --no-cache python3 make g++) or switch the base to node:22-slim, a smaller Debian image that keeps glibc.

The image is still huge

Check three things: are you on an Alpine or slim base, are you running npm ci --omit=dev rather than a full install, and do you have a .dockerignore so node_modules and .git are not copied in. Missing any one of these puts the weight back.

Reordering did not help

Make sure COPY package.json package-lock.json ./ comes before the source COPY, and that only those two files are in that first copy. If you COPY . . before installing, you are back to busting the cache on every change.

Where to go next

You now have a lean, cache-friendly image. The next step is getting it off your machine so you (or your CI) can pull it anywhere.

Next in this series: Docker Images and Registries, where we tag the image and push it to Docker Hub and GitHub Container Registry, then pull it back and inspect what is really inside.

Verified on 2026-09-10 on a real Ubuntu 24.04.5 LTS system (arm64, an OrbStack VM on Apple Silicon; on amd64 the exact byte counts differ slightly) with Docker Engine 29.8.0 (BuildKit). Both images were built from the same app: the naive node:22 image measured 1.62GB and the multi-stage node:22-alpine image 233MB (docker images), base images node:22 (1.62GB) and node:22-alpine (227MB). After a one-line change to server.js, the naive rebuild re-ran RUN npm install while the optimized rebuild showed CACHED on the deps stage (COPY package.json package-lock.json and RUN npm ci --omit=dev), re-running only COPY server.js. The docker history layer sizes are from that build.

Docker Compose: Run a Multi-Service Stack (Web + Postgres + Redis)

Shubham Sharma — Fri, 25 Sep 2026 14:00:05 +0000

Running one container is easy. Real applications are never one container though. A typical web app is a server, a database, and a cache, all running together and talking to each other. Starting each one by hand with the right flags, in the right order, on the right network, gets old immediately.

Docker Compose fixes that. You describe every service once in a single YAML file, then bring the whole stack up with one command. In this post we build a real three service stack, a Node API backed by Postgres and Redis, and drive it end to end: up, prove the services are talking, then down. Every command and its output below was captured on a real Docker Engine.

Tip

Key takeaways

Compose describes a multi-service app in one docker-compose.yml, brought up with docker compose up.

Containers on the same Compose network reach each other by service name (the API connects to postgres:5432 and redis:6379, no IPs).

Publish only what the outside world needs. Here only the API gets a host port; Postgres and Redis stay private on the Compose network.

depends_on controls start order, not readiness. Your app still needs to retry the first connection.

Keep secrets in a .env file that you never commit, and reference them from the Compose file.

Info

Get the code. Every file in this post is in the docker-foundations repo, under 03-compose-stack/. Clone it to follow along.

Prerequisites

Docker installed and running. If you need it, see Install Docker on macOS, Windows (WSL2), and Linux.
Comfort with single containers helps. If docker run, ps, and logs are new, start with Run Your First Containers.
Modern Docker ships Compose as the docker compose subcommand. Check yours with docker compose version.

What Compose actually is

Compose is one YAML file plus one command. Instead of a pile of docker run lines, you declare each service (its image, ports, environment, volumes, and dependencies) in docker-compose.yml, and Compose creates them together on a shared private network. On that network, every service can reach every other by its service name, which is the piece that makes multi-container apps sane.

We will build this stack:

api: a small Node HTTP server on port 3000, published to your machine on 8080.
postgres: a Postgres 16 database, private to the stack.
redis: a Redis 7 cache, private to the stack.

The API writes a row to Postgres and increments a counter in Redis on every request, which proves all three are wired together.

The project

Five small files. Here is the layout:

compose-stack/
  docker-compose.yml
  .env.example
  app/
    package.json
    server.js
  db/
    init.sql

docker-compose.yml

services:
  api:
    image: node:22-alpine
    working_dir: /app
    command: sh -c "npm install --no-audit --no-fund && node server.js"
    ports:
      - "8080:3000"
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://redis:6379
    volumes:
      - ./app:/app
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql:ro

  redis:
    image: redis:7-alpine

volumes:
  pgdata:

A few things worth pointing out:

No version: line. Modern Compose treats the old top-level version field as obsolete and ignores it. If you see it in older tutorials, you can delete it.
Service-name hostnames. The API's DATABASE_URL points at the host postgres, and REDIS_URL at redis. Those are the service names, and Compose resolves them on the shared network. You never hardcode an IP.
Only the API publishes a port. ports: "8080:3000" exposes the API to your machine. Postgres and Redis have no ports entry, so they are reachable only by other services in the stack, not from your host or the internet. That is exactly what you want for a database.
depends_on makes Compose start Postgres and Redis before the API. Read the readiness note below, because this does less than it looks.
A named volume, pgdata, keeps the database on disk so data survives down and restarts. init.sql is mounted into Postgres's init directory and runs once when the volume is first created.

app/server.js

The app is deliberately tiny. On each request it bumps a Redis counter and inserts a Postgres row, then returns both:

const http = require("http");
const { Pool } = require("pg");
const { createClient } = require("redis");

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const redis = createClient({ url: process.env.REDIS_URL });
redis.on("error", (e) => console.error("redis error:", e.message));

// depends_on waits for the container to start, not for the service to be ready,
// so retry the first connection to Postgres and Redis.
async function withRetry(fn, label, tries = 30) {
  for (let i = 1; i <= tries; i++) {
    try {
      return await fn();
    } catch (e) {
      console.log(`waiting for ${label} (${i}/${tries}): ${e.message}`);
      await new Promise((r) => setTimeout(r, 1500));
    }
  }
  throw new Error(`${label} not ready after ${tries} tries`);
}

async function start() {
  await withRetry(() => pool.query("SELECT 1"), "postgres");
  await withRetry(() => redis.connect(), "redis");
  console.log("connected to postgres and redis");

  const server = http.createServer(async (req, res) => {
    try {
      const visits = await redis.incr("visits");
      const inserted = await pool.query(
        "INSERT INTO hits (path) VALUES ($1) RETURNING id",
        [req.url]
      );
      const total = await pool.query("SELECT COUNT(*)::int AS count FROM hits");
      res.setHeader("Content-Type", "application/json");
      res.end(
        JSON.stringify(
          {
            message: "API is talking to Postgres and Redis over the Compose network",
            redis_visits: visits,
            postgres_hit_id: inserted.rows[0].id,
            postgres_total_hits: total.rows[0].count,
          },
          null,
          2
        ) + "\n"
      );
    } catch (e) {
      res.statusCode = 500;
      res.end(JSON.stringify({ error: e.message }) + "\n");
    }
  });

  server.listen(3000, () => console.log("api listening on port 3000"));
}

start();

The redis.on("error", ...) line matters more than it looks. In node-redis, the client emits an error event while it cannot reach the server, and an error event with no listener is thrown and takes the process down. That is exactly the window this app is built to survive, so the handler stays. Each request is wrapped in a try/catch too, so a transient query failure returns a 500 instead of crashing the server.

Notice there is no Dockerfile here. The API uses the stock node:22-alpine image, bind-mounts your code in, and runs npm install at startup. That is fine for local development and keeps this post focused on Compose. Building a proper image with a Dockerfile is the next post in the series.

db/init.sql and .env.example

CREATE TABLE IF NOT EXISTS hits (
  id SERIAL PRIMARY KEY,
  path TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

# .env.example  (copy to .env, which you never commit)
POSTGRES_USER=demo
POSTGRES_PASSWORD=change_me_in_a_real_project
POSTGRES_DB=demo

Compose automatically reads a file named .env in the project directory and substitutes those values into ${POSTGRES_USER} and friends. Commit .env.example so people know which variables to set, and keep the real .env out of git.

Bring the stack up

Copy the example env file, then start everything in the background:

cp .env.example .env
docker compose up -d

Compose creates the network and volume, then starts the services in dependency order:

 Network compose-stack_default   Created
 Volume compose-stack_pgdata     Created
 Container compose-stack-postgres-1  Started
 Container compose-stack-redis-1     Started
 Container compose-stack-api-1       Started

Check what is running:

docker compose ps

SERVICE    IMAGE                STATUS         PORTS
api        node:22-alpine       Up 23 seconds  0.0.0.0:8080->3000/tcp
postgres   postgres:16-alpine   Up 23 seconds  5432/tcp
redis      redis:7-alpine       Up 23 seconds  6379/tcp

Look at the PORTS column. Only api has a 0.0.0.0:8080->3000 mapping, so only the API is reachable from your machine. Postgres and Redis show their internal ports with no host mapping: private to the stack.

Prove the services are talking

Hit the API twice, at two different paths:

curl -s localhost:8080/

{
  "message": "API is talking to Postgres and Redis over the Compose network",
  "redis_visits": 1,
  "postgres_hit_id": 1,
  "postgres_total_hits": 1
}

curl -s localhost:8080/hello

{
  "message": "API is talking to Postgres and Redis over the Compose network",
  "redis_visits": 2,
  "postgres_hit_id": 2,
  "postgres_total_hits": 2
}

Both counters went up, which means each request really did reach both stores. You can confirm the data landed by reading each service directly with docker compose exec:

docker compose exec redis redis-cli GET visits

docker compose exec postgres psql -U demo -d demo -c "SELECT id, path FROM hits ORDER BY id;"

 id |  path
----+--------
  1 | /
  2 | /hello
(2 rows)

The Redis counter is at 2, and Postgres has both requests recorded, one row per call. Three separate containers, cooperating over a private network, from one YAML file.

How the wiring works

The mechanism is the Compose network. When Compose brings the stack up, it puts all services on one user-defined bridge network and registers each service name as a DNS name on it. So inside the API container, postgres resolves to the Postgres container and redis to the Redis container. That is why DATABASE_URL can say @postgres:5432 and just work, with no IP addresses and no links.

Warning

depends_on is start order, not readiness. Compose starts Postgres and Redis before the API, but "started" only means the container process launched, not that Postgres is accepting connections yet. On a cold start the database can need a second or two to come up, and if the API tries to connect first it will fail. That is why the API retries its first connection: if the database is slow to accept connections, you will see a few waiting for postgres lines in the API logs before connected. Do not rely on depends_on alone; make your app tolerant of a not-ready dependency, or add a healthcheck.

Once it is up, the API logs confirm it connected:

docker compose logs api

api-1  | connected to postgres and redis
api-1  | api listening on port 3000

Tear it down

Stop and remove the whole stack in one command:

docker compose down

 Container compose-stack-api-1       Removed
 Container compose-stack-postgres-1  Removed
 Container compose-stack-redis-1     Removed
 Network compose-stack_default       Removed

docker compose down removes the containers and the network but keeps the named volume, so your database survives. When you want a truly clean slate, including the data, add the volume flag:

docker compose down -v

Warning

down -v deletes your data. The -v flag removes named volumes too, which wipes the Postgres database. Use it when you want a fresh start, not on anything you care about.

Common gotchas

"port is already allocated" on 8080

Another process is using host port 8080. Change the API's mapping to something free, for example "8081:3000", and browse to 8081.

The API crashes or logs endless "waiting for postgres"

Usually the credentials do not match. The API's DATABASE_URL and the Postgres service must use the same POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB. Since both read from .env, make sure .env exists (copy it from .env.example).

Changes to init.sql do not take effect

init.sql only runs when the Postgres data volume is first created. If you already ran the stack, the volume exists, so edits are ignored. Recreate it with docker compose down -v and bring the stack back up.

`version` warning on `up`

If Compose warns that the version field is obsolete, delete the top-level version: line. Modern Compose does not use it.

Where to go next

You now have a reproducible multi-service stack that starts and stops with one command. The API still installs its dependencies at runtime, which is slow and not how you ship to production.

Next in this series: Lean Docker Images, where we write a real Dockerfile for the API, then cut its size and build time with multi-stage builds and layer caching.

Verified on 2026-09-10 on a real Ubuntu 24.04.5 LTS system with Docker Engine 29.8.0 and Docker Compose v5.5.1. The full stack (node:22-alpine, postgres:16-alpine, redis:7-alpine) was brought up with docker compose up -d, and the outputs shown come from that run (trimmed for width, and shown under the compose-stack project name this post uses): docker compose ps, the two curl round-trips (Redis counter and Postgres rows both incrementing), redis-cli GET visits returning 2, the psql query returning both rows, the api logs, and docker compose down.

Docker Security Basics: Non-Root, Read-Only, Image Scanning, and Secrets

Shubham Sharma — Tue, 22 Sep 2026 14:00:05 +0000

A container that runs is not a container that is safe. By default, a container runs as root, with a writable filesystem, the full set of Linux capabilities, and often a secret or two baked into the image. All of it is fixable. This post hardens a container step by step, without breaking it, and measures each change on a real Docker Engine.

Tip

Key takeaways

Scan your image. A slim base is not just smaller, it is safer: node:22 carried 533 high or critical OS CVEs, node:22-alpine carried 2.

Do not run as root. Add a non-root USER (or user: in Compose) so a container breakout is not instant host root.

Make the root filesystem read-only with read_only: true, and add a tmpfs for the few paths that must be writable.

Drop all capabilities with cap_drop: ALL, add back only what you need, and set no-new-privileges.

Keep secrets out of the image. Use Compose secrets: at run time and RUN --mount=type=secret at build time. Never ENV or COPY a secret.

Prerequisites

Docker installed and running. See Install Docker on macOS, Windows (WSL2), and Linux.
The lean multi-stage image from Lean Docker Images; we build on that slim base here.

Info

Get the code. The hardened Dockerfiles, compose file, and Trivy wrapper for this post are in the docker-foundations repo, under 08-security/. Clone it to follow along.

Scan first: what is actually in your image

Before hardening anything, look at what you are shipping. Trivy scans an image and reports known CVEs. The easiest way to run it is as a container. Here it scans the full Debian-based node:22, counting only HIGH and CRITICAL OS-package vulnerabilities:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  aquasec/trivy:latest image --severity HIGH,CRITICAL --scanners vuln node:22

node:22 (debian 12.15)
Total: 533 (HIGH: 501, CRITICAL: 32)

533 high or critical vulnerabilities, 32 of them critical, before you have added a single line of your own code. Now scan the slim Alpine variant instead:

node:22-alpine (alpine 3.24.1)
Total: 2 (HIGH: 2, CRITICAL: 0)

Two. Same Node.js, a fraction of the attack surface, because Alpine ships almost none of the Debian userland those CVEs live in. (Trivy also reports the Node and npm packages bundled in the runtime, 11 either way; those live in the language layer, not the OS, so the base image does not change them.) This is the security half of the argument for a slim base, on top of the size win from the lean-images post. The scan.sh wrapper in the repo runs exactly this scan on any image.

Do not run as root

By default, the process inside a container runs as root. If an attacker escapes the container, or if a bind-mounted host path is involved, that root can become host root. The fix is a non-root user. The node images ship one called node (uid 1000); switch to it with a single USER line:

# Hardened: slim base, and run as the built-in non-root 'node' user.
FROM node:22-alpine
WORKDIR /app
COPY server.js ./
# node:22-alpine ships a non-root 'node' user (uid 1000)
USER node
EXPOSE 3000
CMD ["node", "server.js"]

Build and check who the container runs as:

docker build -t secure:hardened .
docker run --rm secure:hardened whoami
docker run --rm secure:hardened id -u

node
1000

Not root. That one line removes the most common and most dangerous default.

Warning

Do not put an inline comment on a USER line. Dockerfiles have no inline comments: USER node # ... sets the username to the whole string including the #, and the container fails to start with "unable to find user". Put comments on their own line.

Make the filesystem read-only

Most containers never need to write to their own filesystem at run time. If yours does not, mount it read-only so an attacker cannot drop a script or tamper with binaries. Compare a normal container with a read-only one:

docker run --rm alpine touch /test.txt
docker run --rm --read-only alpine touch /test.txt

# first command: writes fine
# second command:
touch: /test.txt: Read-only file system

For the paths that need to be writable (a cache, /tmp), add a tmpfs, which is an in-memory scratch space that never touches the image:

docker run --rm --read-only --tmpfs /tmp alpine touch /tmp/test.txt   # succeeds

Drop capabilities

A root process inside a container still holds a set of Linux capabilities, fine-grained powers like changing file ownership or binding low ports. Most apps need none of them. Drop them all and see the difference. chown needs CAP_CHOWN:

docker run --rm alpine chown nobody /tmp
docker run --rm --cap-drop ALL alpine chown nobody /tmp

# first command: chown succeeds
# second command:
chown: /tmp: Operation not permitted

With cap_drop: ALL the container cannot perform privileged operations, even as root. Add back only what you actually need with cap_add. Pair it with no-new-privileges:true, which stops a process from ever gaining more privileges (for example through a setuid binary).

Keep secrets out of the image

This is the one that bites teams hardest, because the mistake is invisible until someone pulls your image. The wrong way is to pass a token as a build arg and store it in the environment:

# ANTI-PATTERN. Do NOT do this. Shown only to prove the leak.
ARG API_TOKEN
ENV API_TOKEN=$API_TOKEN

Build that and the token is permanently in the image's metadata:

docker history --no-trunc secure:baked | grep API_TOKEN

API_TOKEN=supersecret-token-value

Anyone who can pull the image can read it. The right way for build-time secrets is BuildKit's --mount=type=secret, which exposes the secret only during one RUN and never writes it to a layer:

# syntax=docker/dockerfile:1
RUN --mount=type=secret,id=api_token \
    test -s /run/secrets/api_token && echo "secret was available at build time"

docker build --secret id=api_token,src=api_token.txt -f Dockerfile.buildsecret -t secure:buildsecret .
docker history --no-trunc secure:buildsecret | grep -c "supersecret-token-value"
docker run --rm secure:buildsecret cat /run/secrets/api_token

0
cat: can't open '/run/secrets/api_token': No such file or directory

Zero occurrences in the history, and the file does not exist in the final image. The secret did its job during the build and vanished. For run-time secrets, Compose has a secrets: block that mounts a file into the container at /run/secrets/, without putting it in the environment where docker inspect or a crash log would expose it.

Putting it all together

The stack's docker-compose.yml applies every one of these at once:

services:
  web:
    build: .
    image: secure-demo
    ports:
      - "8080:3000"
    read_only: true            # the container's root filesystem is read-only
    tmpfs:
      - /tmp                    # a small writable scratch space in memory
    cap_drop:
      - ALL                     # drop every Linux capability
    security_opt:
      - no-new-privileges:true  # process can never gain more privileges
    secrets:
      - api_token               # mounted at /run/secrets/api_token, not in env

secrets:
  api_token:
    file: ./api_token.txt

Bring it up and check the result:

docker compose up -d
curl localhost:8080

secure demo. running as uid 1000. secret mounted: true

Non-root, and the secret arrived as a mounted file, not an environment variable. Confirm the hardening holds from inside the container:

docker compose exec web env | grep -i token     # nothing: the token is not in the environment
docker compose exec web touch /oops.txt

touch: /oops.txt: Read-only file system

The token is nowhere in the environment, and the read-only filesystem refuses the write. That is a container an attacker has very little room to work with.

The hardening checklist

Success

For any container you run in production:

Start from a slim base and scan it (node:22-alpine had 2 OS CVEs versus 533 for node:22).

Run as a non-root user (USER, or user: in Compose).

Set read_only: true and add a tmpfs for writable paths.

cap_drop: ALL, then cap_add only what you need.

Set no-new-privileges:true.

Keep secrets out of the image: Compose secrets: at run time, RUN --mount=type=secret at build time. Never ENV or COPY a secret.

Common gotchas

The app breaks under `read_only: true`

It is trying to write somewhere. Find the path (logs, cache, a pid file) and add it as a tmpfs or a named volume, rather than removing read_only.

The app breaks under `cap_drop: ALL`

It needs a capability. The common one is binding a port below 1024, which needs CAP_NET_BIND_SERVICE. Add just that back with cap_add, or publish a high port and map it. Better still, run the app on a high port and let the proxy handle 80 and 443.

A non-root container cannot write to a mounted volume

The volume is owned by root on the host. Set the volume's ownership to your container's uid, or use a named volume, which Docker initializes with the right permissions.

Trivy reports vulnerabilities you cannot fix

Some CVEs have no patched version yet. Focus on HIGH and CRITICAL with a fix available, keep your base image updated, and rescan regularly rather than chasing an empty report.

Where to go next

Your container is now scanned, non-root, read-only, capability-stripped, and free of baked-in secrets. The last foundational question is which engine to run it with.

Next in this series: Docker vs Podman, a hands-on comparison of the daemonless, rootless alternative and what actually changes when you migrate.

Verified on 2026-09-11 on a real Ubuntu 24.04.5 LTS system (arm64) with Docker Engine 29.8.0 (BuildKit). Captured: Trivy scans of node:22 (533 HIGH/CRITICAL OS CVEs, 32 critical) versus node:22-alpine (2, 0 critical); the hardened image running as uid 1000 (whoami node); --read-only refusing a write and --tmpfs allowing one; --cap-drop ALL turning a working chown into "Operation not permitted"; a BuildKit --mount=type=secret leaving zero occurrences of the token in docker history and no secret file in the image, versus an ARG/ENV build that printed API_TOKEN=supersecret-token-value in history; and the hardened Compose stack serving as uid 1000 with the secret mounted, no token in the environment, and a read-only root filesystem refusing touch /oops.txt.

Capstone: Dockerize Your Own App End to End

Shubham Sharma — Sat, 19 Sep 2026 14:00:01 +0000

This is the capstone of the Docker Foundations series. Instead of one new concept, it pulls the whole track together: you take a real app from source code to a live URL served over HTTPS, built into a lean image, hardened the way you would actually run it, pushed to a registry by CI, and deployed to a server. Every command below was run for real, first locally and then on an actual Ubuntu server.

Tip

Get the code: the app, the multi-stage Dockerfile, the production Compose file, the Caddy config, and the CI workflow are in the 10-capstone folder of the companion repo.

Info

Built and run on Docker Engine 29.8.0 with Compose v5.5.1, then deployed on a separate Ubuntu 24.04 server. The output shown is the genuine result.

The app

The app is deliberately small but real: an Express server backed by Postgres. It serves a page with a visit counter (so it has to read and write a database) and exposes a /healthz endpoint for health checks. The full source is in the repo; the only thing that matters here is that it is a normal app with a real dependency, not a toy that prints hello.

A lean image with a multi-stage build

The Dockerfile builds in two stages. The first installs production dependencies against the lockfile; the second copies just those dependencies and the source into a minimal runtime image that runs as a non-root user and declares a healthcheck:

# ---- deps: install production dependencies against the lockfile ----
FROM node:22-alpine AS deps
WORKDIR /app
COPY app/package.json app/package-lock.json ./
RUN npm ci --omit=dev

# ---- runtime: minimal image, non-root, with a healthcheck ----
FROM node:22-alpine AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY app/ ./
USER node
EXPOSE 3000
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
  CMD wget -q -O /dev/null http://localhost:3000/healthz || exit 1
CMD ["node", "server.js"]

Build it and check the size:

docker build -t tdm-capstone:local .
docker images tdm-capstone:local

tdm-capstone:local  233MB

Because the build tooling stays in the first stage, the final image carries only the Alpine base, the production node_modules, and the app. That is the multi-stage payoff from earlier in the series, applied to a real app.

The production stack

A single Compose file wires the app to Postgres and puts Caddy in front of it, and it turns on the operating and security practices from the rest of the series at once. The important parts:

  app:
    image: ${APP_IMAGE:-tdm-capstone:local}
    depends_on:
      db:
        condition: service_healthy   # do not start until Postgres is ready
    read_only: true                  # the app writes nothing to its own filesystem
    tmpfs:
      - /tmp
    cap_drop:
      - ALL                          # it needs no Linux capabilities
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O /dev/null http://localhost:3000/healthz || exit 1"]
      interval: 10s
      retries: 3
      start_period: 5s
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 128M

Bring it up, and the health gating sequences the whole stack for you:

docker compose -f compose.prod.yml up -d
docker compose -f compose.prod.yml ps --format "table {{.Service}}\t{{.Status}}"

SERVICE   STATUS
app       Up 23 seconds (healthy)
caddy     Up 18 seconds
db        Up 28 seconds (healthy)

Postgres becomes healthy first, the app waits for it and then becomes healthy itself, and only then does Caddy start. The app answers over HTTPS through Caddy, and the counter proves it is really talking to Postgres:

curl -k https://localhost

<!doctype html>...<p>This page has been served <strong>1</strong> times.</p>...

Hit it again and the count goes to 2. Now confirm the hardening actually took effect, not just that it is written in the file. The container runs as an unprivileged user:

docker compose -f compose.prod.yml exec app id

uid=1000(node) gid=1000(node) groups=1000(node)

Its root filesystem is read-only, so a compromised process cannot rewrite the app, while the /tmp tmpfs stays writable for scratch space:

docker compose -f compose.prod.yml exec app sh -c "touch /oops.txt"

touch: /oops.txt: Read-only file system

And the limits and dropped capabilities are real, straight from docker inspect:

ReadonlyRootfs=true  Memory=134217728  NanoCpus=500000000  CapDrop=[ALL]

That is 128MB of memory, half a CPU, every Linux capability dropped, and a read-only root, on a container that self-reports health. This one stack applies the Compose, volumes, operating, and security posts together.

Ship it: build in CI, push to GHCR

You do not build production images by hand on your laptop. A small GitHub Actions workflow builds the image on every push and pushes it to the GitHub Container Registry, authenticating with the token GitHub gives the job:

permissions:
  contents: read
  packages: write
jobs:
  build-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          context: ./10-capstone
          push: true
          tags: ghcr.io/<you>/tdm-capstone:latest

Pushing this to the repo ran the job green in about half a minute and published the image with its digest:

build-push  in 26s
pushing manifest for ghcr.io/<you>/tdm-capstone:latest@sha256:d6e8d6b6...

Your server can now pull a known, immutable image by tag or digest instead of building on the box. New images published this way are private by default, so to pull one on a server you would first run docker login ghcr.io (or make the package public in your GitHub package settings).

Deploy it with automatic HTTPS

The last step is a real server. Copy this folder up, set the environment, and run the same Compose file. The one new idea is the hostname: sslip.io is a free wildcard DNS service where a name like 203-0-113-5.sslip.io resolves to 203.0.113.5, which gives you a real hostname for any IP without buying a domain. Caddy uses that hostname to request a certificate:

# .env on the server
SITE_ADDRESS=<your-server-ip-with-dashes>.sslip.io

docker compose -f compose.prod.yml up -d
curl -k https://<your-server-ip-with-dashes>.sslip.io

<!doctype html>...<p>This page has been served <strong>1</strong> times.</p>...

That is the app, built from the same Dockerfile, running behind Caddy and answering over HTTPS at a real hostname, on a real server.

Warning

About the certificate: the lab server here has a private IP, which Let's Encrypt cannot reach to validate, so this deploy used Caddy's tls internal option (a local certificate authority) to prove the HTTPS path end to end. On a real VPS with a public IP, you delete the tls internal line and Caddy fetches a genuine, browser-trusted Let's Encrypt certificate for your sslip.io hostname automatically, with no domain purchase and no manual certbot step.

Tear it down

Everything is disposable, which is the point:

docker compose -f compose.prod.yml down -v

That stops and removes the containers, the network, and the named volumes.

What you built

You took an app with a database and turned it into a lean, non-root, resource-limited, health-checked image; ran it as a hardened stack behind a reverse proxy with HTTPS; had CI build and publish it to a registry; and deployed it to a server reachable over HTTPS with no domain purchase. That is the entire Docker Foundations series in one project.

If you worked through the whole track, from installing Docker and running your first containers, through Compose, lean images, volumes and networks, operating, and security, you now have every piece it takes to ship a container you built yourself. That is a genuinely production-shaped skill set, and everything here is in the companion repo for you to clone and run.

Docker Images vs Containers, Explained

Shubham Sharma — Mon, 14 Sep 2026 10:15:47 +0000

If you are new to Docker, this is probably the first thing that trips you up: people say "image" and "container" like they mean the same thing, and they absolutely do not. Getting this one distinction straight makes almost everything else about Docker click into place.

Here is the whole idea in one sentence: an image is the read-only template, and a container is a running copy made from it. If you have written any code, it is the same relationship as a class and an object, or a recipe and the meal you cook from it. One image, many containers.

Info

Everything below was run on a real Docker Engine (Server 29.8.0). The image IDs, container IDs, and sizes are the genuine output. The tables are trimmed to the columns that matter here, so what you see on your own machine will have a few more columns.

One image, many containers

Let's prove the relationship instead of just asserting it. First, pull an image once:

docker pull nginx:alpine

Now start three containers from that single image:

docker run -d --name c1 nginx:alpine
docker run -d --name c2 nginx:alpine
docker run -d --name c3 nginx:alpine

There is still only one image on disk:

docker images nginx

REPOSITORY   TAG      IMAGE ID       SIZE
nginx        alpine   72ba65eb42c1   104MB

But there are three separate containers, each with its own container ID, all pointing back at that same image:

docker ps

CONTAINER ID   IMAGE          NAMES
f291e8935b87   nginx:alpine   c3
dbbf21ab18e1   nginx:alpine   c2
01da24bab3c5   nginx:alpine   c1

One image (72ba65eb42c1), three containers (01da..., dbbf..., f291...). That is the core fact: the image is the shared, unchanging original, and each container is an independent running instance of it. This is exactly why Docker is efficient. Ten copies of the same app do not mean ten copies of its files on disk. They share one image.

Tip

Two quick commands map cleanly onto the two concepts: docker images lists your images (the templates), and docker ps lists your running containers (the instances). If you ever lose track of which is which, that pair is the tell.

Each container gets its own writable layer

If they all share one read-only image, how can containers be different from each other? Because when a container starts, Docker adds a thin writable layer on top of the image, just for that container. Anything the container changes goes into its own layer and touches nothing else.

Watch it happen. Write a file inside c1:

docker exec c1 sh -c "echo 'written inside c1' > /note.txt"
docker exec c1 cat /note.txt

written inside c1

Now look for that same file in c2, which was started from the identical image:

docker exec c2 cat /note.txt

cat: can't open '/note.txt': No such file or directory

The file exists in c1 and does not exist in c2, even though both came from the same image. Each container's changes live in its own private writable layer. The image underneath never changed.

Warning

That writable layer is created and destroyed with the container. Run docker rm c1 and the note.txt you wrote is gone for good. This is the number one surprise for beginners: data written inside a container is not permanent. When you need data to survive, you use a volume, which is the subject of its own guide in this series.

So what is an image, really?

An image is not one big blob. It is a stack of read-only layers, each one a set of filesystem changes from the step that built it. You can list them with docker image history. It prints newest layer first, so here are the top few (the --format flag just trims it to size and command for readability):

docker image history nginx:alpine --format "{{.Size}}\t{{.CreatedBy}}" | head -6

51.8MB   RUN /bin/sh -c set -x   && apkArch="$(cat ...
0B       ENV ACME_VERSION=0.4.1
0B       ENV NJS_RELEASE=1
0B       ENV NJS_VERSION=1.0.1
0B       CMD ["nginx" "-g" "daemon off;"]
0B       STOPSIGNAL SIGQUIT

Each line is a layer. Some add real files and have a size (the 51.8MB package install), others just set metadata like an environment variable or the default command and cost nothing. This is only the top of the list; the base Alpine layer and the rest of the image sit below these, which is where most of the 104MB actually lives. Every container you run from this image shares all of those read-only layers and simply adds its own empty writable layer on top. That shared design is why the three containers above cost you 104MB of image once, not 104MB three times.

The mental model to keep

Line the two up side by side and the distinction sticks:

An image is built, versioned, and read-only. You create it with a Dockerfile, tag it, push it to a registry, and pull it. It is the same for everyone who pulls it.
A container is run, started, stopped, and thrown away. It is one live instance of an image, with its own ID, its own writable layer, and its own lifecycle.

The commands follow the same split. docker build and docker pull deal in images. docker run, docker stop, and docker rm deal in containers. And docker run is simply the bridge between them: it takes an image and produces a running container.

Once that lands, the rest of Docker is mostly detail. Next in the Docker Foundations series, put it to work by running your first containers hands-on, then move up to Docker Compose to run several at once.

Fix: Permission Denied on the Docker Daemon Socket

Shubham Sharma — Mon, 14 Sep 2026 10:15:46 +0000

You ran a normal docker command on Linux and got this instead of output:

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

On older Docker versions the same problem reads a little differently, but it is the exact same wall:

Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

Nothing is broken. Docker is running fine. Your user account just is not allowed to talk to it yet. This guide shows you why that happens, the one-line fix that gets you working right now, the permanent fix, and the one "fix" you should never copy from a random forum answer.

Info

Everything below was run on a real Docker Engine (Client 29.8.0 / Server 29.8.0) on Ubuntu 24.04.5 LTS. The commands and output are the genuine results, not illustrations.

Why this happens

Docker does its real work in a background service (the daemon) that runs as root. Your docker command is just a client. It talks to the daemon through a Unix socket, a special file at /var/run/docker.sock. Look at who owns that file:

ls -l /var/run/docker.sock

srw-rw---- 1 root docker 0 Sep 10 15:41 /var/run/docker.sock

Read that line right to left. The socket is owned by user root and group docker, and its permissions are rw for the owner, rw for the group, and nothing for everyone else. So only root and members of the docker group can read from or write to it. A brand-new user is in neither:

id

uid=1000(tester) gid=1000(tester) groups=1000(tester)

No docker group in that list, so the connection is refused. That is the whole story. The error is a file-permission error wearing a scary costume.

Fix 1: run it right now with sudo

If you just need the command to work this second, run it as root with sudo:

sudo docker ps

NAMES     STATUS

The command connects and returns cleanly (an empty table here just means no containers are running). This is fine for a one-off, but typing sudo before every docker command gets old fast, and it means every container you start is being managed as root. For your own machine, set up the permanent fix instead.

Fix 2: add your user to the docker group (the real fix)

Add your user to the docker group once, and you never need sudo for Docker again:

sudo usermod -aG docker $USER

-aG means "append to this group" (the -a matters; without it you would replace all your other groups). Confirm it took:

id

uid=1000(tester) gid=1000(tester) groups=1000(tester),990(docker)

There is the docker group. But if you try docker ps in the same terminal, you may still get permission denied, and this is the step everyone trips on.

Warning

Group membership is only read when a login session starts. Your current shell was started before you joined the group, so it still has your old group list. You need a fresh session for the change to apply.

Get a fresh session in any one of these ways:

# option A: load the new group into the current shell right now
newgrp docker

# option B: log out and back in (or close and reopen your terminal)

# option C: over SSH, disconnect and reconnect

After that, Docker works as your normal user, no sudo:

docker ps

NAMES     STATUS

Connected, no permission error, no sudo. That is the fix you want.

The "fix" to avoid

Search this error and you will find answers telling you to just open up the socket:

# do NOT do this
sudo chmod 666 /var/run/docker.sock

It makes the error go away, and it is a genuinely bad idea. 666 lets every user and process on the machine read and write the Docker socket. Anyone who can talk to the Docker daemon can start a container that mounts your entire host filesystem as root, which is effectively handing them root on the box. The docker group already gives your user that same power, so understand what you are joining.

Error

Adding a user to the docker group (or opening the socket) grants root-equivalent access to the whole machine. That is expected and documented, but it means you should only do it for accounts you fully trust. On shared or production servers, prefer rootless Docker or calling Docker through sudo with a controlled sudoers rule.

Quick reference

# see who owns the socket (root:docker, group-only access)
ls -l /var/run/docker.sock

# right now, one-off
sudo docker ps

# permanent: join the group, then start a fresh session
sudo usermod -aG docker $USER
newgrp docker      # or log out and back in
docker ps          # works, no sudo

That is every legitimate way out of this error. If sudo docker ps also fails, your problem is different: the daemon itself is not running. Start it with sudo systemctl start docker and check sudo systemctl status docker.

New to Docker and want the mental model behind all this? Start with our guide on running your first containers, then work through the Docker Foundations series.

Docker Foundations: The Complete Hands-On Series (Install to Production)

Shubham Sharma — Sun, 13 Sep 2026 19:19:28 +0000

Docker is the front door to modern back-end and self-hosting work, and most tutorials drop you in the middle of it. This series does not. It starts from nothing and takes you all the way to an app you built, hardened, and deployed over HTTPS on a real server. Every guide is hands-on, and every command and number in them was run on real Docker and captured, not paraphrased.

Use this page as the map. Work straight down it if you are starting out, or jump to the piece you need.

Info

Every guide in this series is a real lab: the commands, output, image sizes, and errors are genuine, captured on Docker Engine 29.x. The runnable code for each one lives in the companion repo linked at the bottom.

The path, start to finish

1. Install Docker on macOS, Windows (WSL2), and Linux
One guide, three operating systems, ending in a verified docker run hello-world and the post-install checks each OS actually needs.

2. Run Your First Containers
The everyday lifecycle on a real nginx: run, ps, logs, exec, stop, start, and rm, plus the images-versus-containers mental model.

3. Docker Compose: Run a Multi-Service Stack
Move from single containers to a declarative Web plus Postgres plus Redis stack with one docker compose up, wired together over a Compose network.

4. Lean Docker Images: Multi-Stage Builds and Layer Caching
Cut the same app from a 1.62GB image to 233MB with a multi-stage build, and measure exactly why it shrank and why rebuilds get faster.

5. Where Your Data Lives: Volumes, Bind Mounts, and Networks
Make data survive restarts, back up and restore a volume, and connect containers by name on a user-defined network.

6. Operating Containers: Healthchecks, Limits, Restart Policies, and Env Config
Turn a working stack into one that behaves in production: health-gated startup, memory and CPU limits, self-healing restarts, and clean env config.

7. Docker Security Basics: Non-Root, Read-Only, Image Scanning, and Secrets
Harden a container without breaking it: scan for CVEs, run as non-root, mount the root filesystem read-only, drop capabilities, and keep secrets out of images.

8. Docker vs Podman: A Hands-On Comparison and Migration
Run the same images and Compose file under both engines to see what daemonless and rootless really change, and what it takes to migrate.

9. Capstone: Dockerize Your Own App End to End
Put it all together: a lean image, a hardened Compose stack, a CI build that pushes to a registry, and a deploy behind Caddy with automatic HTTPS.

Quick answers

Two short reads that clear up the questions almost everyone hits early:

Docker Images vs Containers, Explained proves the difference with real output: one image, many containers, each with its own writable layer.
Fix: Permission Denied on the Docker Daemon Socket explains the error every Linux beginner sees and the one permanent fix (plus the insecure one to avoid).

Tip

Get the code: every runnable lab in this series lives in the docker-foundations repo, one folder per post. Clone it and follow along.

Where to start

If you are new, begin at step 1 and go in order; each post builds on the last. If you already run containers, jump to Compose, security, or the capstone. By the end you will be able to build a lean image, run it as a hardened stack, and ship it to a server over HTTPS, all with tools you understand because you ran every step yourself.

LM Studio Guide: Run Local LLMs on Your Mac Fast

Shubham Sharma — Tue, 01 Sep 2026 13:56:57 +0000

LLMs are rapidly changing how we interact with technology, and thankfully, you don't need a supercomputer or a cloud subscription to experiment with them. LM Studio is a desktop application that lets you download and run a vast array of large language models right on your Mac. This guide will walk you through everything from understanding why you'd want to run models locally to getting your first AI model up and running.

What is LM Studio and Why Run AI Models on Your Mac

LM Studio is a game-changer for anyone curious about AI. It's a beautifully designed, user-friendly desktop application that simplifies the process of downloading, discovering, and running large language models (LLMs) directly on your computer. Think of it as an app store for AI, but instead of games or productivity tools, you're downloading powerful AI models that can generate text, write code, answer questions, and much more.

Privacy and Control Without the Cloud

One of the biggest advantages of running AI models locally with LM Studio is the unparalleled privacy and control you gain. When you use cloud-based AI services, your prompts and data are sent to remote servers, where they might be stored, analyzed, or used for training. With LM Studio, everything happens on your machine.

Running models locally means your conversations, your code snippets, and your sensitive data never leave your computer. This is a massive win for privacy-conscious users and developers who handle proprietary information.

This local execution also means you're not reliant on external APIs that can change their terms, pricing, or availability without notice. You have direct access to the AI's capabilities whenever you need them, internet connection or not.

What You'll Be Able to Do After Setup

Once LM Studio is up and running, a whole new world of AI-powered possibilities opens up on your Mac. You're not just running a demo; you're interacting with powerful AI that can assist you in numerous ways.

Here are just a few things you'll be able to do:

Text Generation: Brainstorm ideas, write blog posts, draft emails, create marketing copy, or even write poetry.
Code Completion: Get intelligent code suggestions, help with debugging, and understand complex code snippets, all within your local environment.
Chatbot Creation: Build your own personal chatbot for specific tasks or general conversation, trained on the models you download.
Summarization: Condense long documents or articles into concise summaries.
Translation: Experiment with language translation capabilities.
Creative Writing: Develop stories, scripts, or game narratives.

Tip

The beauty of LM Studio is its flexibility. You can swap out models easily, experiment with different AI personalities, and tailor the experience to your exact needs.

Check Your Mac's Readiness Before Installing

Before you dive into downloading LM Studio, it's crucial to ensure your Mac is up to the task. Running large language models, even locally, can be resource-intensive. Understanding your system's capabilities will help you set realistic expectations and avoid potential performance issues.

Minimum vs. Recommended Specs

The performance of AI models heavily depends on your hardware. While LM Studio can technically run on a range of Macs, some configurations will offer a much smoother experience than others.

Component	Minimum Specs (Basic Functionality)	Recommended Specs (Smooth Experience)	Notes
RAM	8 GB	16 GB or more	More RAM allows for larger models and faster processing.
Storage	50 GB free space	100 GB+ free space	Models can be several gigabytes each.
Processor	Intel Core i5 or Apple M1 (base)	Apple M1 Pro/Max/Ultra, M2, M3 series (or higher Intel)	Apple Silicon (M-series) chips offer significant performance advantages.
GPU	Integrated Graphics	Dedicated GPU (if available) or Apple Silicon GPU	GPU acceleration dramatically speeds up inference. LM Studio leverages Metal on macOS.

How to Check Your Mac's Specs

You don't need to be a terminal wizard to find out what kind of Mac you have. Here's a simple way to check your system details:

Click the Apple Menu: In the top-left corner of your screen, click the Apple icon ().
Select "About This Mac": This will open a window with a summary of your Mac's hardware and software.
Check Overview Tab: Look for information on your "Processor" (e.g., Apple M1, Intel Core i7), "Memory" (your RAM), and "Graphics."
Check Storage: Click on the "Storage" tab to see how much free space you have.
For More Detail: Click "System Report..." for a more in-depth look at your hardware.

Info

If your Mac has Apple Silicon (M1, M2, M3 chips), you're in a great position. These chips are highly optimized for AI tasks and will generally provide a much better experience than older Intel Macs with equivalent RAM.

Download and Install LM Studio on Your Mac

Now that you've confirmed your Mac is ready, let's get LM Studio installed. The process is straightforward and designed to be as user-friendly as possible.

Getting the Installer from the Official Source

Always download software from official sources to ensure you're getting a legitimate and malware-free copy.

Tip

Head over to the official LM Studio website: lmstudio.ai. You'll find download buttons prominently displayed. Choose the version appropriate for your Mac (usually an .dmg file).

Running the Installation Wizard

Once you've downloaded the .dmg file, the installation is usually as simple as dragging the application icon to your Applications folder.

Open the .dmg file: Double-click the downloaded file. A Finder window will typically appear.
Drag to Applications: Drag the LM Studio application icon into the "Applications" folder shortcut within that window.
Eject the disk image: After copying, you can eject the LM Studio disk image by dragging its icon from the Finder sidebar to the Trash.
Launch LM Studio: Open your Applications folder and double-click the LM Studio icon. You might see a security warning; if so, click "Open."

Verify Installation and Launch for the First Time

After launching, LM Studio will present its main interface. For the first launch, it might take a moment to load. You'll see a clean dashboard with options to search for models, chat, and view settings. This confirms that the installation was successful and LM Studio is ready to go.

Download Your First AI Model Inside LM Studio

The real magic of LM Studio is its integrated model browser. Instead of hunting for models across the web, you can discover and download them directly within the application.

Understanding Model Sizes and What They Mean

You'll see models listed with numbers like "7B," "13B," or "70B." This refers to the number of parameters the model has, which is a rough indicator of its complexity and capability. Larger models are generally more powerful but require more resources (RAM and processing power).

You'll also encounter terms like "quantization." This is a process that reduces the precision of the model's weights, making it smaller and faster to run, often with a negligible impact on quality. Common quantization formats include GGUF (used by llama.cpp, which LM Studio leverages) with variations like q4_K_M or q5_K_S.

Model Size	Parameters	Resource Needs	Quality	Best For
7B	7 Billion	Low to Moderate	Good	Beginners, basic tasks, systems with 8-16GB RAM.
13B	13 Billion	Moderate to High	Very Good	Systems with 16GB+ RAM, more complex tasks.
70B	70 Billion	Very High	Excellent	High-end systems with 32GB+ RAM, demanding tasks.

For your first model, start small. A 7B or 13B model is usually a safe bet for most modern Macs.

Recommended Starter Models for Mac

Here are a few models that are often well-regarded and perform nicely on Mac hardware:

Mistral 7B Instruct: A very capable 7B model that balances performance and quality.
Llama 3 8B Instruct: Meta's latest offering, known for its strong performance and instruction-following.
OpenHermes 2.5 Mistral 7B: A fine-tuned version of Mistral, often praised for its conversational abilities.

Downloading a Model Step by Step

Let's get your first model downloaded:

Navigate to the Search Tab: In LM Studio, click the magnifying glass icon on the left sidebar to go to the model search.
Search for a Model: Type the name of a model (e.g., "Mistral 7B Instruct") into the search bar.
Select a Specific Version: You'll see a list of available GGUF files. Look for one with a Q in its name (e.g., mistral-7b-instruct-v0.2.Q4_K_M.gguf). The Q4_K_M indicates a good balance of size and quality.
Click Download: Click the download button next to the model file you've chosen. You'll see the download progress in the bottom section of the app.

Info

Model downloads can take a while depending on your internet speed and the model size. Be patient!

Load Your Model and Start Chatting

With a model downloaded, the next step is to load it and start interacting. LM Studio makes this incredibly simple.

Loading the Model into Memory

Once the download is complete, you need to load the model into LM Studio's inference engine.

Go to the Chat Tab: Click the chat bubble icon on the left sidebar.
Select Your Model: At the top of the chat interface, you'll see a dropdown menu labeled "Select a model to load." Click it and choose the model you just downloaded.
Wait for Loading: LM Studio will now load the model into your Mac's RAM. You'll see a progress indicator. This can take anywhere from a few seconds to a couple of minutes, depending on the model size and your system's speed.

Your First Prompt and Response

Once the model is loaded, the chat interface is ready. Simply type your question or prompt into the message box at the bottom and press Enter. The model will then generate a response.

Basic Settings to Tweak (Temperature, Context)

You'll notice a settings panel on the right side of the chat interface. While you can explore these later, two key parameters to be aware of are:

Temperature: Controls the randomness of the output. Lower temperatures (e.g., 0.2) lead to more focused and deterministic responses, while higher temperatures (e.g., 0.8) produce more creative and varied output.
Context Length: This determines how much previous conversation the model remembers. A larger context window allows for longer, more coherent conversations but uses more RAM.

Here are some common settings to experiment with:

Temperature: Start around 0.7 for general chat.
Top-K / Top-P: These are sampling strategies that also influence output creativity. Defaults are often fine to start.
Max new tokens: Limits the length of the model's response.
Context Length: Adjust based on your RAM. For smaller models, you might be able to increase this significantly.

Tip

Don't be afraid to experiment! Changing these settings can dramatically alter the model's behavior.

Troubleshooting Common Installation and Setup Issues

Even with user-friendly tools, you might run into a snag or two. Here are solutions to some common problems.

App Won't Launch or Crashes on Startup

If LM Studio refuses to open or quits unexpectedly right after launching, it's often due to permissions or installation conflicts.

Troubleshooting App Launch Issues

Re-download LM Studio: The installer might have been corrupted during download. Try downloading it again from lmstudio.ai.
Check macOS Version: Ensure your macOS is up-to-date. LM Studio has minimum OS requirements.
Delete and Reinstall: Drag LM Studio from your Applications folder to the Trash, then empty the Trash. Re-download and install it again.
Permissions: While less common for simple drag-and-drop installs, ensure LM Studio has necessary permissions if prompted.

Model Downloads Fail or Run Out of Disk Space

This is usually a straightforward storage issue.

Troubleshooting Download Failures

Check Available Disk Space: Go to "About This Mac" -> "Storage" to see how much free space you have. Models can be several gigabytes.
Pause and Resume: Sometimes, pausing the download and then resuming it can help.
Clear Cache: LM Studio has a cache for downloaded models. You can manage this in the Settings tab to free up space if needed.
Download Smaller Models: If space is tight, opt for smaller models or more heavily quantized versions.

Responses Are Slow or Model Won't Load

Performance issues are typically related to hardware limitations.

Troubleshooting Slow Performance

RAM is Key: If the model won't load or responses are extremely slow, you might not have enough RAM for that specific model.
Close Other Applications: Free up RAM by closing any unnecessary applications running in the background.
Try a Smaller Model: A 7B model will always be faster and easier to load than a 70B model.
GPU Acceleration: Ensure GPU acceleration is enabled in the settings if your Mac supports it (which most modern Macs with Apple Silicon do). LM Studio usually handles this automatically.

Q: Why is my model download so slow?
A: Download speed depends heavily on your internet connection and the server load on the model hosting platform. Larger models naturally take longer.

Q: Can I run multiple models at once?
A: LM Studio is designed to run one model for inference at a time. You can download many models, but only one can be loaded into memory for chatting.

Q: What's the difference between GGUF and other model formats?
A: GGUF is a file format optimized for running LLMs efficiently on consumer hardware, particularly using libraries like llama.cpp, which LM Studio relies on.

What You Can Build and Do Next with LM Studio

You've got LM Studio installed, a model downloaded, and you've had your first chat. What's next? LM Studio isn't just for casual chatting; it's a powerful tool for developers and creators.

Text Generation and Content Creation

Leverage LM Studio for all your writing needs.

Brainstorming: Ask for blog post ideas, marketing slogans, or story concepts.
Drafting: Generate first drafts of articles, emails, or social media posts.
Editing: Get suggestions for improving clarity, tone, or grammar.

Code Completion and Programming Assistance

Developers will find LM Studio invaluable for local coding tasks.

Code Snippets: Ask for boilerplate code or examples for specific functions.
Debugging Help: Paste error messages or code blocks and ask for potential explanations or fixes.
Learning New Languages: Request explanations of syntax or concepts in a programming language you're learning.

Building Chatbots and Conversational Interfaces

LM Studio can act as the backend for your own applications.

Local API: LM Studio can expose a local OpenAI-compatible API. This means you can point your existing AI applications or scripts to LM Studio instead of a cloud service.
Custom Tools: Build specialized chatbots for customer support, internal knowledge bases, or personal assistants.

Experimenting with Prompt Engineering

The quality of AI output is heavily influenced by how you prompt it.

Iterate: Try different phrasings, add context, or specify the desired output format.
Few-Shot Learning: Provide examples within your prompt to guide the model's response style.
Role-Playing: Instruct the model to act as a specific persona for tailored responses.

Success

By running these models locally, you're not just experimenting with AI; you're building a foundation for powerful, privacy-preserving applications.

Ready to Go Deeper with LM Studio

You've successfully set up LM Studio and run your first AI model. This is just the beginning of your journey into local AI.

Explore More AI Possibilities

Ready to dive deeper? Explore LM Studio's documentation to learn about advanced settings, custom model configurations, and integrating with other tools.

Discover Advanced Features

DEV Community: Shubham Sharma

Install Docker on macOS, Windows (WSL2), and Linux: One Guide, Three Paths

Prerequisites

macOS: Docker Desktop

Windows: Docker Desktop with the WSL2 backend

Linux: Docker Engine (the native path)

Run Docker without sudo (Linux post-install)

Optional: rootless Docker (Linux)

What a working install looks like

Common gotchas, by OS

macOS: "Cannot connect to the Docker daemon"

Windows: containers will not start

Windows: docker not found in PowerShell

Linux: "permission denied while trying to connect to the Docker daemon socket"

Linux: apt cannot find docker-ce

Where to go next

Run Your First Containers: docker run, ps, logs, exec, stop, rm

Prerequisites

Images versus containers, in one minute

Start a container

See it running

Talk to it

Look inside

Stop, start, and see stopped containers

Clean up

The lifecycle at a glance

Common gotchas

"port is already allocated"

docker exec says the container is not running

The name is already in use

Changes inside a container disappear

Where to go next

Operating Containers: Healthchecks, Resource Limits, Restart Policies, and Env Config

Prerequisites

Healthchecks: does the container actually work?

Health-gated startup in Compose

Resource limits: stay in budget

Memory

CPU

Limits in Compose

Restart policies: self-healing

Env config without secrets in the image

The whole thing in one Compose file

Common gotchas

Container exits with code 137

Healthcheck passes but the app is broken

depends_on: condition: service_healthy does nothing

The container keeps restarting forever

My .env changes are ignored

Where to go next

Where Your Data Lives: Docker Volumes, Bind Mounts, and Networks

Prerequisites

Named volumes: data that survives

Bind mounts: live files from the host

Back up and restore a volume

Networks: containers that find each other by name

Doing it in Compose

Common gotchas

My data still disappeared

docker compose down -v wiped my database

Bind mount shows an empty directory

Permission denied inside the container

Containers cannot reach each other

Where to go next

Lean Docker Images: Multi-Stage Builds and Layer Caching

Prerequisites

Attempt 1: the naive Dockerfile

Attempt 2: the optimized multi-stage Dockerfile

1. A smaller base image

2. Multi-stage: build in one stage, ship another

3. Production dependencies only

Prove the cache works

Look at the layers

Common gotchas

npm ci fails with "no package-lock.json found"

Alpine build fails on a native module

The image is still huge

Reordering did not help

Where to go next

Docker Compose: Run a Multi-Service Stack (Web + Postgres + Redis)

Windows: `docker` not found in PowerShell

Linux: apt cannot find `docker-ce`

`docker exec` says the container is not running

`depends_on: condition: service_healthy` does nothing

My `.env` changes are ignored

`docker compose down -v` wiped my database

`npm ci` fails with "no package-lock.json found"

`version` warning on `up`

The app breaks under `read_only: true`

The app breaks under `cap_drop: ALL`