New tutorial for beginners, this time is an introduction to Swarm, an orchestration tool which comes with Docker. I wrote this tutorial after following the official quickstart and after filtering which I think is the most useful information to start with orchestration.

Likewise, I’m adding some explanations of what I found most difficult to understand.

Previously in Kubernetes

Some months ago, I followed a Kubernetes tutorial, the Google orchestrator, which these days have the most traction power. During and after the excercise, I felt like:

Dog typing in a keyboard
Don't know what I'm doing

It seemed to me a very sophisticated tool, far from being beginner-friendly. This made sense, because it’s a relatively new tool, which affects the maturity of documentation; besides, it was solving a complex problem, outside my knowledge zone. Thus, I concluded that orchestration wasn’t my thing.

However, I’ve spent two weeks studying the basis of Swarm, and now I think there is a way of approaching the question, more suitable for beginners. So, there we go!

Detailed goal

I’ve looked through several Swarm tutorials, and I’ve seen different approaches, so maybe it’s useful to share the specific scope of this tutorial; what I want to show is:

  • basic concepts of orchestration: state, replicas, nodes, manager, worker, routing
  • basic commands to create a Swarm cluster
  • basic commands to deploy docker images in a Swarm
  • how to write a docker-compose.yml file in version 3, which can be used in a Swarm

All this information will be split in several posts to make it easier to follow.


This tutorial assumes that you understand the basis of docker. If it’s the first time you’re going to deal with docker, I recommend you to spend a while with this introduction to docker and with this other introduction to Dockerfile.

Besides, I’ll use an example that starts after we can put our application in a docker image available through a registry. I published recently an introduction to GitlabCI that you may find useful.

Let's start!

We’d like to learn how to orchestrate with Swarm. Orchestration is the set of tools and practices to deploy applications that can be in HA (high availability, the service is always responding), and where the infrastructure can scale quickly (if there is a peak, the service can be updated seamlessly). To achieve that, we’re going to use Swarm mode that comes out-of-the-box with docker. We’ll need a cluster: the (tipically physical) machines available for creating the nodes for Swarm. Those machines need to have visibility between them.

So we’re going to create a cluster in our machine, which replicates a scenario similar to what could be the cloud. With Vagrant, we’re using 3 virtual machines (that will be our nodes). You can use this Vagrantfile and its provision. If you type vagrant up in the Vagrantfile directory, the system will load 3 virtual machines with ubuntu (and docker).

Don’t try the Swarm commands directly in your machine; when activating the Swarm mode, your docker will be modified and you’ll probably need to rollback some changes. The best option is to use the virtual machines in Vagrant.

Swarm works distributing the services among the cluster machines. Each machine, by default is a worker; in addition, some machines are managers: those managers know the state of the cluster; if a node falls, managers detect it and launch measures to restablish the desired application state. In a Swarm cluster there should be always an odd number of managers, so they can use consensus algorithms.

So first thing we’re gonna do is to initialize one of the machines as a manager (server1) and we’re going to associate the rest (server2 and server3) as workers:

# enter the server1
(myhost)$ vagrant ssh server1
(server1)$ docker swarm init --advertise-addr

The output of this command is needed to associate the rest of the nodes to the cluster; the output will be similar to:

Swarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager.

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

    docker swarm join \
    --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \

If by any chance, we lose this command (maybe we close the window terminal), we can recover it executing in the manager node the following command:

(server1)$ docker swarm join-token worker

Now we have to enter in both of the other machines and execute this docker swarm join –token… command in server2 and server3. Done! We’ve a Swarm cluster up and running. Now, a couple of useful commands:

# to see the list of services in a cluster
(server1)$ docker service ls

# to see the nodes in a cluster
(server1)$ docker node ls
ID                            HOSTNAME     STATUS     AVAILABILITY     MANAGER STATUS
niqaah8mhlou9gij2fye046sq *   server1      Ready      Active           Leader
qowv0xmux806zu5u7f7or4yed     server2      Ready      Active
w92gfg7dwl33esmmk7acnhcdk     server3      Ready      Active

The asterisk indicates the current node, and Leader tells that this is a manager node.

Well done! So far, we’ve seen some basic concepts and we’ve created a cluster. Next post will cover how to create services, update and inspect them. But now, it could be a good moment to stretch your legs. See you in the next post!