Docker Networking Fail: My First `docker-compose` Blunder

Okay, so picture this: I was super excited. My first real project using docker-compose. I’d spent hours crafting this docker-compose.yml file, linking up a web app, a database, and maybe a caching service. It felt like I was building a mini-city of containers, all humming along perfectly in my mind. I hit docker-compose up -d, feeling like a tech wizard, ready to conquer the world. And then… crickets. Or worse, error messages. Lots and lots of error messages.

The "Why Can't My Container See the Database?" Saga

TL;DR: My docker-compose deployment bombed because I assumed containers on the same network could just talk to each other by default using their service names. Turns out, I was missing a crucial piece of the networking puzzle, and my app couldn't reach the database. Classic "Oops IT" moment, right?

I was building a simple blog application. The stack involved:

Frontend: A basic Node.js/Express app serving HTML.

Backend/API: Another Node.js/Express app that handled requests and talked to the database.

Database: PostgreSQL, because who doesn't love a reliable relational database?

Caching: Redis, to speed things up.

My docker-compose.yml looked something like this (don't laugh, it was my first rodeo!):

version: '3.8'
services:
  frontend:
    build: ./frontend
    ports:
      - "8080:80"
    depends_on:
      - backend
    environment:
      - BACKEND_URL=http://backend:3000 # This is where the trouble started
  backend:
    build: ./backend
    ports:
      - "3000:3000"
    depends_on:
      - db
      - redis
    environment:
      - DATABASE_URL=postgresql://user:password@db:5432/mydb
      - REDIS_HOST=redis
  db:
    image: postgres:13
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    volumes:
      - db_data:/var/lib/postgresql/data
  redis:
    image: redis:alpine
volumes:
  db_data:

I’d confidently set BACKEND_URL=http://backend:3000 in my frontend service and DATABASE_URL=postgresql://user:password@db:5432/mydb in my backend service. The idea was that docker-compose would magically make backend resolvable from frontend, and db resolvable from backend.

When I ran docker-compose up -d, I started tailing the logs for the frontend service:

docker-compose logs -f frontend

And what did I see? A cascade of connection errors.

Error: connect ECONNREFUSED 127.0.0.1:3000
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1198:16)
    at Object.callbackWrapper [as afterConnect] (net.js:1156:12)
    at listOne (internal/stream_base_object.js:161:17)
    at handleStream (internal/stream_base_object.js:181:17)
    at processTicksAndRejections (internal/process/task_queues.js:82:21)
Error: Failed to connect to the backend API. Please ensure the backend is running and accessible at http://backend:3000

"What the heck?" I thought. The backend service is running! docker-compose ps showed all services as Up. And the db service? More psql connection errors from the backend logs.

Delving into the Docker Network Abyss

This is where I realized my assumption was flawed. I assumed that just because containers were started with docker-compose, they were automatically on a network where service names would resolve. This is partially true, but not always in the way you expect, especially if you're doing something a bit unconventional or if your docker-compose.yml is missing some explicit configurations.

The crucial detail is that docker-compose does create a default network for your services. However, if you don't explicitly define networks, or if your services are configured in a way that bypasses this default behavior (which wasn't the case here, but it's good to be aware of), name resolution can fail.

The real culprit for me was a subtle misunderstanding of how depends_on works. depends_on ensures that containers start in the correct order, but it doesn't guarantee that the dependent service is ready to accept connections. My frontend was trying to hit the backend immediately after the backend container started, but before the backend application itself had fully initialized and started listening on its port. The same applied to the backend trying to connect to the database.

Furthermore, I was assuming that backend would resolve to the container's IP address. While docker-compose does provide DNS resolution within its default network, the ECONNREFUSED error pointed to something more fundamental: the port wasn't accessible or the service wasn't listening yet.

I started poking around. I tried docker exec -it <frontend_container_id> sh and then tried to ping backend. Sometimes it worked, sometimes it didn't, which was confusing. But the curl http://backend:3000 command from inside the frontend container would consistently fail.

Then I checked the backend logs again. I saw messages like:

Database connection established.
Redis connected.
Server listening on port 3000

This confirmed the application was eventually starting up, but the frontend was too impatient.

The networks Section and depends_on Refinements

The primary fix involved ensuring proper network configuration and handling the readiness of services.

First, let's explicitly define a network. While docker-compose creates a default one, being explicit is good practice and makes troubleshooting easier.

```yaml version: '3.8'

services: frontend: build: ./frontend ports: - "8080:80" environment: - BACKEND_URL=http://backend:3000 networks: - app-network