README.md in percheron-0.7.10 vs README.md in percheron-0.7.11
- old
+ new
@@ -4,21 +4,38 @@
[](https://travis-ci.org/ashmckenzie/percheron)
[](https://codeclimate.com/github/ashmckenzie/percheron)
[](https://codeclimate.com/github/ashmckenzie/percheron)
[](https://gemnasium.com/ashmckenzie/percheron)
-Organise your Docker containers with muscle and intelligence.
+
+### Organise your Docker containers with muscle and intelligence.
+
+## Why?
+
+Percheron aims to address the following challenges when working with Docker images and containers:
+
+* Managing multiple containers and mutiple sets (stacks) of containers
+* Building images and containers with support for dependencies
+* Versioning of images and containers
+
+Percheron is like Vagrant but instead of managing VM's, it manages Docker images and containers.
+It is a very handy tool when you wish to create a basic or complex stack without the need to run
+multiple VMs.
+
+It is intended to be used in a test, development or prototyping scenario.
+
## Features
-* Single, easy to write `.percheron.yml` controls everything
-* Supports building, creating and starting of containers and their dependancies
-* Supports building using a Dockerfile or pulling a Docker image from Docker Hub
-* Build 'base' images as a dependancy and then build from there
-* Support for pre-build and post-start scripts when generating images and starting containers
-* Version control of building images and containers
-* Generate Graphviz dependancy graphs dynamically
+* Single, easy to write `.percheron.yml` describes your stack(s)
+* Build, create and start units and their dependencies
+* Build units using a Dockerfile or by pulling Docker images from Docker Hub
+* Build 'bare/base' images and build new images on top of them
+* Support for pre-build and post-start scripts when generating images and starting units
+* Version control of images and units
+* Partial template (liquid) support within `.percheron.yml`
+* Generate Graphviz dependency graphs dynamically based purely on your `.percheron.yml`
* Written in Ruby :)
## Supported platforms
* Linux
@@ -50,17 +67,53 @@
* [Docker 1.6.x](https://docs.docker.com/installation/) / [Boot2Docker v1.6.x+](https://docs.docker.com/installation)
* [Docker client](https://docs.docker.com/installation) (nice to have)
## Usage
-1) Install percheron
+```
+Usage:
+ percheron [OPTIONS] SUBCOMMAND [ARG] ...
+Parameters:
+ SUBCOMMAND subcommand
+ [ARG] ... subcommand arguments
+
+Subcommands:
+ list, status List stacks and its units
+ console Start a pry console session
+ start Start a stack
+ stop Stop a stack
+ restart Restart a stack
+ build Build images for a stack
+ create Build images and create units for a stack
+ recreate Recreate a stack
+ purge Purge a stack
+ shell Shell into a unit
+ logs Show logs for a unit
+ graph Generate a stack graph
+
+Options:
+ -h, --help print help
+ -c, --config_file CONFIG Config file (default: ".percheron.yml")
+ --version show version
+```
+
+## Demo (using boot2docker)
+
+1) Get boot2docker up and running
+
```bash
+boot2docker up && eval $(boot2docker shellinit) && export BOOT2DOCKER_IP=$(boot2docker ip)
+```
+
+2) Install percheron
+
+```bash
gem install percheron
```
-2) Create a `.percheron.yml` file describing your stack:
+3) Create a `.percheron.yml` file describing the stack, in this case [consul](https://consul.io/):
```yaml
---
docker:
host: "https://boot2docker:2376"
@@ -84,40 +137,83 @@
start_args: "-server -join master"
dependant_unit_names:
- master
```
-3) Start it up!
+4) Start it up!
```bash
percheron start consul-stack
+
+I, [2015-05-21T19:25:05.975964 #35449] INFO -- : Starting 'master' unit
+I, [2015-05-21T19:25:06.676782 #35449] INFO -- : Starting 'agent1' unit
+I, [2015-05-21T19:25:07.167997 #35449] INFO -- : Starting 'agent2' unit
```
-4) Bring up the consul UI
+5) Show the status
```bash
+percheron status consul-stack
+
++--------+--------------+----------+------------+------------------------+---------+---------+
+| consul-stack |
++--------+--------------+----------+------------+------------------------+---------+---------+
+| Unit | ID | Running? | IP | Ports | Volumes | Version |
++--------+--------------+----------+------------+------------------------+---------+---------+
+| master | 0acd1e2cfbc0 | yes | 172.17.0.1 | 8500:8500, 8600:53/udp | | 1.0.0 |
+| agent1 | d70495c1c62b | yes | 172.17.0.2 | | | 1.0.0 |
+| agent2 | 458ad3ba0890 | yes | 172.17.0.3 | | | 1.0.0 |
++--------+--------------+----------+------------+------------------------+---------+---------+
+```
+
+6) Ensure consul is running
+
+```bash
+curl http://boot2docker:8500/v1/catalog/nodes
+
+[{"Node":"agent1","Address":"172.17.0.5"},{"Node":"agent2","Address":"172.17.0.6"},{"Node":"master","Address":"172.17.0.4"}]
+```
+
+7) Perform some DNS lookups using consul
+
+```bash
+dig @boot2docker -p 8600 master.node.consul agent1.node.consul agent2.node.consul +short
+
+172.17.0.7
+172.17.0.8
+172.17.0.9
+```
+
+8) Bring up the consul UI
+
+```bash
open http://boot2docker:8500/ui
```
-5) Perform some DNS lookups
+9) Purge it!
```bash
-dig @boot2docker -p 8600 master.node.consul +short
-dig @boot2docker -p 8600 agent1.node.consul +short
-dig @boot2docker -p 8600 agent2.node.consul +short
+percheron purge consul-stack
+
+I, [2015-05-21T19:28:23.925205 #35710] INFO -- : Stopping 'agent2' unit
+I, [2015-05-21T19:28:24.269218 #35710] INFO -- : Deleting 'agent2' unit
+I, [2015-05-21T19:28:24.452320 #35710] INFO -- : Stopping 'agent1' unit
+I, [2015-05-21T19:28:24.811764 #35710] INFO -- : Deleting 'agent1' unit
+I, [2015-05-21T19:28:24.965680 #35710] INFO -- : Stopping 'master' unit
+I, [2015-05-21T19:28:25.246578 #35710] INFO -- : Deleting 'master' unit
```
-## Dependancy graph
+## Dependency graph
Note: Requires [Graphviz](http://graphviz.org/) installed.
```bash
percheron graph consul-stack
```
-## Demo
+## Demo asciicast
[](https://asciinema.org/a/7l1ar35xlmfsaphhptrqvx7jg)
## Debugging