ufo 1.6.1 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a6388da22b6c5411a782d28977800302d9b38a58
-  data.tar.gz: 99c104ba7d80919fbe87781072b0945fe93ca0db
+  metadata.gz: 719240a41b0030380ceb747403c3fb272120a9be
+  data.tar.gz: 8238a183e5602cc44f7681091a9bb823541f3ec5
 SHA512:
-  metadata.gz: 62494d932d9451f1c613f886f27f2802b2ed0fcfc092084ab610e48fb1731fabfd6aea7a3431a4ace9c32bbf76bb99dbce848acf8ec79dfb40c7b4ccfc802618
-  data.tar.gz: 925dc53383349eecac49c37c967ff1bf8c2942db9d61c4a335a41bc3fc9580393c2bbf85cffd80dd413d05695ba7b7620572b4ea2c3fdcadb5cc5d07916f92bf
+  metadata.gz: 5aa712d256743f80d959653230cfc4f5542ff98aa315ea33012c4e93ac4810206dee120ac39c9c4b26c5ce0957e5d6126915813d46e153405d36684c8004d003
+  data.tar.gz: 9e4707e07e52225a45f378a8f358d8033de2b39298b1014d03ebbd2b941ee157789ab28c8286dea1b77994e71a6f7dffb1ca4db5c974113443649080cc016f91

data/CHANGELOG.md

@@ -3,6 +3,11 @@
 All notable changes to this project will be documented in this file.
 This project *tries* to adhere to [Semantic Versioning](http://semver.org/), even before v1.0.
 
+## [1.6.2]
+* update bin/deploy starter project script
+* update help menu
+* update docs
+
 ## [1.6.1]
 * exit if docker push fails
 

data/README.md

@@ -1,291 +1,56 @@
-# Ufo - A Easy Way to Build and Ship Docker Images to AWS ECS
+# Ufo - Easy Way to Build and Ship Docker to AWS ECS
 
 [![CircleCI](https://circleci.com/gh/tongueroo/ufo.svg?style=svg)](https://circleci.com/gh/tongueroo/ufo)
 
-## Quick Introduction
+Ufo is a tool that makes building and shipping Docker images to [AWS ECS](https://aws.amazon.com/ecs/) super easy.
 
-Ufo is a simple tool that makes building and shipping Docker containers to [AWS ECS](https://aws.amazon.com/ecs/) super easy.
-
-* This blog post provides an introduction to the tool: [Ufo - Build Docker Containers and Ship Them to AWS ECS](https://medium.com/@tongueroo/ufo-easily-build-docker-containers-and-ship-them-to-aws-ecs-15556a2b39f#.qqu8o4wal).
-* This presentation covers ufo also: [Ufo Ship on AWS ECS](http://www.slideshare.net/tongueroo/ufo-ship-for-aws-ecs-70885296)
-
-A summary of what `ufo ship` does:
+The main command is `ufo ship`.  Here's summary of what it does:
 
 1. Builds a docker image. 
 2. Generates and registers the ECS template definition. 
-3. Deploys the ECS template definition to the specified service.
+3. Deploys the ECS template definition to the ECS service.
 
-Ufo deploys a task definition that is created via a template generator which is fully controllable.
+Ufo deploys a task definition that is written in a templating language that is easily and fully controllable.
 
+See [ufoships.com](http://ufoships.com) for full documentation.
 
 ## Installation
 
-    $ gem install ufo
-
-### Dependencies
-
-* Docker: You will need a working version of [Docker](https://docs.docker.com/engine/installation/) installed as ufo shells out and calls the `docker` command.
-* AWS: Set up your AWS credentials at `~/.aws/credentials` and `~/.aws/config`.  This is the [AWS standard way of setting up credentials](https://aws.amazon.com/blogs/security/a-new-and-standardized-way-to-manage-credentials-in-the-aws-sdks/).
-
-## Quick Usage
-
-### ufo ship
-
-To execute the ship process run:
-
-```bash
-ufo ship hi-web-prod --cluster mycluster
-```
-
-Note, if you have configured `ufo/settings.yml` to map hi-web-prod to the `mycluster` cluster using the service_cluster option the command becomes simply:
-
-```bash
-ufo ship hi-web-prod
-```
-
-When you run `ufo ship hi-web-prod`:
-
-1. It builds the docker image.
-2. Generates a task definition and registers it.
-3. Updates the ECS service to use it.
-
-If the ECS service hi-web-prod does not yet exist, ufo will create the service for you.
-
-By convention, if the service has a container name web, you'll get prompted to create an ELB and specify a target group arn.  The ELB and target group must already exist.
-
-You can bypass the prompt and specify the target group arn as part of the command.  The elb target group can only be associated when the service gets created for the first time.  If the service already exists then the `--target-group` parameter just gets ignored and the ECS task simply gets updated.  Example:
-
-
-```bash
-ufo ship hi-web-prod --target-group=arn:aws:elasticloadbalancing:us-east-1:12345689:targetgroup/hi-web-prod/12345
-```
-
-When using ufo if the ECS service does not yet exist, it will automatically be created for you.  Ufo will also automatically create the ECS cluster. If you are relying on this tool to create the cluster, you still need to associate ECS Container Instances to the cluster yourself.
-
-## Detailed Usage
-
-First initialize ufo files within your project.  Let's say you have an example `hi` app.
-
-```
-$ git clone https://github.com/tongueroo/hi
-$ cd hi
-$ ufo init --app hi --cluster stag --image tongueroo/hi
-Setting up ufo project...
-created: ./bin/deploy
-exists: ./Dockerfile
-created: ./ufo/settings.yml
-created: ./ufo/task_definitions.rb
-created: ./ufo/templates/main.json.erb
-created: ./.env
-Starter ufo files created.
-$
-```
-
-Take a look at the `ufo/settings.yml` file and notice that it contains some default configuration settings so you do not have to type out these options repeatedly for some of the ufo commands.
-
-```yaml
-image: tongueroo/hi
-service_cluster:
-  default: prod # default cluster
-  hi-web-prod: blue
-  hi-clock-prod: blue
-  hi-worker-prod: blue
-```
-
-The `image` value is the name that ufo will use for the Docker image name.
-
-The `service_cluster` mapping provides a way to set default service-to-cluster mappings so that you do not have to specify the `--cluster` repeatedly.  This is very helpful. For example:
-
-```
-ufo ship hi-web-prod --cluster hi-cluster
-ufo ship hi-web-prod # same as above because it is configured in ufo/settings.yml
-ufo ship hi-web-prod --cluster special-cluster # overrides the default setting in `ufo/settings.yml`.
-```
-
-### Task Definition ERB Template and DSL Generator
-
-Ufo task definitions are written as an ERB template that makes it every easily accessible and configurable to your requirements.  Here is is an example of an ERB template `ufo/templates/main.json.erb` that shows how easy it is to modfied the task definition you want to be uploaded by ufo:
-
-```json
-{
-    "family": "<%= @family %>",
-    "containerDefinitions": [
-        {
-            "name": "<%= @name %>",
-            "image": "<%= @image %>",
-            "cpu": <%= @cpu %>,
-            <% if @memory %>
-            "memory": <%= @memory %>,
-            <% end %>
-            <% if @memory_reservation %>
-            "memoryReservation": <%= @memory_reservation %>,
-            <% end %>
-            <% if @container_port %>
-            "portMappings": [
-                {
-                    "containerPort": "<%= @container_port %>",
-                    "protocol": "tcp"
-                }
-            ],
-            <% end %>
-            "command": <%= @command.to_json %>,
-            <% if @environment %>
-            "environment": <%= @environment.to_json %>,
-            <% end %>
-            <% if @awslogs_group %>
-            "logConfiguration": {
-                "logDriver": "awslogs",
-                "options": {
-                    "awslogs-group": "<%= @awslogs_group %>",
-                    "awslogs-region": "<%= @awslogs_region || 'us-east-1' %>",
-                    "awslogs-stream-prefix": "<%= @awslogs_stream_prefix %>"
-                }
-            },
-            <% end %>
-            "essential": true
-        }
-    ]
-}
-```
-
-The instance variable values are specified in `ufo/task_definitions.rb` via a DSL.  Here's the
-
-
-```ruby
-task_definition "hi-web-prod" do
-  source "main" # will use ufo/templates/main.json.erb
-  variables(
-    family: task_definition_name,
-    # image: tongueroo/hi:ufo-[timestamp]=[sha]
-    image: helper.full_image_name,
-    environment: helper.env_file('.env.prod')
-    name: "web",
-    container_port: helper.dockerfile_port,
-    command: ["bin/web"]
-  )
-end
-```
-
-The task\_definitions.rb file has some special variables and helper methods available. These helper methods provide useful contextual information about the project. For example, one of the variable provides the exposed port in the Dockerfile of the project. This why if someone changes the exported port in the Dockerfile, he will not "forgot" to also update the ufo variable as it is automatically referenced. Here is a list of the important helpers:
+If you want to quickly install ufo without having to worry about ufo’s dependencies you can simply install the Bolts Toolbelt which has ufo included.
 
-* **helper.full\_image\_name** — The full docker image name that ufo builds. The “base” portion of the docker image name is defined in ufo/settings.yml. For example, the base portion is `tongueroo/hi` and the full image name is `tongueroo/hi:ufo-[timestamp]-[sha]`. The base name does not include the generated Docker tag, which contains a timestamp and git sha of the Dockerfile that is used.
-* **helper.dockerfile\_port** — Exposed port extracted from the Dockerfile of the project. 
-* **helper.env_vars(text)** — This method takes a block of text that contains the env values in key=value format and converts that block of text to the proper task definition json format.
-* **helper.env_file(path)** — This method takes an `.env` file which contains a simple key value list of environment variables and converts the list to the proper task definition json format.
-
-The 2 classes which provide these special helper methods are in [ufo/dsl.rb](https://github.com/tongueroo/ufo/blob/master/lib/ufo/dsl.rb) and [ufo/dsl/helper.rb](https://github.com/tongueroo/ufo/blob/master/lib/ufo/dsl/helper.rb). Refer to these classes for the full list of the special variables and methods.
-
-### Shipping Multiple Services with bin/deploy
-
-A common pattern is to have 3 processes: web, worker, and clock.  This is very common in rails applcations. The web process handles web traffic, the worker process handles background job processing that would be too slow and potentially block web requests, and a clock process is typically used to schedule recurring jobs. These processes use the same codebase, or same docker image, but have slightly different run time settings.  For example, the docker run command for a web process could be [puma](http://puma.io/) and the command for a worker process could be [sidekiq](http://sidekiq.org/).  Environment variables are sometimes different also.  The important key is that the same docker image is used for all 3 services but the task definition for each service is different.
-
-This is easily accomplished with the `bin/deploy` wrapper script that the `ufo init` command initially generates.  The starter script example shows you how you can use ufo to generate one docker image and use the same image to deploy to all 3 services.  Here is an example `bin/deploy` script:
-
-```bash
-#!/bin/bash -xe
-
-ufo ship hi-worker-prod --cluster prod --no-wait
-ufo ship hi-clock-prod --cluster prod --no-wait --no-docker
-ufo ship hi-web-prod --cluster prod --no-docker
+```sh
+brew cask install boltopslabs/software/bolts
 ```
 
-The first `ufo ship hi-worker-prod` command build and ships docker image to ECS, but the following two `ufo ship` commands use the `--no-docker` flag to skip the `docker build` step.  `ufo ship` will use the last built docker image as the image to be shipped.  For those curious, this is stored in `ufo/docker_image_name_ufo.txt`.
+Or if you prefer you can install ufo with RubyGems
 
-### Service and Task Names Convention
-
-Ufo assumes a convention that service\_name and the task\_name are the same.  If you would like to override this convention then you can specify the task name.
-
-```
-ufo ship hi-web-prod --task my-task
+```sh
+gem install ufo
 ```
 
-This means that in the task_definition.rb you will also defined it with `my-task`.  For example:
-
-```ruby
-task_definition "my-task" do
-  source "web" # this corresponds to the file in "ufo/templates/web.json.erb"
-  variables(
-    family: "my-task",
-    ....
-  )
-end
-
-```
+Full installation instructions are at [Install Ufo](http://ufoships.com/docs/install/).
 
-### Running Tasks in Pieces
+## Quick Start
 
-The `ufo ship` command goes through a few stages: building the docker image, registering the task defiintions and updating the ECS service.  The CLI exposes each of the steps as separate commands.  Here is now you would be able to run each of the steps in pieces.
+To quickly demonstrate how simple it is to use ufo we will use an example app from [tongueroo/hi](https://github.com/tongueroo/ufo).  The app is a barebones sinatra app.  Here are the steps:
 
-Build the docker image first.
-
-```bash
-ufo docker build
-ufo docker build --push # will also push to the docker registry
-```
-
-Build the task definitions.
-
-```bash
-ufo tasks build
-ufo tasks register # will register all genreated task definitinos in the ufo/output folder
+```sh
+brew cask install boltopslabs/software/bolts
+git clone https:///github.com/tongueroo/hi.git
+cd hi
+ufo init --app=hi --env stag --cluster=stag --image=tongueroo/hi
+ufo ship hi-web-stag
 ```
 
-Skips all the build docker phases of a deploy sequence and only update the service with the task definitions.
-
-```bash
-ufo ship hi-web-prod --no-docker
-```
-Note if you use the `--no-docker` option you should ensure that you have already push a docker image to your docker register.  Or else the task will not be able to spin up because the docker image does not exist.  I recommend that you normally use `ufo ship` most of the time.
-
-
-### Automated Docker Images Clean Up
-
-Ufo can be configured to automatically clean old images from the ECR registry after the deploy completes.  I normally set `~/.ufo/settings.yml` like so:
-
-```yaml
-ecr_keep: 30
-```
+Congratulations, you have successfully used ufo to deploy to an ECS service.
 
-Automated Docker images clean up only works if you are using ECR registry.
 
-## Running a single task
+## Articles
 
-Sometimes you do not want to run a long running `service` but a one time task. Running Rails migrations are a good example of a one off task.  Here is an example of how you would run a one time task.
-
-```
-ufo task hi-migrate-prod
-```
-
-You will need to define a task definition for the migrate command also in `ufo/task_definitions.rb`.  If you only need to override the Docker command and can re-use an existing task definition like `hi-web-prod`.  You can use the `--command` option:
-
-```
-ufo task hi-web-prod --command bin/migrate
-ufo task hi-web-prod --command bin/with_env bundle exec rake db:migrate:redo VERSION=xxx
-```
-
-The `--command` option takes a string. If the string has brackets in it then it will be evaluated as an Array but the option must be a string.
-
-## Scale
-
-There is a convenience wrapper that simple executes `aws ecs update-service --service [SERVICE] --desired-count [COUNT]`
-
-```
-ufo scale hi-web 1
-```
-
-## Destroy
-
-To scale down the service and destroy it:
-
-```
-ufo destroy hi-web
-```
+* This blog post provides an introduction to the tool: [Ufo - Build Docker Containers and Ship Them to AWS ECS](https://medium.com/@tongueroo/ufo-easily-build-docker-containers-and-ship-them-to-aws-ecs-15556a2b39f#.qqu8o4wal).
+* This presentation covers ufo also: [Ufo Ship on AWS ECS](http://www.slideshare.net/tongueroo/ufo-ship-for-aws-ecs-70885296)
 
-### More Help
 
-```
-ufo help
-```
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/tongueroo/ufo/issues](https://github.com/tongueroo/ufo/issues).

data/docs/_docs/automated-cleanup.md

@@ -0,0 +1,15 @@
+---
+title: Automated Clean Up
+---
+
+Ufo can be configured to automatically clean old images from the ECR registry after the deploy completes by configuring the your [settings.yml] file like so:
+
+```yaml
+ecr_keep: 30
+```
+
+Automated Docker images clean up only works if you are using ECR registry.
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/migrations.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/next-steps.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/conventions.md

@@ -6,7 +6,7 @@ Ufo uses a set of naming conventions.  This helps enforce some best practices an
 
 ### Service and Task Names Convention
 
-The main convention is that the ECS service and task definition name are the same by default.   If you would like to override this convention then you can specify the task name.
+Ufo assumes a convention that service\_name and the task\_name are the same. If you would like to override this convention then you can specify the task name.
 
 ```
 ufo ship hi-web-prod --task my-task
@@ -39,7 +39,6 @@ You can also bypass the prompt by specifying the target group arn as part of the
 ufo ship hi-web-prod --target-group=arn:aws:elasticloadbalancing:us-east-1:12345689:targetgroup/hi-web-prod/12345
 ```
 
-<a id="prev" class="btn btn-basic" href="{% link _docs/ufo-settings.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link _docs/next-steps.md %}">Next Step</a>
+<a id="prev" class="btn btn-basic" href="{% link _docs/helpers.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/run-in-pieces.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
-

data/docs/_docs/helpers.md

@@ -0,0 +1,22 @@
+---
+title: Helpers
+---
+
+The task\_definitions.rb file has access to special variables and helper methods available. These helper methods provide useful contextual information about the project.
+
+For example, one of the variable provides the exposed port in the Dockerfile of the project. This is useful if someone changes the exported port in the Dockerfile, he likely to forget to also update the ufo variable so it is referenced via the helper. Here is a list of the important helpers:
+
+Helper  | Description
+------------- | -------------
+full\_image\_name | The full docker image name that ufo builds. The "base" portion of the docker image name is defined in ufo/settings.yml. For example, the base portion is `tongueroo/hi` and the full image name is `tongueroo/hi:ufo-[timestamp]-[sha]`. The base name does not include the generated Docker tag, which contains a timestamp and git sha of the Dockerfile that is used.
+dockerfile\_port | Exposed port extracted from the Dockerfile of the project. 
+env_vars(text) | This method takes a block of text that contains the env values in key=value format and converts that block of text to the proper task definition json format.
+env_file(path) | This method takes an `.env` file which contains a simple key value list of environment variables and converts the list to the proper task definition json format.
+
+To call the helper in task_definitions.rb you must add `helper.` in front.  So full\_image\_name  is called via `helper.full_image_name`.
+
+The 2 classes which provide these special helper methods are in [ufo/dsl.rb](https://github.com/tongueroo/ufo/blob/master/lib/ufo/dsl.rb) and [ufo/dsl/helper.rb](https://github.com/tongueroo/ufo/blob/master/lib/ufo/dsl/helper.rb). Refer to these classes for the full list of the special variables and methods.
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/settings.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/conventions.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/install.md

@@ -4,7 +4,7 @@ title: Installation
 
 ### Install with Bolts Toolbelt
 
-If you want to quickly install ufo without having to worry about ufo's dependency you can simply install the Bolts Toolbelt which has ufo included.
+If you want to quickly install ufo without having to worry about ufo's dependencies you can simply install the Bolts Toolbelt which has ufo included.
 
 ```sh
 brew cask install boltopslabs/software/bolts
@@ -26,6 +26,11 @@ Or you can add ufo to your Gemfile in your project if you are working with a rub
 gem "ufo"
 {% endhighlight %}
 
+### Dependencies
+
+* Docker: You will need a working version of [Docker](https://docs.docker.com/engine/installation/) installed as ufo shells out and calls the `docker` command.
+* AWS: Set up your AWS credentials at `~/.aws/credentials` and `~/.aws/config`.  This is the [AWS standard way of setting up credentials](https://aws.amazon.com/blogs/security/a-new-and-standardized-way-to-manage-credentials-in-the-aws-sdks/).
+
 <a id="prev" class="btn btn-basic" href="/docs/">Back</a>
 <a id="next" class="btn btn-primary" href="{% link _docs/structure.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/migrations.md

@@ -0,0 +1,32 @@
+---
+title: Database Migrations
+---
+
+A common task is to run database migrations with newer code before deploying the actual code. This is easily achieved with the `ufo task` command. Here's an example:
+
+```sh
+ufo task hi-web-prod --command bundle exec rake db:migrate
+```
+
+It nice to wrap the commands in a wrapper script in case you have to do things like the load the environment.
+
+```sh
+ufo task hi-web-prod --command bin/migrate
+```
+
+The `bin/migrate` script can look like this:
+
+```bash
+#!/bin/bash
+bundle exec rake db:migrate
+```
+
+The `ufo task` command is generalized so you can actually run any one-off task. It is not just limited to running migrations. The `ufo task` command performs the following:
+
+1. Builds the docker image and pushes it to a registry
+2. Registers the ECS Task definition
+3. Runs an one-off ECS Task
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/single-task.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/automated-cleanup.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/next-steps.md

@@ -12,7 +12,7 @@ From here, there are a few resources that can help you continue along:
 
 Everyone can contribute to make ufo better, including the documentation. These docs are of the same ufo repo in the [docs folder](https://github.com/tongueroo/ufo/tree/master/docs). Please fork the project and open a pull request!  We love your pull requests. Contributions are encouraged and welcomed!
 
-<a id="prev" class="btn btn-basic" href="{% link _docs/conventions.md %}">Back</a>
+<a id="prev" class="btn btn-basic" href="{% link _docs/automated-cleanup.md %}">Back</a>
 <a id="next" class="btn btn-primary" href="{% link articles.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
 

data/docs/_docs/run-in-pieces.md

@@ -0,0 +1,30 @@
+---
+title: Run in Pieces
+---
+
+The `ufo ship` command goes through a few stages: building the docker image, registering the task defiintions and updating the ECS service.  The CLI exposes each of the steps as separate commands.  Here is now you would be able to run each of the steps in pieces.
+
+Build the docker image first.
+
+```bash
+ufo docker build
+ufo docker build --push # will also push to the docker registry
+```
+
+Build the task definitions.
+
+```bash
+ufo tasks build
+ufo tasks register # will register all genreated task definitinos in the ufo/output folder
+```
+
+Skips all the build docker phases of a deploy sequence and only update the service with the task definitions.
+
+```bash
+ufo ship hi-web-prod --no-docker
+```
+Note if you use the `--no-docker` option you should ensure that you have already push a docker image to your docker registry.  Or else the task will not be able to spin up because the docker image does not exist.  It is normally recommended that you normally use `ufo ship`.
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/conventions.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/single-task.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/{ufo-settings.md → settings.md}

@@ -52,6 +52,6 @@ docker_keep: 30
 ```
 
 <a id="prev" class="btn btn-basic" href="{% link _docs/ufo-help.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link _docs/conventions.md %}">Next Step</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/helpers.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
 

data/docs/_docs/single-task.md

@@ -0,0 +1,29 @@
+---
+title: Run Single Task
+---
+
+Sometimes you do not want to run a long running `service` but a one time task. Running Rails migrations are a good example of a one off task.  Here is an example of how you would run a one time task.
+
+```
+ufo task hi-web-prod --command bundle exec rake db:migrate
+```
+
+At the end of the output you should see you the task ARN:
+
+```sh
+$ ufo task hi-web-prod --command bundle exec rake db:migrate
+...
+Running task_definition: hi-web-prod
+Task ARN: arn:aws:ecs:us-west-2:994926937775:task/a0e4229d-3d39-4b26-9151-6ab6869b84d4
+$
+```
+
+You can describe that task for more details:
+
+```sh
+aws ecs describe-tasks --tasks arn:aws:ecs:us-west-2:994926937775:task/a0e4229d-3d39-4b26-9151-6ab6869b84d4
+```
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/run-in-pieces.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/migrations.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/tutorial-ufo-docker-build.md

@@ -1,8 +1,8 @@
 ---
-title: ufo docker build
+title: Build Docker
 ---
 
-### Step 1 - Build the Docker Image
+### Build the Docker Image
 
 Let's use the `ufo docker build` command to build the docker image. The command uses the `Dockerfile` in the current project to build the docker image.  You use your own Dockerfile so you have fully control over how you would like the image to be built.  For this tutorial we will continue to use the [tongueroo/hi](https://github.com/tongueroo/hi) app and it's Dockerfile. Let's run the command:
 

data/docs/_docs/tutorial-ufo-init.md

@@ -1,5 +1,5 @@
 ---
-title: ufo init
+title: Setup Ufo
 ---
 
 The easiest way to create this ufo folder is by using the `ufo init` command.  For this tutorial we'll [tongueroo/hi](https://github.com/tongueroo/hi) which is a small test sinatra app.
@@ -15,7 +15,7 @@ You should see output similiar to this:
 
 <img src="/img/tutorials/ufo-init.png" class="doc-photo" />
 
-The standard directory structure of the ufo folder looks like this:
+The `ufo init` command generated a few starter ufo files for you. The standard directory structure of the ufo folder looks like this:
 
 ```sh
 ufo
@@ -28,6 +28,31 @@ ufo
 
 The explanation of the folders and files were covered in detailed earlier at [Structure]({% link _docs/structure.md %}).
 
+### Settings
+
+Take a look at the `ufo/settings.yml` file and notice that it contains some default configuration settings so you do not have to type out these options repeatedly for some of the ufo commands.
+
+```yaml
+image: tongueroo/hi
+service_cluster:
+  default: stag # default cluster
+  # can override the default cluster for each service.  CLI overrides all of these settings.
+  hi-web-stag:
+  hi-clock-stag:
+  hi-worker-stag:
+```
+
+The `image` value is the name that ufo will use as a base to generate a Docker image name.
+
+The `service_cluster` mapping provides a way to set default service-to-cluster mappings so that you do not have to specify the `--cluster` repeatedly.  This is very helpful. For example:
+
+```
+ufo ship hi-web-stag --cluster hi-cluster
+ufo ship hi-web-stag # same as above because it is configured in ufo/settings.yml
+ufo ship hi-web-stag --cluster special-cluster # overrides the default setting in `ufo/settings.yml`.
+```
+
+
 <a id="prev" class="btn btn-basic" href="{% link _docs/tutorial.md %}">Back</a>
 <a id="next" class="btn btn-primary" href="{% link _docs/tutorial-ufo-docker-build.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/_docs/tutorial-ufo-ship.md

@@ -1,11 +1,38 @@
 ---
-title: ufo ship
+title: Deploy One App
 ---
 
 ### Step 3 - Ship the Code to ECS
 
 In this guide we have walked through what ufo does step by step.  First ufo builds the Docker image with `ufo docker build`.  Then it will build and register the ECS task definitions with the `ufo tasks` commands. Now we'll deploy the code to ECS.
 
+```sh
+ufo ship hi-web-stag --cluster stag
+```
+
+Note, when we ran `ufo init` earlier, it configured `ufo/settings.yml` to map hi-web-stag to the `stag` cluster with the service_cluster option.  This nicely simplifies the command to
+
+```bash
+ufo ship hi-web-stag
+```
+
+When you run `ufo ship hi-web-stag`:
+
+1. It builds the docker image.
+2. Generates a task definition and registers it.
+3. Updates the ECS service to use it.
+
+If the ECS service hi-web-stag does not yet exist, ufo will create the service for you. Ufo will also automatically create the ECS cluster. If you are relying on this tool to create the cluster, you still need to associate ECS Container Instances to the cluster yourself.
+
+By convention, if the service has a container name web, you'll get prompted to create an ELB and specify a target group arn.  The ELB and target group must already exist. You can bypass the prompt and specify the target group ARN as part of the ship command or with the `--no-target-group-prompt` option.  The elb target group only gets associated with the ECS service if the service is being created for the first time.  If the service already exists then the `--target-group` parameter just gets ignored and the ECS task simply gets updated.  Example:
+
+
+```bash
+ufo ship hi-web-stag --target-group=arn:aws:elasticloadbalancing:us-east-1:12345689:targetgroup/hi-web-stag/12345
+```
+
+Let's go back to the original command and take a look at the output:
+
 ```sh
 ufo ship hi-web-stag
 ```
@@ -36,6 +63,8 @@ Checking the ECS console you should see something like this:
 
 <img src="/img/tutorials/ecs-console-ufo-ship.png" class="doc-photo" />
 
+You have successfully shipped a docker image to ECS! 🍾🥂
+
 ### Skipping Previous Steps
 
 The `ufo ship` command will automatically calls the steps we called manually in the previous pages: `ufo build` and `ufo tasks`.

data/docs/_docs/tutorial-ufo-ships.md

@@ -1,8 +1,12 @@
 ---
-title: ufo ships
+title: Deploy Multiple Apps
 ---
 
-You might have noticed in in the tutorial that the starter ufo folder that `ufo init` generates creates 3 task definitions for 3 services for a web, worker and clock role.  We can use the same `ufo ship` command to deploy to all 3 service roles like so:
+You might have noticed in in the tutorial that the generated starter ufo folder contains 3 task definitions a web, worker and clock role.  This is a common pattern.  The web process handles web traffic, the worker process handles background job processing that would be too slow and potentially block web requests, and a clock process is typically used to schedule recurring jobs.
+
+These processes use the same codebase and same docker image, but have slightly different run time settings.  The docker run command for a web process could be [puma](http://puma.io/) and the command for a worker process could be [sidekiq](http://sidekiq.org/).  Environment variables are also sometimes different.  The important key is that the same docker image is used for all 3 services but the task definition for each service is slightly different.
+
+While we can use the `ufo ship` command to deploy to all 3 service roles individually like so:
 
 ```sh
 ufo ship hi-web-stag
@@ -10,7 +14,7 @@ ufo ship hi-worker-stag
 ufo ship hi-clock-stag
 ```
 
-This will build Docker image and register task definition each time the command gets run.  It is a common pattern to actually want have the same code base running on all of these roles.  In this case, we want to use the *same* Docker image and *same* task definition for all 3 roles.  Ufo provides a `ufo ships` command for this exact situation.
+This would build a new Docker image for each process.  We actually want have the same docker image running on all of these roles.  In this case where we want to use the *same* Docker image for all 3 roles, ufo provides a `ufo ships` command.
 
 ### ufo ships
 
@@ -22,7 +26,12 @@ You can check on the ECS console and should see something similar to this:
 
 <img src="/img/tutorials/ecs-console-ufo-ships.png" class="doc-photo" />
 
+You can shorten the command by taking advantage of shell expansion:
+
+```sh
+ufo ships hi-{web,worker,clock}-stag
+```
+
 <a id="prev" class="btn btn-basic" href="{% link _docs/tutorial-ufo-ship.md %}">Back</a>
 <a id="next" class="btn btn-primary" href="{% link _docs/commands.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
-

data/docs/_docs/tutorial-ufo-tasks-build.md

@@ -1,16 +1,18 @@
 ---
-title: ufo tasks build
+title: Task Definitions
 ---
 
-### Step 2a - Build the ECS Task Definitions
+### Build the ECS Task Definitions
 
-Now that we have a docker image pushed to a registry we can use that image for ECS.  Ufo takes that image and adds it to an ECS task definition.  This is where ufo makes building and controlling your ECS task definition super powerful.
+Now that we have a docker image pushed to a registry we can use that image for ECS.  Ufo takes that image and adds it to an ECS task definition.  This is where ufo is super powerful.  Ufo gives you the power to build and control your ECS task definition easily.
 
 Let's take a look at the 2 files that are used by ufo to build the the ECS task definition.  These files were generated by the `ufo init` command at the beginning.
 
 1. ufo/templates/main.json.erb
 2. ufo/task_definitions.rb
 
+Ufo task definitions are written as an ERB template that makes it every easily accessible and configurable to your requirements.  Here is is an example of an ERB template `ufo/templates/main.json.erb` that shows how easy it is to modfied the task definition you want to be uploaded by ufo:
+
 **main.json.erb**:
 
 ```json
@@ -55,6 +57,8 @@ Let's take a look at the 2 files that are used by ufo to build the the ECS task
 }
 ```
 
+The instance variable values are specified in `ufo/task_definitions.rb` via a DSL.  Here's the file:
+
 **task_definitions.rb**:
 
 ```
@@ -100,7 +104,11 @@ task_definition "hi-clock-stag" do
 end
 ```
 
-Ufo uses the ERB template in `main.json.erb` and combines it with the variables defined in the task definition declarations in `task_definitions.rb` and generates the raw AWS formatted task definition in the `output` folder.  In this case there are 3 task_definitions so there will be 3 generated output files. If you need to modify the task definition template to suite your own needs it is super simple, just edit `main.json.erb`.  No need to dive deep into internal code that builds up the task definition with some internal structure.  It is all there for you to fully control.
+Ufo uses the ERB template in `main.json.erb` and combines it with the variables defined in the task definition declarations in `task_definitions.rb` and generates the raw AWS formatted task definition in the `output` folder.  In this case there are 3 task_definitions so there will be 3 generated output files.
+
+If you need to modify the task definition template to suite your own needs it is super simple, just edit `main.json.erb`.  You do not have to dive deep into internal code somewhere.  It is all there for you to fully control.
+
+The task_definition.rb has access to some useful helper methods detailed in [Helpers]({% link _docs/helpers.md %}).
 
 Let's build the task definitions:
 
@@ -144,12 +152,12 @@ Let's take a look at one of the generated files: `ufo/output/hi-web-stag.json`.
 }
 ```
 
-### Step 2b Register the ECS Task Definitions
+### Register the ECS Task Definitions
 
 You have built the ecs task definitions locally on your machine. To register the task definitions in output run this command:
 
 ```sh
-ufo ecs register
+ufo tasks register
 ```
 
 You should see something similiar to this:

data/docs/_docs/ufo-destroy.md

@@ -17,4 +17,3 @@ ufo destroy hi-web-stag --sure
 <a id="prev" class="btn btn-basic" href="{% link _docs/ufo-scale.md %}">Back</a>
 <a id="next" class="btn btn-primary" href="{% link _docs/ufo-docker-build.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
-

data/docs/_docs/ufo-help.md

@@ -17,6 +17,6 @@ ufo ships -h
 ```
 
 <a id="prev" class="btn btn-basic" href="{% link _docs/ufo-tasks-register.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link _docs/ufo-settings.md %}">Next Step</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/settings.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
 

data/docs/_docs/ufo-scale.md

@@ -20,3 +20,4 @@ While scaling via this method is quick and convenient the [ECS Service AutoScali
 <a id="next" class="btn btn-primary" href="{% link _docs/ufo-destroy.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
 
+

data/docs/_docs/ufo-tasks-register.md

@@ -5,7 +5,7 @@ title: ufo tasks register
 The `ufo tasks register` command registers all the generated task definitions in `output/` to AWS ECS. Let's run it:
 
 ```sh
-ufo ecs register
+ufo tasks register
 ```
 
 You should see something similiar to this:

data/docs/_includes/contact.html

@@ -10,7 +10,7 @@
         <div class="row">
             <div class="col-lg-12 text-center">
                 <div id="success"></div>
-                <a href="{% link quick-start.md %}" class="btn btn-primary btn-xl">Quick Start</a>
+                <a id="next" href="{% link quick-start.md %}" class="btn btn-primary btn-xl">Quick Start</a>
             </div>
         </div>
     </div>

data/docs/_includes/footer.html

@@ -6,8 +6,9 @@
                     <div class="footer-col col-md-4">
                         <h3>More Tools</h3>
                         <ul class="list-unstyled tools">
+                            <li><a href="http://sonic-screwdriver.cloud">Sonic Screwdriver</a></li>
                             <li><a href="http://lono.cloud">Lono</a></li>
-                            <li><a href="http://jackandtheelasticbeanstalk.com">Jack</a></li>
+                            <li><a href="http://jack-eb.com">Jack</a></li>
                             <li><a href="https://boltops.com/toolbelt">Toolbelt</a></li>
                         </ul>
                     </div>

data/docs/_includes/subnav.html

@@ -13,7 +13,7 @@
                 <li><a href="{% link _docs/tutorial-ufo-docker-build.md %}">Build Docker</a></li>
                 <li><a href="{% link _docs/tutorial-ufo-tasks-build.md %}">Task Definitions</a></li>
                 <li><a href="{% link _docs/tutorial-ufo-ship.md %}">Deploy One App</a></li>
-                <li><a href="{% link _docs/tutorial-ufo-ships.md %}">Deploy Apps</a></li>
+                <li><a href="{% link _docs/tutorial-ufo-ships.md %}">Deploy Multiple Apps</a></li>
             </ul>
         </li>
         <li><a href="{% link _docs/commands.md %}">Commands</a>
@@ -32,8 +32,13 @@
                 <li><a href="{% link _docs/ufo-help.md %}">ufo help</a></li>
             </ul>
         </li>
-        <li><a href="{% link _docs/ufo-settings.md %}">Settings</a></li>
+        <li><a href="{% link _docs/settings.md %}">Settings</a></li>
+        <li><a href="{% link _docs/helpers.md %}">Helpers</a></li>
         <li><a href="{% link _docs/conventions.md %}">Conventions</a></li>
+        <li><a href="{% link _docs/run-in-pieces.md %}">Run In Pieces</a></li>
+        <li><a href="{% link _docs/single-task.md %}">Run Single Task</a></li>
+        <li><a href="{% link _docs/migrations.md %}">Database Migrations</a></li>
+        <li><a href="{% link _docs/automated-cleanup.md %}">Automated Cleanup</a></li>
         <li><a href="{% link _docs/next-steps.md %}">Next Steps</a></li>
         <li><a href="{% link articles.md %}">Articles</a></li>
     </ul>

data/docs/_includes/ufo-ship-options.md

@@ -10,4 +10,4 @@ Option  | Description
 `--pretty`  | This boolean option determines ufo generates the task definitions in output in a pretty human readable format.
 `--stop-old-tasks`  | This boolean option determines if ufo will call ecs stop-task on the old tasks after deployment. Sometimes old tasks hang around for a little bit with ECS this forces them along a little quicker.
 `--ecr-keep`  | This integer option determines how many old docker images to keep around.  Ufo will automatically delete and clean up docker images at the end of this process. The default is reasonable large at 30.
-`--cluster`  | This decides what cluster to use.  This can also be set in ufo/settings.yml covered in [Settings]({% link _docs/ufo-settings.md %}).  The cli option takes highest precedence.
+`--cluster`  | This decides what cluster to use.  This can also be set in ufo/settings.yml covered in [Settings]({% link _docs/settings.md %}).  The cli option takes highest precedence.

data/docs/quick-start.md

@@ -9,7 +9,7 @@ brew cask install boltopslabs/software/bolts
 git clone https:///github.com/tongueroo/hi.git
 cd hi
 ufo init --app=hi --env stag --cluster=stag --image=tongueroo/hi
-ufo ship
+ufo ship hi-web-stag
 ```
 
 You should see something similar to this:

data/lib/starter_project/bin/deploy

@@ -3,10 +3,5 @@
 # Generated started bin/deploy script.  Meant to be example only and should probably
 # be overridden.
 
-# Only build docker image on with the first command.
-ufo ship <%= @app %>-clock --cluster <%= @cluster %> --no-wait
-# Skipping the docker build phase for the rest of the ship commands
-ufo ship <%= @app %>-worker --cluster <%= @cluster %> --no-wait --no-docker
-# The final service will wait for the deploy to finish.  Please specify an
-# Application Load Balancer if creating the service for the first time.
-ufo ship <%= @app %>-web --cluster <%= @cluster %> --no-docker
+# Only build one docker image and deploys it to multiple ECS services
+ufo ships <%= @app %>-{web,clock,worker}-<%= @env %> --cluster <%= @cluster %>

data/lib/starter_project/ufo/settings.yml

@@ -5,6 +5,6 @@ image: <%= @image %>
 service_cluster:
   default: <%= @cluster %> # default cluster
   # can override the default cluster for each service.  CLI overrides all of these settings.
-  <%= @app %>-web-prod:
-  <%= @app %>-clock-prod:
-  <%= @app %>-worker-prod:
+  <%= @app %>-web-<%= @env %>:
+  <%= @app %>-clock-<%= @env %>:
+  <%= @app %>-worker-<%= @env %>:

data/lib/ufo/cli/help.rb

@@ -6,7 +6,7 @@ module Ufo
 <<-EOL
 Examples:
 
-$ ufo init --cluster prod --image tongueroo/hi --app hi
+$ ufo init --app=hi --env stag --cluster=stag --image=tongueroo/hi
 
 The image should not include the tag since the tag is generated upon a `ufo ship`.
 EOL

data/lib/ufo/version.rb

@@ -1,3 +1,3 @@
 module Ufo
-  VERSION = "1.6.1"
+  VERSION = "1.6.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ufo
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.6.2
 platform: ruby
 authors:
 - Tung Nguyen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-13 00:00:00.000000000 Z
+date: 2017-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -175,10 +175,16 @@ files:
 - docs/LICENSE
 - docs/README.md
 - docs/_config.yml
+- docs/_docs/automated-cleanup.md
 - docs/_docs/commands.md
 - docs/_docs/conventions.md
+- docs/_docs/helpers.md
 - docs/_docs/install.md
+- docs/_docs/migrations.md
 - docs/_docs/next-steps.md
+- docs/_docs/run-in-pieces.md
+- docs/_docs/settings.md
+- docs/_docs/single-task.md
 - docs/_docs/structure.md
 - docs/_docs/tutorial-ufo-docker-build.md
 - docs/_docs/tutorial-ufo-init.md
@@ -194,7 +200,6 @@ files:
 - docs/_docs/ufo-help.md
 - docs/_docs/ufo-init.md
 - docs/_docs/ufo-scale.md
-- docs/_docs/ufo-settings.md
 - docs/_docs/ufo-ship.md
 - docs/_docs/ufo-ships.md
 - docs/_docs/ufo-tasks-build.md