Docker Swarm setup

Edit 2015-01-07: Updated article to reflect changes in swarm. Thanks Rael!

Docker Swarm was announced at the first European DockerCon. Swarm is a pluggable cluster manager with a simple scheduler.

It’s currently not super easy to set up, so here is how I did it.


The swarm executable discovers hosts by reading entries from the discovery url, Sample output:


As you can see, this is just a list of IP/port combinations.

Currently, swarm does not need to run on the hosts themselves. The hosts do need to run docker from the master branch, so the local swarm can talk to it.

Here is a list of the main steps, I’ll go into more detail later. tl;dr: 1. Create a swarm token: swarm create 2. Add hosts to the swarm: swarm join --discovery=token://TOKEN --addr=host_ip:port 3. Start the swarm manager: swarm manage --discovery=token://TOKEN --host=swarm_ip:port 4. Start containers in the swarm: docker -H swarm_ip:port run -dP nginx

The swarm application

The swarm application does a couple of things. It creates a token, and you can add hosts to the discovery address with it. It also functions as a daemon with a rest API. All of these things can run from your local machine, any of your swarm hosts, or from a container.

Swarm is not distributed as an executable at the moment, so we’ll have to compile it. There are multiple options.

If you want to manage your swarm from OSX, install golang using Homebrew: brew install go. Then, get and build the swarm executable by running

GOPATH=$(pwd) go get

You will find the OSX swarm executable under bin/swarm.

If you are running Linux or want to compile for running on Linux using OSX, either install go or use the official go container:

docker run -v $(pwd):/go/bin --rm golang:1.3.3 go get

This will leave the Linux swarm binary in your current working directory.

My favorite option is to just use a container for running swarm. You can use the image that I created in this automated swarm build or roll your own.

#Prepare hosts The hosts need to run docker version 1.4.0 or higher.

I’m going to run this on Digital Ocean, using the docker image. Start up a new droplet, any size will do. Wait for it to boot, then ssh in and add DOCKER_OPTS="-H" to /etc/default/docker.

Restart the daemon using sudo service docker restart

ssh [email protected]_droplet

service docker stop

echo DOCKER_OPTS=\"-H -H unix://var/run/docker.sock\" >> /etc/default/docker

service docker start

Repeat for all the hosts that you want to manage. Done!

#Manager Now we’re ready to start managing.

##Create a new swarm token

swarm create
``` will spit out a token. If you're using the swarm image, go

docker run –rm remmelt/swarm create

##Add each of your hosts to the swarm

swarm join –discovery=token://TOKEN –addr=a.b.c.d:2375

This will add address a.b.c.d:2375 to the swarm. Remember that you can see what is in the swarm by surfing to the [dicovery url](
Running the image? Enter

docker run –rm remmelt/swarm join –discovery=token://TOKEN –addr=a.b.c.d:2375

Note that this command does not currently return. Once the IP has been added to the swarm, you can ctrl-c out. The `join` command does not need to keep running to stay joined.

##Start the management API

swarm manage –discovery=token://TOKEN –host=

This will start the management API. Image:

docker run –rm -p 4243:4243 remmelt/swarm manage –discovery=token://XXXX –host= ``` (we need the port to communicate with the API).

##Start a container Use the docker binary to start a container as usual, but make sure the -H flag points to the host you’re running swarm manage on. In my case, that’s boot2docker.

docker -H boot2docker:4243 run -dP nginx

This will take a while, one of the nodes is downloading the nginx image. The command will return once the container has started.

##List nodes

swarm list --discovery=token://TOKEN


docker run --rm remmelt/swarm list --discovery=token://TOKEN

##List containers

docker -H boot2docker:4243 ps

Note the names of the containers, they start with the name of the node they’re running on.


If you’re getting a tls: oversized record received with length error, run unset DOCKER_TLS_VERIFY and it will work.

Happy swarming!