Initialise a Docker Swarm with the Right Network Boundaries

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 that is 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; do not use --force-new-cluster as a routine reset.

Checkpoint: continue only when you have identified the intended manager and the current state is not already the Swarm you mean to keep.

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. A loopback address such as 127.0.0.1 is only suitable for a deliberately isolated local test and cannot be used by remote workers.

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. The documentation 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. It is 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 required by your topology.

If you need a different data interface, add --data-path-addr with an address or interface that peers can reach. If you need 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.

Warning: this command creates a Swarm, generates its certificate authority and join tokens, and makes this node an active manager. It is not an inspection command. A failed attempt can still leave you needing to inspect the daemon before trying again.

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 useful results are active, true, Ready, Active and Leader. A single-node Swarm is a valid test or small deployment, but it has no manager redundancy.

Checkpoint: before adding a worker, test reachability to the manager's selected address and port from that worker. Also confirm that the worker can reach the data-path address and port. A successful initialisation proves local configuration, not end-to-end firewall reachability.

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

If it is the last manager, Docker will refuse an ordinary leave because doing so would destroy the manager quorum. Use sudo docker swarm leave --force only when you have deliberately accepted that this node is leaving and the Swarm state on it is no longer needed. Services and cluster membership are operational state, so record the recovery decision before using the force option.

--force-new-cluster has 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.