Skip to content
Hands-on IT IT Drills

Day 2: Networks

Goal: Understand how services find each other via DNS, and split the stack into a public frontend and an internal backend network. · Duration: approx. 60 min · Prerequisite: Day 1

Briefing

  • If you specify nothing, Compose attaches all services to one network <project>_default. A built-in DNS server (127.0.0.11) resolves every service name there.
  • ports: publishes a port on the Mac. Containers in the same network don’t need that; they reach every port directly.
  • Multiple networks separate responsibilities: whoever doesn’t share a network with a service can neither resolve nor reach it.
  • internal: true cuts a network off from the outside: no internet, no published ports.
              Mac 127.0.0.1:3000          127.0.0.1:8080
                     │                          │
 notes_frontend ─────┼──────────────────────────┼───────────── (with internet)
                ┌────▼─────┐               ┌────▼─────┐
                │   web    │──── api ─────►│   api    │
                └──────────┘               └────▲─────┘
 notes_backend ─────────────────────────────────┼──────────── internal: true
                                           ┌────┴─────┐
                                           │  worker  │
                                           └──────────┘

Drill 1: The default network

Start of the day: take over the state from Day 1 and start it.

source ~/compose-lab/setup/env.sh
docker compose -p notes down
mkdir -p ~/compose-lab/tag02 && cd ~/compose-lab/tag02
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag01/notes/." .
docker compose up -d
docker network inspect notes_default --format \
  '{{.Name}} {{.Driver}} {{range .IPAM.Config}}{{.Subnet}} {{.Gateway}}{{end}}'
docker network inspect notes_default --format \
  '{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'

Expected (shortened, addresses differ on your machine):

 Container notes-web-1 Started
 Container notes-worker-1 Started
notes_default bridge 172.20.0.0/16 172.20.0.1
notes-worker-1 172.20.0.4/16
notes-web-1 172.20.0.3/16
notes-api-1 172.20.0.2/16

A bridge network with its own subnet, all three containers in it. Docker assigns the IP addresses anew on every start – that’s why the services address each other only by name.

Save your progress? Sign up for free

Drill 2: Service discovery via DNS

web ships BusyBox with nslookup:

docker compose exec web nslookup api
docker compose exec web nslookup notes-api-1
docker compose exec web nslookup notes-api

Expected (shortened):

Server:     127.0.0.11
Address:    127.0.0.11:53
Non-authoritative answer:
Name:   api
Address: 172.20.0.2
…
Name:   notes-api-1
Address: 172.20.0.2
…
** server can't find notes-api: NXDOMAIN

The service name api and the container name notes-api-1 resolve. notes-api – the default in the code of worker and web – does not exist; that’s why the compose.yaml sets NOTES_API_URL: http://api:8080. For containers without tools (like notes-api in scratch), you look with a helper container in the same network:

docker run --rm --label lab=compose-lab --network notes_default alpine:3.24 \
  sh -c 'getent hosts api; wget -qO- http://api:8080/healthz; echo; \
         grep -v "^#" /etc/resolv.conf'

Expected (shortened):

172.20.0.2        api  api
ok
nameserver 127.0.0.11
options ndots:0

127.0.0.11 is Docker’s DNS server in every user-defined network. It knows the names in its own network and forwards everything else to the host’s DNS.

Save your progress? Sign up for free

Drill 3: ports and expose

docker compose port api 8080
docker compose port web 3000
docker compose port worker 8080; echo "Exit: $?"
docker compose ps --format '{{.Service}}: {{.Ports}}'

Expected:

127.0.0.1:8080
127.0.0.1:3000
no port 8080/tcp for container notes-worker-1:
Exit: 1
api: 127.0.0.1:8080->8080/tcp
web: 127.0.0.1:3000->3000/tcp
worker:
  • Only those who access a service from the Mac need ports:. worker has no published port and still reaches api.
  • Within the network, the container port always applies: web calls api:8080, even if you set API_PORT=8081.
  • expose: publishes nothing. According to the reference, it only describes ports for other services; whatever the Dockerfile declares via EXPOSE is visible anyway. Containers in the same network reach every port on which a process listens.

Save your progress? Sign up for free

Drill 4: Two networks

Now each service gets only the networks it needs:

cat > compose.yaml <<'EOF'
# compose.yaml – state at the end of Day 2
name: notes

services:
  api:
    build: notes-api
    environment:
      NOTES_API_KEY: ${NOTES_API_KEY}
    ports:
      - "127.0.0.1:${API_PORT:-8080}:8080"
    networks: [frontend, backend]

  worker:
    build: notes-worker
    environment:
      NOTES_API_URL: http://api:8080
      NOTES_API_KEY: ${NOTES_API_KEY}
    depends_on:
      - api
    networks: [backend]

  web:
    build: notes-web
    environment:
      NOTES_API_URL: http://api:8080
      NOTES_API_KEY: ${NOTES_API_KEY}
    ports:
      - "127.0.0.1:${WEB_PORT:-3000}:3000"
    depends_on:
      - api
    networks: [frontend]

networks:
  frontend: {}
  backend:
    internal: true
EOF
docker compose up -d
docker network ls --filter label=com.docker.compose.project=notes \
  --format '{{.Name}} internal={{.Internal}}'

Expected (shortened):

 Network notes_backend Created
 Network notes_frontend Created
 Container notes-api-1 Recreated
 Container notes-web-1 Recreated
 Container notes-worker-1 Recreated
 Container notes-api-1 Started
 Container notes-worker-1 Started
 Container notes-web-1 Started
notes_backend internal=true
notes_default internal=false
notes_frontend internal=false

Wait – notes_default is still there. No service uses it, but Compose only removes a network if it is in the file. down leaves it behind, too. Get rid of it:

docker network inspect notes_default --format '{{len .Containers}} Container'
docker network rm notes_default

Expected:

0 Container
notes_default

Tip: docker network ls --filter label=com.docker.compose.project=notes finds such leftovers as well.

Save your progress? Sign up for free

Drill 5: Who sees whom?

docker compose exec web wget -qO- -T 2 http://api:8080/healthz; echo
docker compose exec web nslookup worker | tail -1
docker compose logs worker --tail 2
docker network inspect notes_frontend --format \
  '{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'
docker network inspect notes_backend --format \
  '{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'

Expected (shortened, addresses differ):

ok
** server can't find worker: NXDOMAIN
worker-1  | worker started, api=http://api:8080, interval=10s
worker-1  | summary: 0 notes, 0 words
notes-api-1 172.22.0.2/16
notes-web-1 172.22.0.3/16

notes-api-1 172.21.0.2/16
notes-worker-1 172.21.0.3/16
from  to api web worker
web (frontend) ✔ – ✘ (cannot be resolved)
worker (backend) ✔ ✘ –
Mac ✔ 8080 ✔ 3000 ✘

api is attached to both networks and has its own address in each. web and worker share no network and know nothing about each other.

Save your progress? Sign up for free

Drill 6: internal – no way out

A helper container in each network, once to the internet, once to api:

for n in notes_frontend notes_backend; do
  echo "== $n"
  docker run --rm --label lab=compose-lab --network "$n" alpine:3.24 sh -c \
    'wget -q -T 3 -O /dev/null https://example.com && echo "Internet: ja" \
       || echo "Internet: nein"; wget -qO- -T 2 http://api:8080/healthz; echo'
done

Expected:

== notes_frontend
Internet: ja
ok
== notes_backend
wget: bad address 'example.com'
Internet: nein
ok

In the internal network, Docker only resolves the names of the neighbors, not external names. The worker itself notices this the same way:

docker compose exec worker python -c \
  "import httpx; print(httpx.get('https://example.com', timeout=3).status_code)" \
  2>&1 | tail -1

Expected:

httpx.ConnectError: [Errno -3] Temporary failure in name resolution

Second consequence of internal: a container only in this network cannot publish ports. Test it with a single notes-api container:

docker run -d --name notes-probe --label lab=compose-lab --network notes_backend \
  -p 127.0.0.1:8088:8080 -e NOTES_API_KEY=lab-api-key-123 notes-api >/dev/null
sleep 2
docker ps --filter name=notes-probe --format '{{.Names}} {{.Status}} [{{.Ports}}]'
curl -s -m 3 localhost:8088/healthz; echo "curl Exit: $?"
docker rm -f notes-probe

Expected (shortened):

notes-probe Up 2 seconds (healthy) [8080/tcp]
curl Exit: 7
notes-probe

No error at startup, but no forwarding either: -p is silently ignored. That’s why every service with ports: is also attached to frontend.

Save your progress? Sign up for free

Drill 7: Network names and external

Compose puts the project name in front of every network. With name: you set the real name yourself; with external: true, Compose uses an existing network instead of creating one. Test it with --dry-run and a copy of the file:

sed 's|^  frontend: {}|  frontend:\n    name: notes-shared|' compose.yaml > netz.yaml
docker compose -f netz.yaml --dry-run up -d 2>&1 | grep -m1 Network
sed 's|^  frontend: {}|  frontend:\n    name: notes-shared\n    external: true|' \
  compose.yaml > netz.yaml
docker compose -f netz.yaml up -d

Expected:

 Network notes-shared Creating
network notes-shared declared as external, but could not be found

An external network must exist beforehand; Compose never creates it and never deletes it. Typical for networks shared by several projects, for example a common reverse proxy:

docker network create --label lab=compose-lab notes-shared
docker compose -f netz.yaml --dry-run up -d 2>&1 | grep -E 'Container' | head -3
docker network rm notes-shared
rm netz.yaml

Expected (shortened):

9cd5b9051dac…
 Container notes-worker-1 Running
 Container notes-api-1 Recreate
 Container notes-api-1 Recreated
notes-shared

api and web would be recreated (different network), worker would stay. In this book we stick with the two project-owned networks; external only shows up again in the Enterprise Note.

Warning: Without grep you additionally see a warning: the previous network notes_frontend no longer matches the file and is left untouched. As in Drill 4, Compose does not clean up networks that are no longer part of the file by itself.

Save your progress? Sign up for free

Checkpoint

The stack with the compose.yaml from Drill 4 is running. The networks:

cd ~/compose-lab/tag02
docker network ls --filter name=notes_ --format '{{.Name}} internal={{.Internal}}'

Expected: backend internal, frontend normal, no notes_default anymore.

notes_backend internal=true
notes_frontend internal=false

web reaches api:

docker compose exec web wget -qO- -T 2 http://api:8080/healthz; echo

Expected:

ok

web does not see worker:

docker compose exec web nslookup worker

Expected (shortened):

Server:     127.0.0.11
Address:    127.0.0.11:53

** server can't find worker…: NXDOMAIN

worker reaches api, but not the internet:

docker compose exec worker python -c \
  "import httpx; print(httpx.get('http://api:8080/healthz').text)"
docker compose exec worker python -c \
  "import httpx; httpx.get('https://example.com', timeout=3)" 2>&1 | tail -1

Expected (shortened):

ok
httpx.ConnectError: [Errno -3] Temporary failure in name resolution

api is published, a POST via web works:

curl -s localhost:8080/healthz; echo
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"Kontrollpunkt Tag 2"}'; echo

Expected (shortened, ID differs):

ok
{"id":"30480990-…","text":"Kontrollpunkt Tag 2"}

The complete file is in code/tag02/notes/compose.yaml.

Challenge

The worker should get by without NOTES_API_URL and use the code default http://notes-api:8080. Don’t change anything in the code for this, only the network configuration of api – in such a way that the name notes-api applies only in backend, so web cannot resolve it. Work in a copy compose.alias.yaml.

Hint: The long form of networks: on a service supports aliases: per network.

Solution

cp compose.yaml compose.alias.yaml

In compose.alias.yaml, write the networks of api in the long form and delete the line NOTES_API_URL from worker:

  api:
    # … as before
    networks:
      frontend: {}
      backend:
        aliases: [notes-api]

  worker:
    build: notes-worker
    environment:
      NOTES_API_KEY: ${NOTES_API_KEY}
    depends_on:
      - api
    networks: [backend]
docker compose -f compose.alias.yaml up -d
sleep 12
docker compose -f compose.alias.yaml logs worker | head -1
docker compose -f compose.alias.yaml logs worker --tail 1
docker compose -f compose.alias.yaml exec worker getent hosts notes-api
docker compose -f compose.alias.yaml exec web nslookup notes-api | tail -1

Expected (shortened, addresses differ):

 Container notes-web-1 Running
 Container notes-api-1 Recreated
 Container notes-worker-1 Recreated
worker-1  | worker started, api=http://notes-api:8080, interval=10s
worker-1  | summary: 0 notes, 0 words
172.20.0.2      notes-api
** server can't find notes-api: NXDOMAIN

Aliases apply per network: in backend, api is additionally called notes-api, in frontend it is not. web stays unchanged and keeps running. The whole file: code/tag02/challenge/compose.alias.yaml. Back to the state of the day:

docker compose up -d
rm compose.alias.yaml
docker compose down

Save your progress? Sign up for free

Enterprise Note

  • Networks are the simplest segmentation on a Docker host: databases and workers belong in an internal network, only the proxy and API in a network with ports.
  • internal also blocks updates, telemetry and license checks. Whoever needs egress gets it in a controlled way through an egress proxy, not through an open network.
  • Shared networks between projects (external: true) are a contract: name, subnet and owner must be documented, otherwise one team’s docker network rm breaks another team’s services.
  • Use fixed subnets (ipam.config.subnet) only when they collide with the corporate VPN or Docker hosts in the same network; the default ranges 172.16.0.0/12 frequently overlap with corporate networks.
  • In Kubernetes, service names correspond to Services and internal roughly to a NetworkPolicy without egress – the mental model carries over.