Allow configuring the platform network name instead of hardcoding dokploy-network

Open
  • Is something wrong?
#5,827 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
docker, typescript
Domain
devops, infrastructure, networking

Research direction

Start with packages/server/src/setup/setup.ts and trace the network-name uses named in the issue, including Traefik setup, RESERVED_NETWORKS, and server health. Decide how the requested configuration should stay consistent across those entry points, and whether disabling creation is in scope. Done means the chosen option works while defaulting to current behavior.

Written by the indexing model from the issue text.

Description

We run Dokploy self-hosted (v0.30.3, single-node Docker Swarm 29.9.2, Ubuntu 24.04) with a network-per-app-group model: each group of apps gets its own overlay --attachable network on a dedicated /24, Traefik joins all of them, and nothing else is reachable from outside. Everything in that model works except the platform network, which we cannot control.

What happens

dokploy-network reappears, empty, about 30 seconds after every Docker daemon start. It comes from initializeNetwork() in packages/server/src/setup/setup.ts, called unconditionally from server.mjs on the self-hosted branch:

export const initializeNetwork = async () => {
  const networkInitialized = await dockerNetworkInitialized();
  if (networkInitialized) return;
  docker.createNetwork({
    Attachable: true,
    Name: "dokploy-network",
    Driver: "overlay",
  });
};

The name is hardcoded. Grepping v0.30.3 and the current main bundle gives 68 occurrences across setup, postgres-setup, traefik-setup, forward-auth-setup, server-setup, server-validate, services/network, utils/docker/compose/network, utils/docker/domain and services/server-health. There is no DOKPLOY_*NETWORK* environment variable, no DB setting, no UI toggle, and the name is in RESERVED_NETWORKS. It is unchanged on v0.30.10.

Why it breaks an isolation model
  • A host that enforces per-group networks can only delete the recreated network in a loop, and that loop never converges because the platform recreates it at every start. We ran a 15-minute guard that removed it for a while. It "worked", but the window between create and delete is real, and every boot produced a false alarm.
  • Leaving it in place empty is worse than the alarm: it is an attachable network with a familiar name, so a deploy that forgets to declare a network lands there and appears to succeed while bypassing the isolation model entirely.
  • Making it inert is not possible. Docker allows exactly one null-driver network (none); docker network create -d null dokploy-network fails with only one instance of "null" network is allowed, and every other driver is attachable.
What we do now

We keep dokploy-network as the Dokploy control plane and enforce membership: its own /24, only dokploy, dokploy-postgres and the Traefik container may be attached, a 15-minute guard detaches anything else and alerts, and applications use Isolated Deployments or an explicitly assigned group network. With that in place initializeNetwork() finds the network and logs Network is already initialized, which is the behaviour we want. It works, but it is a host-side workaround for a naming concern, and it depends on the reserved name staying reserved.

Request

Either or both:

  1. DOKPLOY_NETWORK_NAME (default dokploy-network), resolved once and used everywhere the name currently appears - ideally as a single exported constant rather than 68 literals, so the UI, RESERVED_NETWORKS, Traefik setup and server-health stay consistent with the configured value.
  2. DOKPLOY_DISABLE_DEFAULT_NETWORK=true to skip creation entirely, for operators who assign every network explicitly.

Both should default to current behaviour so existing installs are unaffected.

Steps to reproduce
  1. Self-hosted Dokploy without dokploy-network.
  2. docker network rm dokploy-network, or start from a fresh daemon.
  3. Restart dockerd, then restart the Dokploy container/service.
  4. docker network ls shows dokploy-network again, and docker network inspect dokploy-network shows no containers.

Related: #2798 (network management and isolation) and #4637 (network isolation per project and environment).

Dominant language
TypeScript
Stars
38.2k
Forks
3.1k
Avg merge
2d 7h
Merged PRs (30d)
69

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Dokploy/dokploy

All issues in Dokploy/dokploy

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.