Docker Compose — Cross-Compose Networking

1 minute read

Sometimes services in different Compose projects need to talk to each other. You can achieve this using external networks.

The Pattern

┌── Project A ──────────┐     ┌── Project B ──────────┐
│  services:             │     │  services:             │
│    api: ...            │     │    dashboard: ...       │
│    db: ...             │     │                         │
│  networks:             │     │  networks:              │
│    shared:             │     │    shared:               │
│      name: shared-net  │     │      external: true      │
│                        │     │      name: shared-net    │
└────────────────────────┘     └─────────────────────────┘
         │                              │
         └──────── shared-net ──────────┘

Step 1: Create the Network in Project A

project-a/compose.yml:

services:
  api:
    image: node:20-alpine
    networks:
      - shared
  db:
    image: postgres:16
    networks:
      - shared

networks:
  shared:
    name: shared-net

Step 2: Join from Project B

project-b/compose.yml:

services:
  dashboard:
    image: nginx:alpine
    networks:
      - shared

networks:
  shared:
    external: true
    name: shared-net

Step 3: Test Connectivity

# Start both projects
cd project-a && docker compose up -d
cd ../project-b && docker compose up -d

# Dashboard can reach api
docker compose exec dashboard ping api

PING api (172.22.0.2): 56 data bytes
64 bytes from 172.22.0.2: seq=0 ttl=64 time=0.112 ms

Pre-Create Method

You can also create the network manually:

docker network create shared-net

Then both projects use external: true:

networks:
  shared:
    external: true
    name: shared-net

Common Pitfalls

Issue Solution
Network not found Start Project A first, or pre-create
DNS not resolving Both services must be on the same network
Name collision Use explicit name: to avoid prefix

Summary

Approach When to Use
Named network in one project One project “owns” the network
External + pre-created Both projects are independent
Same Compose file Services belong to the same app

Quick Reference

Item Detail
external: true Reference a pre-existing network
name: Explicit network name (no prefix)
Pre-create docker network create shared-net
DNS Services must share a network for DNS

You may also enjoy