Edit 2015-01-07: Updated article to reflect changes in swarm. Thanks Rael!
It's currently not super easy to set up, so here is how I did it.
swarm executable discovers hosts by reading entries from the discovery url, discovery-stage.hub.docker.com/v1/clusters/TOKEN. Sample output:
As you can see, this is just a list of IP/port combinations.
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:
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
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 github.com/docker/swarm
You will find the OSX
swarm executable under
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 github.com/docker/swarm
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.
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 0.0.0.0:2375" to
Restart the daemon using
sudo service docker restart
ssh root@digitalocean_droplet service docker stop echo DOCKER_OPTS=\"-H 0.0.0.0:2375 -H unix://var/run/docker.sock\" >> /etc/default/docker service docker start
Repeat for all the hosts that you want to manage. Done!
Now we're ready to start managing.
Create a new swarm token
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=0.0.0.0:4243
This will start the management API. Image:
docker run --rm -p 4243:4243 remmelt/swarm manage --discovery=token://XXXX --host=0.0.0.0:4243
(we need the port to communicate with the API).
Start a container
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
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.
swarm list --discovery=token://TOKEN
docker run --rm remmelt/swarm list --discovery=token://TOKEN
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
unset DOCKER_TLS_VERIFY and it will work.