Docker DNS and Service Networking

Goal

Explain how containers find each other, why localhost inside a container means "this container", and how an internal network removes internet access from the services that handle your data.

What you'll learn

• Docker's embedded DNS server resolves Compose service names
• localhost is per container
• Two networks: edge (published) and private (internal: true)
• How to check what a container can and cannot reach

Architecture

            edge network (bridge)                 private network (bridge, internal: true)
host:3000 ──► web ─────────────────────────────────► web
                                                     backend ──► postgres
                                                             └─► ollama
                                                     no gateway: nothing here reaches the internet

web is attached to both networks, so it can receive your request on edge and forward it to backend on private.

Prerequisites

Module 04, stack running.

Steps

1. Service names are DNS names

docker compose exec backend getent hosts postgres ollama web

172.26.0.3      postgres
172.26.0.2      ollama
172.26.0.5      web

Addresses change when containers are recreated. Names do not. That is why compose.yaml says OLLAMA_URL: http://ollama:11434, and nginx resolves backend at request time.

2. localhost is the container itself

docker compose exec backend python -c "import urllib.request as u; print(u.urlopen('http://localhost:11434/api/version', timeout=3).read())"
docker compose exec backend python -c "import urllib.request as u; print(u.urlopen('http://ollama:11434/api/version', timeout=3).read())"

3. The internal network

docker network inspect local-ai-demo_private --format '{{.Internal}}'

4. Prove it from inside

docker compose exec backend python -c "
import socket
for target in ['registry.ollama.ai', 'pypi.org']:
    try: socket.getaddrinfo(target, 443); print(target, 'resolves')
    except OSError as e: print(target, 'does not resolve:', e)
try: socket.create_connection(('1.1.1.1', 443), timeout=4); print('1.1.1.1:443 reachable')
except OSError as e: print('1.1.1.1:443 unreachable:', e)
"

registry.ollama.ai does not resolve: [Errno -3] Temporary failure in name resolution
pypi.org does not resolve: [Errno -3] Temporary failure in name resolution
1.1.1.1:443 unreachable: [Errno 101] Network is unreachable

The same is true for ollama: docker compose exec ollama ollama pull qwen3:0.6b fails. That is why ./scripts/pull-model.sh uses a separate, temporary container on Docker's default network.

5. What is published

docker compose port web 8080
docker compose port backend 8000 || echo "backend: not published"

Verification

• Service names resolve inside containers, and localhost does not reach another container
• local-ai-demo_private is internal
• Public DNS and TCP fail from inside backend

Exercises

1. Run docker compose exec web wget -qO- http://backend:8000/api/health. Why does this work from web when the backend has no published port?
2. Could web reach the internet? Check which networks it is on with docker inspect local-ai-demo-web-1 --format '{{json .NetworkSettings.Networks}}'. What would you change if you wanted it isolated too, and what would stop working?
3. Change OLLAMA_URL to http://localhost:11434 in compose.yaml, run docker compose up -d --wait, and open /api/ready. Change it back.

Troubleshooting