ufo 1.5.0 → 1.6.0

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

@@ -0,0 +1,28 @@
+---
+title: ufo ships
+---
+
+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:
+
+```sh
+ufo ship hi-web-stag
+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.
+
+### ufo ships
+
+```sh
+ufo ships hi-web-stag hi-worker-stag hi-clock-stag
+```
+
+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" />
+
+<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

@@ -0,0 +1,166 @@
+---
+title: ufo tasks build
+---
+
+### Step 2a - 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.
+
+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
+
+**main.json.erb**:
+
+```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
+        }
+    ]
+}
+```
+
+**task_definitions.rb**:
+
+```
+# common variables
+common = {
+  image: helper.full_image_name, # includes the git sha tongueroo/hi:ufo-[sha].
+  cpu: 128,
+  memory_reservation: 256,
+  environment: helper.env_file(".env")
+  # another example
+  # environment: helper.env_vars(%Q{
+  #   RAILS_ENV=production
+  #   SECRET_KEY_BASE=secret
+  # })
+}
+
+task_definition "hi-web-stag" do
+  source "main" # will use ufo/templates/main.json.erb
+  variables(common.dup.deep_merge(
+    family: task_definition_name,
+    name: "web",
+    container_port: helper.dockerfile_port,
+    command: ["bin/web"]
+  ))
+end
+
+task_definition "hi-worker-stag" do
+  source "main" # will use ufo/templates/main.json.erb
+  variables(common.dup.deep_merge(
+    family: task_definition_name,
+    name: "worker",
+    command: ["bin/worker"]
+  ))
+end
+
+task_definition "hi-clock-stag" do
+  source "main" # will use ufo/templates/main.json.erb
+  variables(common.dup.deep_merge(
+    family: task_definition_name,
+    name: "clock",
+    command: ["bin/clock"]
+  ))
+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.
+
+Let's build the task definitions:
+
+```sh
+ufo tasks build
+```
+
+You should see output similar to below:
+
+<img src="/img/tutorials/ufo-tasks-build.png" class="doc-photo" />
+
+Let's take a look at one of the generated files: `ufo/output/hi-web-stag.json`.
+
+```json
+{
+  "family": "hi-web-stag",
+  "containerDefinitions": [
+    {
+      "name": "web",
+      "image": "tongueroo/hi:ufo-2017-06-11T22-22-32-a18aa30",
+      "cpu": 128,
+      "memoryReservation": 256,
+      "portMappings": [
+        {
+          "containerPort": "3000",
+          "protocol": "tcp"
+        }
+      ],
+      "command": [
+        "bin/web"
+      ],
+      "environment": [
+        {
+          "name": "RAILS_ENV",
+          "value": "staging"
+        }
+      ],
+      "essential": true
+    }
+  ]
+}
+```
+
+### Step 2b 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
+```
+
+You should see something similiar to this:
+
+```sh
+hi-clock-stag task definition registered.
+hi-web-stag task definition registered.
+hi-worker-stag task definition registered.
+```
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/tutorial-ufo-docker-build.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/tutorial-ufo-ship.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.md

@@ -0,0 +1,15 @@
+---
+title: Tutorial
+---
+
+In the next sections, we'll walk through using ufo in detail. We will ufo-ify a project. Then we'll go through the step by step process that ufo automated.  Normally ufo is not really used in step like fashion like in this tutorial, but going through it step by step really helps to understand how ufo works.  Here are the steps we'll go through:
+
+1. We'll build a docker image by using `ufo docker`.
+2. We'll build and register the task definitions to ECS with the newly built docker images with `ufo tasks`
+3. Finally, we'll use `ufo ship` to run through entire process.
+
+Let's start!
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/structure.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/tutorial-ufo-init.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-destroy.md

@@ -0,0 +1,20 @@
+---
+title: ufo destroy
+---
+
+Ufo provides a quick way to destroy an ECS service. In order to destroy an ECS service you must makes sure that the desired number of tasks is first set to 0. It is easy to forgot to do this and waste time. So as part of destroying the service ufo will scale the ECS service down to 0 automatically first and then destroy the service.  Ufo also prompts you before destroying the service.
+
+```
+ufo destroy hi-web-stag
+```
+
+If you would like to bypass the prompt you can use the `--sure` option.
+
+```
+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-docker-base.md

@@ -0,0 +1,42 @@
+---
+title: ufo docker base
+---
+
+### Concept
+
+Docker is fantastic and has given developers more power and control over the OS their application runs on.  Sometimes building Docker images can be slow though.  Docker layer caching technology helps immensely to speed up the process as Docker will only rebuild layers that require rebuilding. But sometimes one little dependency changes it results in having to rebuild many layers.
+
+The `ufo docker base` commands allows you to build an Docker image from `Dockerfile.base` to be used as a cache and in the FROM instruction in the main `Dockerfile`.  This base Docker cache image technique speeds up development substantially if you have dependencies like gems in your project.  Let's say you have 20 gems in your project and are actively developing your project. You are experimenting with 3 different gems, adding and removing them while you are investigating the best gem to use.  Without the Docker image cache that already has all of your other gems installed each time you adjust `Gemfile` it would have to wait until all the gems from scratch again installed again.
+
+There are pros and cons of using this approach.  Remember there are 2 hard problems in computer science: 1. Naming and 2. Caching.  The main con about this approach is if you forget to update the base Docker image you will have cached artifacts that will not disappear unless you rebuild the base Docker image.  While some folks are completely against introducing this cache layer, some have found it being a huge win in speeding up their Docker development workflow.  If you are using this technique it is recommended that you set up some automation that at the very least nightly rebuilds the base Docker image.
+
+### Demo
+
+To demonstrate this command, there's a `docker-cache` branch in the [tongueroo/hi](https://github.com/tongueroo/hi/tree/docker-cache) repo.
+
+ Let's see the command in action:
+
+```sh
+ufo docker base
+Building docker image with:
+  docker build -t tongueroo/hi:base-2017-06-12T14-36-44-2af505e -f Dockerfile.base .
+  ...
+Pushed tongueroo/hi:base-2017-06-12T14-36-44-2af505e docker image. Took 28s.
+The Dockerfile FROM statement has been updated with the latest base image:
+  tongueroo/hi:base-2017-06-12T14-36-44-2af505e
+```
+
+Some of the output has been excluded so we can focus on the important parts to point out. First notice that the commmand simply shells out to the docker command and calls:
+
+```sh
+docker build -t tongueroo/hi:base-2017-06-12T14-36-44-2af505e -f Dockerfile.base .
+```
+
+It is using the docker `-f Dockerfile.base` option to build the base image.  It names the image with `tongueroo/hi:base-2017-06-12T14-36-44-2af505e`.  The image tag contains useful information: the timestamp when the image was built and the exact git sha of the code.  The image gets push to a registry immediately.
+
+Notice at the very end, the *current* `Dockerfile`'s FROM statement has been updated with the newly built base Docker image automatically.  This saves you from forgettig to copying and pasting it the `Dockerfile` yourself.
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/ufo-docker-build.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/ufo-docker-name.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-docker-build.md

@@ -0,0 +1,79 @@
+---
+title: ufo docker build
+---
+
+The `ufo docker build` builds a Docker image using the Dockerfile in the current project folder.  This simply a wrapper command that shells out and calls the `docker` command.  We're use the [tongueroo/hi]((https://github.com/tongueroo/hi) project and it's Dockerfile for demonstration.  Example:
+
+```sh
+ufo docker build
+```
+
+You'll see that it calls:
+
+```
+docker build -t tongueroo/hi:ufo-2017-06-11T22-18-03-a18aa30 -f Dockerfile .
+```
+
+You should see similar output (some of the output has been truncated for conciseness):
+
+```sh
+$ ufo docker build
+Building docker image with:
+  docker build -t tongueroo/hi:ufo-2017-06-11T22-18-03-a18aa30 -f Dockerfile .
+Sending build context to Docker daemon 734.2 kB
+Step 1 : FROM ruby:2.3.3
+ ---> 0e1db669d557
+Step 2 : RUN apt-get update &&   apt-get install -y     build-essential     nodejs &&   rm -rf /var/lib/apt/lists/* && apt-get clean && apt-get purge
+ ---> Using cache
+ ---> 931ace833716
+...
+Step 7 : ADD . /app
+ ---> fae2452e6c35
+Removing intermediate container 4c93f92a7fd8
+Step 8 : RUN bundle install --system
+ ---> Running in f851b9cb7d27
+Using rake 12.0.0
+Using i18n 0.8.1
+...
+Using web-console 2.3.0
+Bundle complete! 12 Gemfile dependencies, 56 gems now installed.
+Bundled gems are installed into /usr/local/bundle.
+ ---> 194830c5c1a8
+...
+Removing intermediate container 67545cd4cd09
+Step 11 : CMD bin/web
+ ---> Running in b1b26e68d957
+ ---> 8547bb48b21f
+Removing intermediate container b1b26e68d957
+Successfully built 8547bb48b21f
+Docker image tongueroo/hi:ufo-2017-06-11T22-18-03-a18aa30 built.  Took 33s.
+$
+```
+
+The docker image tag that is generated contains a useful timestamp and the current HEAD git sha of the project that you are on.
+
+By default when you are running `ufo docker build` directly it does not push the docker image to the registry.  If you would like it to automaticaly push the built image to a registry at the end of the build use the `--push` flag.
+
+```sh
+ufo docker build --push
+```
+
+You should see it being pushed at the end:
+
+```sh
+Docker image tongueroo/hi:ufo-2017-06-11T22-22-32-a18aa30 built.  Took 34s.
+The push refers to a repository [docker.io/tongueroo/hi]
+ef375857f165: Pushed
+4d791d7cde66: Pushed
+277ff31e79b4: Layer already exists
+a361a4de05df: Layer already exists
+ufo-2017-06-11T22-22-32-a18aa30: digest: sha256:c5385a5084e87643bd943eb120e110321c59e8acd30736ba7b5223eb1143baa8 size: 3464
+Pushed tongueroo/hi:ufo-2017-06-11T22-22-32-a18aa30 docker image. Took 9s.
+```
+
+Note in order to push the image to a register you will need to login into the registry.  If you are using DockerHub use the `docker login` command.  If you are using AWS ECR then you can use the `aws ecr get-login` command.
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/ufo-destroy.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/ufo-docker-base.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-docker-clean.md

@@ -0,0 +1,27 @@
+---
+title: ufo docker clean
+---
+
+Ufo comes with a handy command to clean up old images that ufo generates. Ufo only deletes images from the docker daemon and does not remove any images from any registry.  To use it you pass the base portion of the image name to the command. Example:
+
+```sh
+ufo docker clean tongueroo/hi
+```
+
+Here is some example output of the commmand:
+
+```sh
+Cleaning up docker images...
+Running: docker rmi tongueroo/hi:ufo-2017-06-12T12-14-22-a18aa30 tongueroo/hi:ufo-2017-06-12T12-12-05-a18aa30
+```
+
+By default the clean command keeps the most 3 recent docker images. If you would like to override this setting you can use the `--keep` option. Example:
+
+```sh
+ufo docker clean tongueroo/hi --keep 5
+```
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/ufo-docker-name.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/ufo-tasks-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-docker-name.md

@@ -0,0 +1,15 @@
+---
+title: ufo docker name
+---
+
+It is sometimes handy to grab the name of the Docker image that was just generated.  Let's say ou needed the image name so you can feed it into another script that you have. The command `ufo docker name` returns the image of the most recently built Docker image. Example:
+
+```sh
+$ ufo docker image
+tongueroo/hi:ufo-2017-06-12T12-34-48-a18aa30
+```
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/ufo-docker-base.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/ufo-docker-clean.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

@@ -0,0 +1,22 @@
+---
+title: ufo help
+---
+
+You can run help for quick help information right at the cli.  Example:
+
+```sh
+ufo help
+```
+
+You can append `help`, `-h` or `--help` to the end of any command to get more help information about that specific command.  These all work.
+
+```sh
+ufo docker build help
+ufo ship --help
+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>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
+

data/docs/_docs/ufo-init.md

@@ -0,0 +1,37 @@
+---
+title: ufo init
+---
+
+The `ufo init` command provides a way to quickly setup a project to be ufo ready. It creates a ufo with all the starter supporting files in order to use ufo.  This page demonstrates how to use `ufo init`.  The command has a few required options `--app`, `--env`, `--cluster`, and `--image`.
+
+For this example we will use [tongueroo/hi](https://github.com/tongueroo/hi) which is a small test sinatra app.
+
+Let's run the command in our newly clone project.
+
+```sh
+git clone https://github.com/tongueroo/hi.git
+cd hi
+ufo init --app=hi --env stag --cluster=stag --image=tongueroo/hi
+```
+
+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:
+
+```sh
+ufo
+├── output
+├── settings.yml
+├── task_definitions.rb
+└── templates
+    └── main.json.erb
+```
+
+The explanation of the folders and files were covered in detailed earlier at [Structure]({% link _docs/structure.md %}).
+
+<a id="prev" class="btn btn-basic" href="{% link _docs/commands.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/ufo-ship.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
+