Docker Networking Incident: Microservices That Cannot Talk to Each Other

The Symptom

A new auth-service is deployed alongside the existing api and postgres services. The auth-service logs show:

Error: getaddrinfo ENOTFOUND postgres

The api service works fine and connects to postgres without issue. Same image base, similar config.

---

Step 1: Check What Networks Exist

docker network ls

NETWORK ID     NAME              DRIVER
abc123         bridge            bridge
def456         app_app_net       bridge
ghi789         auth_default      bridge

Two custom networks: app_app_net (created by the main docker-compose.yml) and auth_default (created by the auth service's own Compose file). The auth service is on a completely different network — it cannot reach postgres by name because they are not on the same network.

---

Step 2: Confirm Which Network Each Container Is On

docker inspect postgres | grep -A5 Networks
docker inspect auth-service | grep -A5 Networks

postgres: {"app_app_net": {...}}
auth-service: {"auth_default": {...}}

Confirmed: different networks, no shared DNS namespace.

---

Step 3: Immediate Fix — Connect auth-service to app_app_net

docker network connect app_app_net auth-service

Test from inside auth-service:

docker exec auth-service nslookup postgres
docker exec auth-service curl -sf http://postgres:5432

DNS now resolves. Connection works. The incident is resolved.

---

Step 4: Permanent Fix — Use an External Network

The real fix is architectural: both Compose files should connect to the same named external network.

# Main docker-compose.yml
networks:
  app_net:
    name: shared_app_net   # named explicitly so other files can reference it

# auth/docker-compose.yml
services:
  auth-service:
    networks:
      - shared_app_net

networks:
  shared_app_net:
    external: true   # already created by main compose

---

Step 5: The Port Binding Issue (Second Problem)

After fixing networking, a second error appears:

Error: connect ECONNREFUSED 127.0.0.1:6379

The auth-service is trying to reach Redis at 127.0.0.1:6379 — a localhost address. Redis runs in another container, not on localhost of auth-service.

docker exec auth-service env | grep REDIS

REDIS_URL=redis://127.0.0.1:6379

The env var was copied from a local dev config where Redis ran locally. Fix: change to the service name.

REDIS_URL=redis://redis:6379

---

What This Incident Reveals

Network isolation between Compose files is intentional — but it means services in different files cannot reach each other by default. The solutions:

External named networks (preferred for production)
Single Compose file for tightly coupled services
docker network connect for one-off fixes

The 127.0.0.1 mistake in environment variables is one of the most common Docker migration errors — any service reference that was localhost in development must become a container name in Docker.

Practice in the ShellGenius Docker Labs — the network-microservices and port-conflict challenges cover these exact scenarios.