From 280fa016124e69e6a01debf6d9727b45c3c80905 Mon Sep 17 00:00:00 2001 From: James Turnbull Date: Sat, 2 Aug 2014 07:40:13 -0400 Subject: [PATCH 1/2] Improved installation docs --- README.md | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 45ab73cef9..6a19beb364 100644 --- a/README.md +++ b/README.md @@ -22,22 +22,46 @@ Here are some examples of what you can do with libswarm: * Simulate your entire service topology in a single process, then scale it out simply by re-arranging adapters. * Organize your application as loosely coupled services from day 1, without over-engineering. - + ## Installation -First get the go dependencies: +You can install `libswarm` in a few simple steps. You will need to make +Go installed on your host. + +1. Download the current source code. ```sh -go get github.com/docker/libswarm/... +go get github.com/docker/libswarm ``` -Then you can compile `swarmd` with: +2. Make sure `$GOPATH/bin` is in your `$PATH` + +```sh +export PATH=$GOPATH/bin:$PATH +``` + +3. Download or update the current dependencies. + +```sh +cd $GOPATH/src/github.com/docker/libswarm +make deps +``` + +NOTE: You may also need `bzr`. On OS X, you can install it from +[here](http://wiki.bazaar.canonical.com/MacOSXDownloads) or via Home +Brew: `brew install bzr`. On Debian & Ubuntu, `apt-get install bzr` and +on Red Hat et al, `yum install bzr`. + +4. Then compile `swarmd` with: ```sh go install github.com/docker/libswarm/swarmd ``` -If `$GOPATH/bin` is in your `PATH`, you can invoke `swarmd` from the CLI. +## Running libswarm + +If `$GOPATH/bin` is in your `PATH`, you can invoke `swarmd` from the +command line. ```sh $ swarmd -h From 60fd2048707cff4eb32aa77c5f7337ba9d6a2953 Mon Sep 17 00:00:00 2001 From: James Turnbull Date: Sat, 2 Aug 2014 07:43:44 -0400 Subject: [PATCH 2/2] General cleanup of the README docs --- README.md | 80 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 47 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 6a19beb364..2ae7535dea 100644 --- a/README.md +++ b/README.md @@ -2,26 +2,36 @@ *libswarm* is a toolkit for composing network services. -It defines a standard interface for services in a distributed system to communicate with each other. This lets you: +It defines a standard interface for services in a distributed system to +communicate with each other. This lets you: 1. Compose complex architectures from reusable building blocks 2. Avoid vendor lock-in by swapping any service out with another -An extensive library of services is included, and you can also write your own using a simple API. +An extensive library of services is included, and you can also write +your own using a simple API. Here are some examples of what you can do with libswarm: -* Aggregate all your Docker containers across multiple hosts and infrastructure providers, as if they were running on a single host. +* Aggregate all your Docker containers across multiple hosts and + infrastructure providers, as if they were running on a single host. -* Bridge your in-house DNS-based service discovery with that new shiny Consul deployment, without getting locked into either. +* Bridge your in-house DNS-based service discovery with that new shiny + Consul deployment, without getting locked into either. -* Swap in a new clustering and service discovery system, without changing any application code. +* Swap in a new clustering and service discovery system, without + changing any application code. -* Collect logs across an in-house Mesos cluster, a Cloud Foundry deployment and individual servers staggered in 3 different datacenters, forward them to your legacy syslog deployment, then perform custom analytics on them. +* Collect logs across an in-house Mesos cluster, a Cloud Foundry + deployment and individual servers staggered in 3 different + datacenters, forward them to your legacy syslog deployment, then perform + custom analytics on them. -* Simulate your entire service topology in a single process, then scale it out simply by re-arranging adapters. +* Simulate your entire service topology in a single process, then scale + it out simply by re-arranging adapters. -* Organize your application as loosely coupled services from day 1, without over-engineering. +* Organize your application as loosely coupled services from day 1, + without over-engineering. ## Installation @@ -47,7 +57,7 @@ cd $GOPATH/src/github.com/docker/libswarm make deps ``` -NOTE: You may also need `bzr`. On OS X, you can install it from +**NOTE:** You may also need `bzr`. On OS X, you can install it from [here](http://wiki.bazaar.canonical.com/MacOSXDownloads) or via Home Brew: `brew install bzr`. On Debian & Ubuntu, `apt-get install bzr` and on Red Hat et al, `yum install bzr`. @@ -88,17 +98,18 @@ GLOBAL OPTIONS: *Maintainer: Ben Firshman* -This service runs a Docker remote API server, allowing the Docker client and -other Docker tools to control libswarm services. With no arguments, it listens -on port `4243`, but you can specify any port you like using `tcp://0.0.0.0:9999`, -`unix:///tmp/docker` etc. - +This service runs a Docker remote API server, allowing the Docker client +and other Docker tools to control libswarm services. With no arguments, +it listens on port `4243`, but you can specify any port you like using +`tcp://0.0.0.0:9999`, `unix:///tmp/docker` etc. ### Docker client *Maintainer: Aanand Prasad* -This service can be used to control a Docker Engine from libswarm services. It takes one argument, the Docker host to connect to. For example: `dockerclient tcp://10.1.2.3:4243` +This service can be used to control a Docker Engine from libswarm +services. It takes one argument, the Docker host to connect to. For +example: `dockerclient tcp://10.1.2.3:4243` ### SSH tunnel @@ -140,7 +151,9 @@ This service can be used to control a Docker Engine from libswarm services. It t *Maintainer: Aanand Prasad* -Control an [Orchard](https://www.orchardup.com/) host from libswarm. It takes two arguments, an Orchard API token and the name of the Orchard host to control. +Control an [Orchard](https://www.orchardup.com/) host from libswarm. It +takes two arguments, an Orchard API token and the name of the Orchard +host to control. ### Amazon EC2 @@ -170,41 +183,42 @@ Control an [Orchard](https://www.orchardup.com/) host from libswarm. It takes tw ### Debug -The debug service simply catches all messages and prints them on the terminal for inspection. - +The debug service simply catches all messages and prints them on the +terminal for inspection. ## Testing libswarm with swarmd -Libswarm ships with a simple daemon which can control services in your distributed system. - -Usage example: +The libswarm library ships with a simple daemon which can control services in your +distributed system. +### Usage examples Run swarmd without arguments to list available services: -``` -./swarmd +```sh +swarmd ``` Pass a service name as argument to load it: -``` -./swarmd fakeclient +```sh +swarmd fakeclient ``` You can pass arguments to the service, like a shell command: -``` -./swarmd 'dockerserver tcp://localhost:4243' +```sh +swarmd 'dockerserver tcp://localhost:4243' ``` -You can call multiple services. They will be executed in parallel, with the output -of each backend connected to the input of the next, just like unix pipelines. +You can call multiple services. They will be executed in parallel, with +the output of each backend connected to the input of the next, just like +`unix` pipelines. This allows for very powerful composition. -``` -./swarmd 'dockerserver tcp://localhost:4243' 'debug' 'dockerclient unix:///var/run/docker.sock' +```sh +swarmd 'dockerserver tcp://localhost:4243' 'debug' 'dockerclient unix:///var/run/docker.sock' ``` ## Creators @@ -216,5 +230,5 @@ This allows for very powerful composition. ## Copyright and license -Code and documentation copyright 2013-2014 Docker, inc. Code released under the Apache 2.0 license. -Docs released under Creative commons. +Code and documentation copyright 2013-2014 Docker, inc. Code released +under the Apache 2.0 license. Docs released under Creative commons.