Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 38 ยท Getting Started

Setting Up a Practice Cluster

Prepare machines for Docker Swarm: install Docker, choose between virtual machines and Docker-in-Docker, open the required ports and plan the node layout.

To learn Swarm properly you want more than one Docker Engine. You do not need a data centre: three small virtual machines or even three containers on a laptop are enough. This lesson explains the options, the network ports Swarm needs, and how to check that your machines are ready before you create a swarm.

Because the site cannot run Docker, everything here is a read-only recipe for your own computer, plus one runnable checker stand-in.

What you need

  • Three Linux hosts is the best starting layout: they let you try a three-manager swarm, survive losing one node, and see scheduling across nodes.
  • Docker Engine installed on each (any recent release; check docker version).
  • Hosts that can reach each other over the network, with fixed addresses.
  • A user that can run docker (member of the docker group, or root).

You can use cheap cloud VMs, local virtual machines (VirtualBox, Hyper-V, Multipass, Vagrant) or physical Raspberry Pis. The commands are identical.

Create three VMs named manager1, worker1, worker2 (or node1 to node3). Give them static or reserved IP addresses, for example 192.168.56.11, .12, .13. On each, install Docker following the official instructions for your distribution, then check:

CONSOLE
$ docker version
$ docker info --format '{{.Swarm.LocalNodeState}}'
inactive

inactive means the Engine is not part of a swarm yet, which is what we want.

Option 2: Docker-in-Docker on one machine

If you only have a laptop, you can run each "node" as a privileged container that itself runs a Docker daemon (the official docker:dind image). This is fine for learning, but it is not a realistic production layout, and --privileged is a serious permission. The sketch below shows the idea only:

CONSOLE
$ docker network create swarm-lab
$ docker run -d --privileged --name node1 --hostname node1 --network swarm-lab docker:dind
$ docker run -d --privileged --name node2 --hostname node2 --network swarm-lab docker:dind
$ docker exec node1 docker info --format '{{.Swarm.LocalNodeState}}'

You then run all swarm commands through docker exec node1 docker .... Disable TLS handling, if your dind image version requires it, as described in the image's documentation. Remove everything afterwards with docker rm -f node1 node2.

Ports Swarm needs

Swarm nodes talk to each other on a few well-known ports. Firewalls between nodes must allow them or the cluster will look "half joined".

Port Protocol Used for
2377 TCP Cluster management traffic (managers listen, nodes join here)
7946 TCP and UDP Node-to-node discovery (gossip)
4789 UDP Overlay network data traffic (VXLAN)
IP protocol 50 (ESP) n/a Only if you use encrypted overlay networks

Ports you publish for your own services (80, 443, 8080 ...) are separate and must be reachable by your users.

On Ubuntu with ufw, opening them looks like this:

CONSOLE
$ sudo ufw allow 2377/tcp
$ sudo ufw allow 7946/tcp
$ sudo ufw allow 7946/udp
$ sudo ufw allow 4789/udp

Never expose port 2377 to the internet. Anyone who can reach it and holds a join token can try to join your cluster. Limit it to the private network between your nodes.

Planning the layout

flowchart TB
  subgraph LAN["Private network 192.168.56.0/24"]
    M["manager1 .11"]
    W1["worker1 .12"]
    W2["worker2 .13"]
  end
  M --- W1
  M --- W2
  W1 --- W2

Three nodes on one private network. Later you will turn the workers into managers to study quorum.

Decide names and addresses now and keep a list. Hostnames matter because Swarm shows them in docker node ls, and you will use them in placement constraints.

A checklist stand-in

Before you run swarm init, check each node. This Python stand-in encodes the checklist so you can see what a pre-flight report might look like. You fill in the facts yourself; it does not talk to a real machine.

Python Stand-in: pre-flight checklist

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that worker1 reports port 2377 as missing. In a real swarm, workers do not need to accept 2377 from others if you never promote them, but opening it on every node keeps promotions painless.

Time and names

Two small details save hours of confusion. First, keep clocks synchronized (chrony or systemd-timesyncd): certificates have validity windows, and a node whose clock is far off will fail TLS checks. Second, use unique hostnames; two nodes with the same name are confusing, even though Swarm tracks them by ID.

One more stand-in: ports as a set

The same idea in a few lines, using a firewall rule list. Try removing 4789 and notice which feature would break (overlay traffic between containers).

Python Stand-in: what breaks without a port?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which port carries cluster management traffic?

    2377/tcp is the cluster management port. 7946 is discovery and 4789 is overlay data.
  2. 2. Which blocked port would stop containers on different nodes from talking over an overlay network?

    Overlay networks use VXLAN on UDP 4789 between nodes.
  3. 3. Why is Docker-in-Docker only suitable for learning?

    dind containers run with --privileged and share one kernel and one machine, so you learn the commands but not real failure behaviour.

Summary

  • Three Linux hosts (VMs are best) give you a realistic practice cluster.
  • Open 2377/tcp, 7946/tcp+udp and 4789/udp between nodes, and ESP if you encrypt overlays.
  • Keep 2377 off the public internet.
  • Fixed IPs, unique hostnames and synchronized clocks prevent many mysteries.

Next: swarm init and join