diff --git a/README.md b/README.md index 3b7f28ad71..a2ababb00e 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,8 @@ speaks Docker can control swarm transparently: dokku, fig, krane, flynn, deis, docker-ui, shipyard, drone.io, Jenkins... and of course the Docker client itself. Like the other Docker projects, `swarm` follows the "batteries included but removable" -principle. It ships with a simple scheduling backend out of the box. The goal is +principle. It ships with a simple scheduling backend out of the box, and as initial +development settles, an API will develop to enable pluggable backends. The goal is to provide a smooth out-of-box experience for simple use cases, and allow swapping in more powerful backends, like `Mesos`, for large scale production deployments. @@ -44,7 +45,7 @@ $ swarm create # on each of your nodes, start the swarm agent # doesn't have to be public (eg. 192.168.0.X), # as long as the other nodes can reach it, it is fine. -$ swarm join --addr= token:// +$ swarm join --addr= --discovery=token:// # start the manager on any machine or your laptop $ swarm manage -H tcp:// token:// @@ -57,7 +58,7 @@ $ docker -H tcp:// logs ... ... # list nodes in your cluster -$ swarm list token:// +$ swarm list --discovery=token:// ``` @@ -86,7 +87,7 @@ Note that Swarm certificates must be generated with`extendedKeyUsage = clientAut ## Participating -We welcome pull requests and patches; come say hi on IRC, #docker-swarm on freenode. +We welcome pull requests and patches; come say hi on IRC, #swarm on freenode. ## Creators diff --git a/userguide.md b/userguide.md index 5b8516b4f3..310c339fa2 100644 --- a/userguide.md +++ b/userguide.md @@ -4,56 +4,62 @@ page_description: Swarm: a Docker-native clustering system page_keywords: docker, swarm, clustering --- -# Swarm: a Docker-native clustering system [![Build Status](https://travis-ci.org/docker/swarm.svg?branch=master)](https://travis-ci.org/docker/swarm) +# Docker Swarm: a Docker-native clustering system -![Docker Swarm Logo](logo.png?raw=true "Docker Swarm Logo") +Docker `swarm` helps you control a cluster of Docker hosts (known as nodes) +and expose them as a single "virtual" host. -`swarm` is a simple tool which controls a cluster of Docker hosts and exposes it -as a single "virtual" host. - -`swarm` uses the standard Docker API as its frontend, which means any tool which -speaks Docker can control swarm transparently: dokku, fig, krane, flynn, deis, -docker-ui, shipyard, drone.io, Jenkins... and of course the Docker client itself. +The Docker `swarm` manager can be interacted with using the Docker API, which means +any tool which can communicate with a Docker Daemon using that API, can control +a Docker swarm transparently: dokku, fig, krane, flynn, deis, docker-ui, shipyard, +drone.io, Jenkins... and of course the Docker client itself. Like the other Docker projects, `swarm` follows the "batteries included but removable" -principle. It ships with a simple scheduling backend out of the box. The goal is +principle. It ships with a simple scheduling backend out of the box, and as initial +development settles, an API will develop to enable pluggable backends. The goal is to provide a smooth out-of-box experience for simple use cases, and allow swapping in more powerful backends, like `Mesos`, for large scale production deployments. ## Installation -###1 - Download and install the current source code. -Ensure you have golang installed (e.g. `apt-get install golang` on Ubuntu). -You may need to set `$GOPATH`, e.g `mkdir ~/gocode; export GOPATH=~/gocode`. +> **Note**: The only requirement for Swarm nodes is they all run the _same_ release +> Docker daemon (version `1.4.0` and later), configured to listen to a `tcp` +> port that the Swarm manager can access. -The install `swarm` binary to your `$GOPATH` directory. +Docker `swarm` is currently only available as a single go binary on Linux. Download +it from [the latest release](https://github.com/docker/swarm/releases/latest) page +on GitHub. -```sh -go get -u github.com/docker/swarm +For example: + +``` + $ wget -O swarm https://github.com/docker/swarm/releases/download/v0.1.0-rc1/swarm-Linux-x86_64 + # OR + $ curl -SsL https://github.com/docker/swarm/releases/download/v0.1.0-rc1/swarm-Linux-x86_64 > swarm + $ chmod 755 swarm + $ sudo cp swarm /usr/local/bin ``` -###2 - Nodes setup -The only requirement for Swarm nodes is to run a regular Docker daemon (version -`1.4.0` and later). +## Nodes setup -In order for Swarm to be able to communicate with its nodes, they must bind on a -network interface. This can be achieved by starting Docker with the `-H` flag -(e.g. `-H tcp://0.0.0.0:2375`). +Each swarm node will run a swarm node agent which will register the referenced +Docker daemon, and will then monitor it, updating the discovery backend to its +status. -# Example usage +The following example uses the Docker Hub based `token` discovery service: ```bash # create a cluster $ swarm create 6856663cdefdec325839a4b7e1de38e8 # <- this is your unique -# on each of your nodes, start the swarm agent -# doesn't have to be public (eg. 192.168.0.X), -# as long as the other nodes can reach it, it is fine. -$ swarm join --addr= token:// +# For each of your nodes, start a swarm agent +# the Docker daemon doesn't have to be public (eg. 192.168.0.X), +# as long as the swarm manager can access it. +$ swarm join --addr= --discovery token:// # start the manager on any machine or your laptop -$ swarm manage -H tcp:// token:// +$ swarm manage -H tcp:// --discovery token:// # use the regular docker cli $ docker -H tcp:// info @@ -63,24 +69,23 @@ $ docker -H tcp:// logs ... ... # list nodes in your cluster -$ swarm list token:// +$ swarm list --discovery token:// ``` -See [here](discovery) for more information about -other discovery services. +> **Note**: In order for the Swarm manager to be able to communicate with the node agent on +each node, they must listen to a common network interface. This can be achieved +by starting with the `-H` flag (e.g. `-H tcp://0.0.0.0:2375`). -## Advanced Scheduling - -See [filters](scheduler/filter) and [strategies](scheduler/strategy) to learn -more about advanced scheduling. ## TLS Swarm supports TLS authentication between the CLI and Swarm but also between -Swarm and the Docker nodes. +Swarm and the Docker nodes. _However_, all the Docker daemon certificates and client +certificates **must** be signed using the same CA-certificate. -In order to enable TLS, the same command line options as Docker can be specified: +In order to enable TLS for both client and server, the same command line options +as Docker can be specified: `swarm manage --tlsverify --tlscacert= --tlscert= --tlskey= [...]` @@ -88,27 +93,13 @@ Please refer to the [Docker documentation](https://docs.docker.com/articles/http for more information on how to set up TLS authentication on Docker and generating the certificates. -Note that Swarm certificates must be generated with`extendedKeyUsage = clientAuth,serverAuth`. +> **Note**: Swarm certificates must be generated with`extendedKeyUsage = clientAuth,serverAuth`. -## Participating +## Discovery services -We welcome pull requests and patches; come say hi on IRC, #docker-swarm on freenode. +See the [Discovery service](../discovery) document for more information. -## Creators +## Advanced Scheduling -**Andrea Luzzardi** - -- -- - -**Victor Vieux** - -- -- - -## Copyright and license - -Code and documentation copyright 2014-2015 Docker, inc. Code released under the -Apache 2.0 license. - -Docs released under Creative commons. +See [filters](../scheduler/filter) and [strategies](../scheduler/strategy) to learn +more about advanced scheduling.