Traefik Docker Network Routing#

Traefik discovers containers via the Docker socket and must know which network IP to use when a container is on multiple networks. Dokploy controls this through label injection and network attachment, with different behaviors in shared vs. isolated deployment modes.

Network Selection: Shared vs. Isolated Mode#

Shared mode (isolatedDeployment = false, the default): addDomainToCompose() injects dokploy-network (an external bridge) into every service that has a domain, and sets the traefik.docker.network=dokploy-network label (or traefik.swarm.network=dokploy-network for Swarm stacks) 1. This explicitly tells Traefik which network IP to use, preventing non-deterministic selection.

Isolated mode (isolatedDeployment = true): a per-app named network is created at deploy time and Traefik is dynamically connected to it 2. The traefik.docker.network label is not injected for isolated deployments 3 — Traefik is expected to auto-detect the correct network because it is the only shared network between Traefik and the service.

The network label injection logic lives in addDomainToCompose(), and the network attachment helpers are addDokployNetworkToService() and addDokployNetworkToRoot().

Known Failure Modes#

1. Multi-Network Auto-Detection Failures (504 on restart)#

Symptom: 504 gateway timeout on the first request after a container restart, resolving after Traefik reload.

Root cause: When a container is on multiple networks, Traefik picks whichever Docker reports first — a non-deterministic order that can change across restarts. If Traefik selects an internal network IP it cannot reach, all requests time out until it is reloaded 4.

Fix: Ensure traefik.docker.network is set on the service. For shared-mode deployments this label is injected automatically. For isolated deployments where the service also has additional internal networks, add traefik.docker.network=<app-name> to the service labels manually. Related issues: #778, #821, #3200.

A fallback is to add the global network directive to the Traefik Docker provider in /etc/dokploy/traefik/traefik.yml 4:

providers:
  docker:
    exposedByDefault: false
    watch: true
    network: dokploy-network

2. Missing Routing Labels in Isolated Deployments#

Symptom: Services in isolated deployments become unreachable (404) when the service container is also connected to other internal networks.

Root cause: traefik.docker.network is intentionally omitted for isolated deployments 3, but if the service joins additional networks after deploy (e.g., for inter-service communication), Traefik's auto-detection may select the wrong one. A user confirmed that manually adding traefik.docker.network=<app-name> resolved the issue 4.

3. Non-Persistent Network Attachments After Traefik Restart#

Symptom: After Traefik is restarted or recreated (e.g., via UI settings changes like toggling the dashboard or saving port mappings), all isolated-deployment services become unreachable (404). Only dokploy-network remains connected to the Traefik container 5.

Root cause: Isolated-mode network attachment (docker network connect <appName> dokploy-traefik) happens only at deploy time 6. When Traefik is recreated, its container ID changes and the previous network connections are lost. Docker does not persist these runtime network connect calls 5.

Workarounds (until a permanent fix lands):

• Redeploy each affected compose app via the UI to re-run docker network connect.

• Manually reconnect Traefik to all isolated networks:

  ⧉

  for net in $(docker network ls --filter "driver=bridge" --format "{{.Name}}" | grep "^<prefix>-"); do
    docker network connect "$net" dokploy-traefik 2>/dev/null
  done
  

  5

A maintainer acknowledged this as a real bug requiring automatic reconnection when Traefik is recreated 5. The issue also affects VM reboots — isolated-deployment containers are not reconnected to Traefik on host startup 5.

Relevant Source Files#