Docker Compose Networking#

Dokploy automatically transforms Docker Compose files at deploy time to inject networks that wire services together and connect them to the Traefik reverse proxy. There are two distinct networking modes, controlled by the isolatedDeployment flag on the compose schema 1.

Two Networking Modes#

1. Shared Mode (default: isolatedDeployment = false)#

Every service that has a domain configured receives two injected networks:

• dokploy-network (external) — the shared network Traefik listens on. Injected via addDokployNetworkToService() and addDokployNetworkToRoot() in packages/server/src/utils/docker/domain.ts.
• default — Docker Compose's implicit project-scoped bridge network, injected to preserve connectivity between services that rely on it.

Both are added unconditionally by the current implementation inside addDomainToCompose() 2.

2. Isolated Mode (isolatedDeployment = true)#

A unique bridge (or Swarm overlay for stack deployments) network named after the app is created per deployment 3:

docker network inspect <appName> || docker network create [--driver overlay] --attachable <appName>
docker network connect <appName> $(docker ps --filter "name=dokploy-traefik" -q)

The app-name network is injected into the Compose file via addAppNameToRootNetwork() and addAppNameToServiceNetworks() in packages/server/src/utils/docker/collision/root-network.ts. Traefik is then connected to that network, so routing still works.

Network Suffix Collision Prevention#

When multiple Compose apps share the same network names, Dokploy applies a suffix (e.g. frontend-abc123) to avoid collisions. The logic lives in packages/server/src/utils/docker/compose/network.ts:

dokploy-network is always excluded from suffixing 4 so that Traefik's shared network is never renamed.

Address Pool Exhaustion — Root Cause & Status#

The problem: Issue #4499 and Issue #4759 document a production failure where Dokploy exhausts Docker's predefined IPv4 address pools:

Error response from daemon: all predefined address pools have been fully subnetted

Root cause: PR #3614 (merged 2026-02-07) made addDokployNetworkToService() unconditionally inject the "default" network onto every service, even those that already declared explicit networks 5. Each such service causes Docker Compose to create a new <project>_default bridge network on every deploy. On a host with many deployments, Docker's pool of ~30 default /24 subnets is exhausted.

Pending fix: PR #4592 (open as of 2026-07-07) adds a guard: default is only injected when the service had no networks key at all (the undefined case, i.e. it was relying on the implicit Docker Compose default network) 6. Services with an explicit networks key — even an empty one — do not get default injected, avoiding the unnecessary bridge network creation.

Workarounds (Until PR #4592 Merges)#

1. Expand Docker's address pool — add to /etc/docker/daemon.json 7:

   ⧉

   {
     "default-address-pools": [
       { "base": "172.16.0.0/12", "size": 24 }
     ]
   }
   

   Restart Docker after applying.

2. Prune unused networks — docker network prune removes all unused bridge networks and reclaims subnets 7.

3. Declare explicit networks in your Compose file — services that define a networks: key (even if it only lists dokploy-network) are not affected by the pool exhaustion bug 6.

4. Use isolatedDeployment = true — creates a single named network per app rather than a default bridge per deployment.

Related Issues#

Key Source Files#