Domain-linked compose service on two networks makes Traefik route to a stale/wrong IP — 502 that doesn't self-heal (restart/reload insufficient, only container recreate fixes it)

[myagizmaktav]

Summary

When a domain is attached to a Docker Compose service, addDokployNetworkToService (packages/server/src/utils/docker/domain.ts) unconditionally attaches that service to both dokploy-network and the project's implicit default network — this was the intentional fix for #3562 (services losing connectivity to siblings). In a live production incident, this dual-network attachment caused Traefik's Docker provider to select the wrong network's IP for the domain-linked service, producing a persistent 502 Bad Gateway that did not self-heal.

Reproduction / live incident

• App: a single-service (well, two-service: web + a healthcheck-watchdog sidecar) Compose deployment, web has a domain attached.
• web's own docker-compose.yml only declares networks: [dokploy-network] for the service.
• After a deploy, the site started returning 502 Bad Gateway through Cloudflare → Traefik.
• Docker's own HEALTHCHECK reported the container as healthy the entire time (confirmed via docker.getConfig/docker.getContainers through the Dokploy API) — the app itself was fine and responding on 127.0.0.1:3000 inside the container.
• docker.restartContainer (same container ID) did not fix external routing — container came back healthy, site still 502.
• Dokploy's settings.reloadTraefik also did not fix it.
• Inspecting the running container (docker.getConfig) showed it attached to two networks:

  "Networks": {
    "dokploy-network": { "IPAddress": "10.0.1.121", ... },
    "<appName>_default": { "IPAddress": "172.22.0.2", ... }
  }

  even though the user's own compose file never references a default network at all.
• The only thing that fixed it: fully removing the container (docker.removeContainer) and triggering a fresh compose.deploy (new container ID, new network endpoint registration). This matches the pattern already reported in Compose deployments: Traefik routing broken - containers not added to dokploy-network #3435 and the general Traefik-multi-network class of issues (Docker container w. multiple networks, route to wrong IP traefik/traefik#1156, #9551, Traefik v2 routes to wrong Ip, service in 2 networks traefik/traefik#5657).

Root cause (confirmed in current canary source)

packages/server/src/utils/docker/domain.ts:

export const addDokployNetworkToService = (
  networkService: DefinitionsService["networks"],
) => {
  let networks = networkService;
  const network = "dokploy-network";
  const defaultNetwork = "default";
  ...
  if (Array.isArray(networks)) {
    if (!networks.includes(network)) {
      networks.push(network);
    }
    if (!networks.includes(defaultNetwork)) {
      networks.push(defaultNetwork); // <-- always added, unconditionally
    }
  }
  ...
};

This is intentional (per @Siumauricio's comment on #3562: "I think it's a good idea to add the default network to the service where it is specified that the domain should be added"), and is covered by an existing test (apps/dokploy/__test__/compose/domain/network-service.test.ts) that explicitly asserts addDokployNetworkToService(["dokploy-network"]) → ["dokploy-network", "default"].

The tension: this fix for #3562 (keep sibling-service connectivity via the default network) reintroduces the exact multi-network ambiguity that can make Traefik's Docker provider pick the wrong backend IP for the domain-linked service — for compose apps that don't actually need default-network connectivity (single-service apps, or apps managing their own explicit network topology), this default-on behavior has no upside and a real downside (persistent, non-self-healing 502s).

Proposed fix

I've opened a PR (#TODO — filled in after creation) adding an opt-in, backward-compatible per-domain flag skipDefaultNetwork (default false, so all existing behavior/tests are unchanged) that lets a domain skip the default network attachment while still keeping dokploy-network. All existing tests pass unchanged; 5 new tests added for the opt-in path. Happy to adjust the exact API/naming/whether this should live on Domain vs Compose per your preference — this is meant as a starting point for discussion, not a final word on the design.

Environment

• Dokploy version: v0.29.11 (current canary as of 2026-07-12)
• Deployment type: Docker Compose (not Swarm/Application)
• Same server where Dokploy is installed

Will you send a PR to fix it?

Yes — see linked PR.

[djsisson]

there should be a label added

traefik.docker.network=dokploy-network

traefik will always use that label name network for the container ip when specified
https://github.com/traefik/traefik/blob/2a61c9049f119b6e57c7d086f2c07f2086d7b2c1/provider/docker.go#L542

[myagizmaktav]

networks:
  dokploy-network:
    external: true
services:
  web:
    build:
      context: .
      dockerfile: Dockerfile.web
      args:
        VITE_CONVEX_URL: ${VITE_CONVEX_URL:-https://convex.goog.de}
        VITE_CONVEX_SITE_URL: ${VITE_CONVEX_SITE_URL:-https://convex-http.goog.de}
    restart: unless-stopped
    environment:
      TZ: ${TZ:-UTC}
      NODE_ENV: production
      HOST: 0.0.0.0
      PORT: 3000
    networks:
      - dokploy-network
      - default
    labels:
      - traefik.http.routers.general-foxaplicant-uvsoo8-14-web.rule=Host(`foxapplicant.googs.de`)
      - traefik.http.routers.general-foxaplicant-uvsoo8-14-web.entrypoints=web
      - traefik.http.services.general-foxaplicant-uvsoo8-14-web.loadbalancer.server.port=3030
      - traefik.http.routers.general-foxaplicant-uvsoo8-14-web.service=general-foxaplicant-uvsoo8-14-web
      - traefik.http.routers.general-foxaplicant-uvsoo8-14-web.middlewares=redirect-to-https@file
      - traefik.http.routers.general-foxaplicant-uvsoo8-14-websecure.rule=Host(`foxapplicant.sfdsdds.de`)
      - traefik.http.routers.general-foxaplicant-uvsoo8-14-websecure.entrypoints=websecure
      - traefik.http.services.general-foxaplicant-uvsoo8-14-websecure.loadbalancer.server.port=3030
      - traefik.http.routers.general-foxaplicant-uvsoo8-14-websecure.service=general-foxaplicant-uvsoo8-14-websecure
      - traefik.http.routers.general-foxaplicant-uvsoo8-14-websecure.tls.certresolver=letsencrypt
      - traefik.enable=true
      - traefik.docker.network=dokploy-network --- here already have. HERE
      - traefik.http.routers.foxweb.rule=Host(`${WEB_HOST:-foxapplicant.blabla.de}`)
      - traefik.http.routers.foxweb.entrypoints=web
      - traefik.http.routers.foxweb.middlewares=redirect-to-https@file
      - traefik.http.routers.foxweb.service=foxweb
      - traefik.http.routers.foxwebsecure.rule=Host(`${WEB_HOST:-foxapplicant.blabal.de}`)
      - traefik.http.routers.foxwebsecure.entrypoints=websecure
      - traefik.http.routers.foxwebsecure.tls.certresolver=letsencrypt
      - traefik.http.routers.foxwebsecure.service=foxweb
      - traefik.http.services.foxweb.loadbalancer.server.port=3000
      - autoheal=true
  autoheal:
    image: willfarrell/autoheal:latest
    restart: unless-stopped
    environment:
      AUTOHEAL_CONTAINER_LABEL: autoheal
      AUTOHEAL_INTERVAL: 10
      AUTOHEAL_START_PERIOD: 15
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - dokploy-network
     

as you see already defined. @djsisson

[djsisson]

then it doesnt matter what network your service is connected to, traefik is only using the ip from the dokploy-network.

i noticed you have autoheal, but you do not have a defined healthcheck, is that defined in your dockerfile, otherwise it does nothing here
without a defined healthcheck traefik can also sometimes refuse to serve traffic

[myagizmaktav]

@djsisson Thank you — you were right on the network point, and after re-testing I found the actual root cause. Full transparency below.

1. traefik.docker.network — you're correct. I verified against the current v3 source (pkg/provider/docker/config.go, getIPAddress): when the label is set and that network exists in NetworkSettings.Networks, Traefik deterministically returns that network's IP — no ambiguity. Since the label was already set to dokploy-network in my case, the "Traefik picks the wrong network's IP" framing in my original report doesn't hold up for my incident. I retract that as the root cause here (the dual-network attach may still matter for compose setups without the label, but that wasn't my situation).

2. Healthcheck — it is defined, just not in the compose file: it's a HEALTHCHECK in Dockerfile.web (--interval=10s --timeout=3s --start-period=15s --retries=3), which is why docker inspect reported Health.Status: "healthy" throughout the incident, and why autoheal does have something to act on. One small note the other way: for the docker provider, Traefik only removes a container from routing when its health status is literally unhealthy — with no healthcheck there's no health status at all, so Traefik doesn't refuse traffic on that basis.

3. The actual root cause (found while verifying your points): the Dokploy domain for this compose was configured with port 3030, while the app listens on 3000. Dokploy injects its own router/service labels for the domain, so the live container carried two router pairs with the identical Host() rule — my own labels pointing at :3000 (working) and Dokploy's generated ones pointing at :3030 (nothing listening). With identical rules and equal (rule-length) priority, which router wins is effectively arbitrary per provider-config build — which explains everything I observed: persistent 502 with a healthy container, restart/Traefik-reload not helping, and a full container recreate "fixing" it (new config build, winner reshuffles).

I corrected the domain port to 3000 and redeployed — all three services' loadbalancer.server.port labels now point at 3000 and the site is stable. So this turned out to be a misconfiguration on my side amplified by the duplicate-router situation, not the multi-network attach. Sorry for the noise, and thanks for pushing back — it's what led to the real diagnosis. (It might still be worth Dokploy warning when a generated domain router duplicates a user-defined Host() rule on a different port, since the resulting failure mode is very confusing.)