As your microservices architecture grows, you might split it into multiple independent Docker Compose projects—each responsible for a different part of the application. But what happens when services from Project A need to talk to services in Project B?
In this blog post, you’ll learn:
- How Docker Compose handles networking
- Ways to enable communication between separate Compose projects
- Best practices for cross-project service interaction
🧠 Understanding Docker Compose Networks
Each docker-compose
project creates its own default bridge network. For example, starting a docker-compose
project in directory app1/
might create a network like:
app1_default
Services within the same network can resolve each other by container name. But services from different projects cannot communicate by default unless explicitly configured to share a network.
✅ Option 1: Use a Shared External Network
The cleanest way to connect multiple projects is by defining a common external Docker network that all projects attach to.
🔧 Step-by-Step
- Create a shared network manually:
docker network create shared-network
- In each
docker-compose.yml
, declare the external network:
networks:
shared:
external: true
name: shared-network
- Attach services to that network:
services:
service-a:
image: my-image
networks:
- shared
networks:
shared:
external: true
name: shared-network
Now, any container on shared-network
can communicate using service names.
✅ Option 2: Manually Connect Containers to Another Project’s Network
If both projects are already running, you can attach containers to another network using the docker network connect
command:
docker network connect app2_default container_name
This is useful for ad-hoc connections but not ideal for permanent setups.
🧪 Example: Service A from Project 1 Communicates with Service B in Project 2
Suppose:
- Project 1 has a service
frontend
- Project 2 has a service
api
Both are connected to the external shared-network
. From frontend
, you can now do:
curl http://api:5000/endpoint
Assuming api
is listening on port 5000
, this request will work!
⚠️ Common Pitfalls
Problem | Cause | Solution |
---|---|---|
Service not reachable by name | Different networks | Use shared external network |
Connection refused error | Wrong port or host binding | Check exposed/internal port and hostname |
No route to host | Host network issues or firewall | Ensure both containers are on same network |
💡 Best Practices
- Use meaningful network names when defining shared networks.
- Avoid relying on
localhost
inside containers—use container names. - Keep networks loosely coupled to preserve project independence.
- Define networks outside of compose files to manage lifecycle clearly.
📝 Conclusion
Connecting multiple Docker Compose projects is easy once you understand how Docker networks work. By using shared external networks, you can build modular, scalable, and independently managed microservices that talk to each other securely.
🔑 Recap
Goal | Method |
---|---|
Cross-project communication | Use shared external Docker network |
Temporary container linking | docker network connect |
Container-to-container access | Use service names, not localhost |