top
(README.md)
![Zodiac](http://panamax.ca.tier3.io/logos/logo_zodiac.png)


##### A lightweight tool, built on top of [Docker Compose](https://docs.docker.com/compose/), for easy deployment and rollback of dockerized applications.

Zodiac allows you to deploy Docker Compose applications while maintaining a history of all deployments. 
Among other things, this allows you to rollback to a previous, known-good deployment in the event that there are issues with your current build.

Imagine you have the following `docker-compose.yml` file

```
web:
  image: centurylink/simple-server
  ports:
    - "8888:8888"
```

Using Zodiac to deploy this application:

```
$ zodiac deploy
Deploying your application...
Creating zodiac_web_1
Successfully deployed 1 container(s)
```

View your deployment using the `list` command:

```
$ zodiac list
ACTIVE ID      DEPLOY DATE             SERVICES        MESSAGE
*      1       2015-06-30 00:40:27     zodiac_web_1
```

You changed your image and deploy again. The first deployment is retained:

```
$ zodiac list
ACTIVE ID      DEPLOY DATE             SERVICES        MESSAGE
*      2       2015-06-30 00:55:12     zodiac_web_1
       1       2015-06-30 00:40:27     zodiac_web_1
```

Rollback to the first deployment if needed:

```
$ zodiac rollback 1
Rolling back your application...
Creating zodiac_web_1
Successfully rolled back to deployment: 1
$ zodiac list
ACTIVE ID      DEPLOY DATE             SERVICES        MESSAGE
*      3       2015-06-30 00:56:09     zodiac_web_1    Rollback to: #1
       2       2015-06-30 00:55:12     zodiac_web_1
       1       2015-06-30 00:40:27     zodiac_web_1
```

## Installation

### Readying the remote environment
While Zodiac can be used just locally, we recommend pointing it at a remote environment. In that case Zodiac needs to be able to communicate with the docker daemon on that remote host. __We strongly encourage the use of Docker Machine__ for provisioning and installing Docker on the remote host. Zodiac is designed to work out of the box with a Machine-provisioned endpoint. However, one can also set `DOCKER_OPTS` manually on the remote host. Instructions for setting `DOCKER_OPTS` at runtime will vary by OS.



#### TLS
If you are going to use Zodiac to deploy to remote hosts you will want to ensure that your remote Docker daemon is protected with TLS security.
Zodiac ships with TLS support out of the box. Both host verification and client authentication are done via TLS.
TLS is enabled by default, though it may be disabled for debugging purposes, when using private networks, etc.

##### Configuring TLS

__NOTE:__ We assume you're using TLS by default, if not using TLS (strongly discouraged), you'll need to set `--tls=false`, or set the `DOCKER_TLS` envirnoment variable to false.

###### Let Docker Machine do all the heavy lifting
If you used Docker machine to provision Docker on the remote Host, it will have generated TLS certificates and keys for you on both the client and host machine.

You can use the `docker-machine env` command to automatically set-up the environment variables necessary for Zodiac to communicate with the remote host via TLS:

    eval "$(docker-machine env your_remote_name)"

If you do this, you should not need to use the `--endpoint` flag or any of the `--tls*` flags when running the Zodiac client.

###### OR Set up the certificates manually
If you choose to generate the TLS certificates manually, you'll want to genrate a certificate (be it self-signed or CA signed) for the host.
You'll also want to generate a client certificate for authentication purposes. Consult the Docker docs for [securing the Docker daemon](https://docs.docker.com/articles/https/).

Use the `zodiac help` command to see the options for passing in the necassary certificate files.






### Install the local Zodiac client
* Install [Docker Compose](http://docs.docker.com/compose/) **v1.[2-4]**. See: http://docs.docker.com/compose/
* Install the Zodiac Binary for your platform. See: https://github.com/CenturyLinkLabs/zodiac/releases/

or if you're a risk taker:

```
curl -sSL https://raw.githubusercontent.com/CenturyLinkLabs/zodiac/master/install.sh | bash
```

## Usage

The zodiac client supports the following commands:

* `verify` - verify that the target Docker endpoint is reachable and running a compatible version of the API.
* `deploy` - deploy the Docker Compose-defined application to the target Docker endpoint.
* `rollback` - roll to a previous Zodiac deployment.
* `list` - list all previous application deployments.
* `teardown` - remove running services and deployment history for the application.

**NOTE:** Zodiac stores all deployment history on the containers, so manually removing containers can destroy all Zodiac history.

### Global Options

The following flags apply to all of the Zodiac commands:

* `--endpoint` - Host and port for the target Docker endpoint. Should be in the form "tcp://hostname:port". Can optionally be provided by setting the `DOCKER_HOST` environment variable.
* `--tls` - Flag indicating whether or not to use TLS/SSL to communicate with the Docker daemon endpoint (defaults to *true*).
* `--tlsverify` - Flag indicating whether or not to perform TLS certificate authentication on the remote server's certificate (defaults to *true*). 
* `--tlscacert` - Path to the CA certificate which should be used to authenticate the remote server's certificate (defaults to *~/.docker/ca.pem*).
* `--tlscert` - Path to the certificate which should be used for client certificate authentication (defaults to *~/.docker/cert.pem*).
* `--tlskey` - Path to the private key which should be used for client certificate authentication (defaults to *~/.docker/key.pem*).
* `--debug` - Run the client in debug mode with verbose output.
* `--version` - Display version information for the Zodiac client.
* `--help` - Display the Zodiac client help text.

For more information about the various TLS flags, see the TLS section below.

## Remote Target Configuration

The remote Docker host must be exposed over a TCP port to enable remote communication from the local Zodiac CLI. This is typically done by setting DOCKER_OPTS to something like: `DOCKER_OPTS="-H tcp://0.0.0.0:2375 -H unix:///var/run/docker.sock"`. It's worth noting that Docker Machine will do this for you.

## Desired features / fixes
- [x] Support for compose's `build` option
- [ ] Support for compose's `volumes_from` option
- [ ] Support for private repos on the Docker hub
- [ ] Compose scale support

Imports 4 package(s)

  1. github.com/CenturyLinkLabs/zodiac/actions
  2. github.com/CenturyLinkLabs/zodiac/endpoint
  3. github.com/Sirupsen/logrus
  4. github.com/codegangsta/cli

Test imports 3 package(s)

  1. github.com/CenturyLinkLabs/clitest
  2. github.com/CenturyLinkLabs/zodiac/fakeengine
  3. github.com/stretchr/testify/assert