Initialise a Docker Swarm with the Right Network Boundaries

Run docker swarm init on the wrong interface and every worker you add later fails to reach the manager, so get the address right first. You will finish with the current Docker Engine configured as the manager of a single-node Swarm, with its advertised address and listening port chosen deliberately. The examples were checked against Docker CLI 29.8.1 from package docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble.

Allow about fifteen minutes for a clean test, plus time to check firewall rules. You need Docker Engine running, access to the Docker daemon, a stable IP address or interface name, and a shell on the intended manager. The initialisation command changes daemon state and creates Swarm data, so do not run it on a host already part of a Swarm, or on a production daemon without a maintenance plan.

1. Check the Docker version and current Swarm state

These are ordinary read-only checks. The version matters because newer Docker releases add options to this command:

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker info --format 'server={{.ServerVersion}} swarm={{.Swarm.LocalNodeState}}'
server=29.8.1 swarm=inactive

Your build identifier and Swarm state can differ. If the state is active, this daemon is already in a Swarm: stop here and inspect it with docker info and docker node ls rather than reaching for --force-new-cluster as a routine reset.

2. Identify an address other nodes can reach

Use an address assigned to a real interface on this host. Other nodes use the advertised address to contact the manager, and a loopback address such as 127.0.0.1 only suits a deliberately isolated local test since remote workers cannot use it. List addresses without changing anything:

$ ip -br address
lo               UNKNOWN        127.0.0.1/8 ::1/128
enp1s0           UP             192.0.2.10/24

Replace 192.0.2.10 below with the address on your host. Docker recommends a fixed address because workers must keep reaching the manager; if the host has several interfaces, choose the one on the network where Swarm peers will connect.

3. Plan the three relevant network settings

• --advertise-addr tells other nodes where this manager should be reached.
• --listen-addr controls where the manager listens for Swarm control traffic and defaults to 0.0.0.0:2377. Setting it explicitly makes the boundary visible.

$ docker swarm init \
    --advertise-addr 192.0.2.10:2377 \
    --listen-addr 192.0.2.10:2377

The port in both addresses is the Swarm management port in this example, not the published application port. You must also account for the data-path port, which defaults to UDP 4789 when --data-path-port is omitted or set to zero. Firewall rules and cloud security groups must allow the traffic your topology needs.

If you need a different data interface, add --data-path-addr with an address or interface that peers can reach. For a different data port, use --data-path-port PORT, where the installed command accepts ports from 1024 to 49151. Make these choices before initialisation: changing them later is an operational change, not a cosmetic preference.

4. Initialise the manager

Run the command with the Docker permissions appropriate to your installation. If your account cannot access the daemon, prefix it with sudo; that privilege is required for the daemon operation, not for reading the manpage or checking the version.

$ sudo docker swarm init \
    --advertise-addr 192.0.2.10:2377 \
    --listen-addr 192.0.2.10:2377
Swarm initialized: current node (<node-id>) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token <worker-token> 192.0.2.10:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

The node ID and join token are generated values. Treat the worker and manager tokens as credentials: do not paste them into tickets, public logs or source control. If a token is exposed, rotate it from a manager with docker swarm join-token --rotate worker or the corresponding manager command.

5. Verify the manager and its advertised address

Check the resulting state from the manager:

$ sudo docker info --format 'server={{.ServerVersion}} swarm={{.Swarm.LocalNodeState}} control={{.Swarm.ControlAvailable}}'
server=29.8.1 swarm=active control=true
$ sudo docker node ls
ID                            HOSTNAME   STATUS    AVAILABILITY   MANAGER STATUS
<node-id> *                  <hostname> Ready     Active          Leader

The exact ID, hostname and table spacing are host-specific. The results that matter are active, true, Ready, Active and Leader. A single-node Swarm is a valid test or small deployment, but it has no manager redundancy.

6. Add nodes without losing the join command

On the manager, regenerate the worker command when you need it:

$ sudo docker swarm join-token worker
To add a worker to this swarm, run the following command:

    docker swarm join --token <worker-token> 192.0.2.10:2377

Run the displayed command on the worker, not on the manager. Use docker swarm join-token manager when adding another manager. After a worker joins, return to the manager and run sudo docker node ls; management commands such as this one require a manager.

If a join fails, check DNS or the chosen address, firewall rules, the listening port, and whether the token belongs to this Swarm. Do not repeatedly initialise the manager to repair a worker join problem.

7. Recover from a wrong or unwanted initialisation

If this node must leave the Swarm and is not the last manager, leave it with:

$ sudo docker swarm leave

--force-new-cluster serves a different purpose: it rebuilds a single-manager cluster from the current manager state, for example after the other managers are permanently lost. It is not an undo for a mistyped address, and should be treated as a recovery procedure.