3.2 Docker Networking
Service names, Compose, and why the browser cannot use them.
Once you have more than one container, they need to talk to each other. Docker gives containers on the same network a DNS entry under their service name.
Diagram source
flowchart LR
A[Frontend Container]
B[Backend Container]
C[Postgres Container]
A -->|http://backend:4000| B
B -->|postgres:5432| CNo IP addresses, no port publishing between them. backend resolves to
whichever container currently holds that role, which means containers can be
restarted and replaced without anything being reconfigured.
Compose
Docker Compose declares the whole local stack in one file and puts every service on a shared network automatically:
services:
frontend:
build: ./frontend
ports:
- "3000:3000"
environment:
API_URL: http://backend:4000
depends_on:
- backend
backend:
build: ./backend
environment:
DATABASE_URL: postgres://postgres:postgres@postgres:5432/app
depends_on:
- postgres
postgres:
image: postgres:18
environment:
POSTGRES_PASSWORD: postgres
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:Points worth noticing:
Only frontend publishes a port. The others are reachable within the network
but not from your machine — which is what you want, and also why you cannot
connect a database GUI to postgres until you publish 5432 yourself.
The pgdata volume is what stops your data disappearing on
docker compose down. Containers are ephemeral; volumes are not.
depends_on controls start order, not readiness. Postgres accepting
connections takes a few seconds after the container starts, so the backend still
needs to retry — this is the cause of the classic crash-on-first-boot that
resolves itself after a restart.
Server-side vs browser URLs
The most common Docker confusion in frontend work, and worth being very precise about.
http://backend:4000 works inside the Docker network. Your browser is not
inside the Docker network. It has no idea what backend means, and will fail to
resolve it.
Server-side fetch (SSR, route handler) → http://backend:4000
Browser fetch (client component) → http://localhost:4000
or /api via a proxyA Next.js app hits this directly: the same fetch in a server component and a
client component needs different hostnames. Hence the common pattern of two
variables:
environment:
API_URL: http://backend:4000 # server-side only
NEXT_PUBLIC_API_URL: http://localhost:4000 # sent to the browserThe cleaner fix is to avoid the split entirely by putting a
reverse proxy in front of both, so
the browser only ever calls /api on the same origin — no second hostname, and
no CORS.
Useful commands
docker compose up --build # rebuild and start
docker compose logs -f backend # follow one service's logs
docker compose exec backend sh # shell inside a running container
docker compose down -v # stop and delete volumesexec ... sh is the debugging tool that matters. When a container behaves
unexpectedly, get a shell inside it and check what it actually sees:
env | grep API # is the variable set?
wget -qO- backend:4000/health # can it reach the other service?Nearly every "it works locally but not in Docker" problem answers to one of those two questions.
docker compose down -v deletes your volumes, and therefore your local database
contents. Use plain down for stopping work; keep -v for when you actually
want a clean slate.