You’ve meticulously crafted your docker-compose.yml file, your services build correctly, and the startup process finishes without a single error. Yet, when your application tries to connect to its database, you get a “Connection refused” or “Host not found” error. This is a classic and frustrating scenario in Docker Compose networking. Your containers are running, but they’re isolated in their own digital worlds, unable to communicate.
These issues almost always boil down to two core mysteries: service discovery failed events, where containers can’t find each other, and docker compose port conflict problems, where port mappings are misunderstood or misconfigured. To build reliable containerized applications, you must look beyond the docker-compose.yml file and understand the virtual network that Docker creates. This guide will demystify that network, providing you with the tools and techniques to troubleshoot and resolve these common connectivity challenges.
How Compose Magically Builds Your Private Network
When you run docker compose up, Docker doesn’t just start containers; it creates a dedicated, private network for your application. This is a crucial concept. By default, this is a docker bridge network, which acts as a virtual switch that all your services plug into.
Here’s how it works with a simple docker-compose.yml file:
- If your project lives in a directory named myapp, Compose creates a network called myapp_default.
- Every service defined in your file (e.g., web, api, db) is automatically attached to this myapp_default network.
- Each container gets its own IP address on this private network.
The most powerful feature of this setup is the built-in Docker internal DNS. Each service is discoverable by any other service on the same network using its service name. If your web application needs to connect to its PostgreSQL database defined with the service name db, the connection string should simply use the service name and its internal port, like db:5432. You don’t need to know the container’s internal IP address; Docker handles the service names resolution for you. This is the foundation of inter-container communication.
Mystery #1: Service Discovery Failed
The most common networking problem is when one service cannot resolve the hostname of another. Your app container tries to connect to db and fails. This is a DNS issue inside Docker’s virtual network.
Diagnosing Service Discovery Failures
When a container cannot connect to another, your first instinct should be to play network detective. Here are the steps to diagnose the problem.
Step 1: Verify Network Membership
Are your containers actually on the same network? The docker network inspect command is your best friend here. First, find the name of your project’s network by running docker network ls. Then, you can inspect it by name.
This command will return detailed information about the network, including a section listing all the running containers attached to it. This list should contain all the running services from your Compose file.
If a container is missing from this list, it’s not on the network, which is the root of your problem. This often happens when you use custom networks and forget to attach a service to the correct one. Services can only communicate if they share at least one network in common.
Step 2: Test DNS from Inside the Container
If both containers are on the network, the next step is to check docker DNS resolution from the perspective of the failing container. You can use the docker exec command to open a shell inside your application container.
Once inside, use standard networking tools to test connectivity. A simple ping to the service name is the easiest way to check. A successful ping will show that the service name is correctly resolved to an IP address. If it fails with “bad address” or “name not resolved,” you have a DNS problem.
Step 3: Check for Custom or External Network Issues
If you’ve defined custom networks in your docker-compose.yml file, you must explicitly assign each service to the networks it needs to access. A common mistake is isolating a service by attaching it to the wrong network.
Another potential issue arises when using a compose external network. If you specify a network as external, Compose will not create it. It expects that network to already exist. If you mistype the name, Compose won’t warn you; your containers will simply fail to attach to anything, leaving them unable to communicate.
Mystery #2: The Dreaded Port Conflict
The second great mystery of docker container networking revolves around port mappings. A docker compose port conflict can prevent your services from starting or make them inaccessible from your host machine.
The ports section in docker-compose.yml uses the format “HOST_PORT:CONTAINER_PORT”.
- CONTAINER_PORT: The port the application is listening on inside the container.
- HOST_PORT: The port that is exposed on your host machine (your laptop, a server, etc.).
For example, a port mapping of “8000:80” maps port 80 inside the container to port 8000 on your host.
Unraveling Port Binding Issues
Here are the most common port-related problems and how to solve them.
“Port is already allocated” Error
This error is straightforward: the host port you’re trying to use is already in use by another application on your host machine. You can either stop the other application or choose a different host port for your service.
The localhost Confusion
A frequent mistake is trying to connect services to each other using localhost and the exposed host port. For example, from the web container, you might try to connect to localhost:5432 to reach the database. This will not work.
Each container has its own localhost. When your web container connects to localhost, it’s trying to connect to itself, not the db container. Inter-container communication must use the service name and the container’s internal port. The host port is only for accessing the service from outside the Docker network, such as from your browser or a database client on your host machine.
Using an Override File for Flexibility
You can avoid editing your main docker-compose.yml file for different environments by using an override file. Create a file named docker-compose.override.yml in the same directory. Compose automatically merges this file with the original. This is perfect for managing container port mapping in development without affecting the production configuration.
For example, your base configuration might not expose any ports for the database, but your override file can add a port mapping for local debugging. This keeps your base configuration clean and secure while providing flexibility for development.
From Reactive Debugging to Proactive Monitoring
Using CLI tools for debugging is essential for acute networking problems. However, this is a reactive approach. In a production environment, you need to spot networking issues, high latency, and connection errors as they happen.
Netdata provides real-time, high-granularity monitoring for your entire Docker environment. It automatically discovers your containers and the applications running inside them, giving you immediate visibility into:
- Network Traffic: See the bandwidth used by each container and service in real-time.
- Container Health: Monitor CPU, memory, and disk I/O for every container to spot resource-constrained services that might be dropping connections.
- Application Metrics: Netdata goes beyond container metrics to monitor the applications themselves, showing you database query times, API error rates, and more.
By correlating these metrics on a single dashboard, you can instantly see the impact of a networking issue on your application’s performance. Instead of guessing why a service is slow, you can see if it’s due to high network latency, DNS resolution delays, or resource saturation on another container.
To take your compose network troubleshooting from a reactive task to a proactive discipline, sign up for a free Netdata account and gain a complete, real-time picture of your containerized services.