ufo 3.1.2 → 3.2.0

data/docs/_includes/content.html

@@ -8,6 +8,11 @@
     <section id="main">
         <div class="container">
             <div class="row">
+                {% if page.reference %}
+                <div class="col-md-9 reference-nav">
+                    <a href="/reference">Back to Reference Index</a>
+                </div>
+                {% endif %}
                 <div class="col-md-9 content-body">
                     <h2>{{ page.title }}</h2>
                     {{ content }}

data/docs/_includes/css/main.css

@@ -9,11 +9,21 @@ body {
 }
 
 p {
-    font-size: 20px;
+    /*font-size: 20px;*/
+    font-size: 1.2em;
 }
 
 p.small {
-    font-size: 16px;
+    /*font-size: 16px;*/
+    font-size: 1em;
+}
+
+pre code {
+    font-size: 0.85em;
+}
+
+code {
+    font-size: 0.75em;
 }
 
 a,
@@ -31,7 +41,7 @@ h3,
 h4,
 h5,
 h6 {
-    text-transform: uppercase;
+    /*text-transform: uppercase;*/
     font-family: Montserrat,"Helvetica Neue",Helvetica,Arial,sans-serif;
     font-weight: 700;
 }
@@ -201,7 +211,11 @@ section {
 section h2 {
     margin: 0;
     margin-bottom: 15px;
-    font-size: 2em;
+    font-size: 1.6em;
+}
+
+section h3 {
+    font-size: 1.4em;
 }
 
 section.success {
@@ -479,3 +493,8 @@ footer .footer-below {
     transform: translateZ(0);
     -webkit-transform: translateZ(0);
 }
+
+.reference-nav {
+    margin-bottom: 20px;
+}
+

data/docs/_includes/css/ufo.css

@@ -1,10 +1,10 @@
 ol.overview-stages li {
-    font-size: 1.1em;
+    /*font-size: 1.1em;*/
     padding: 10px 0;
 }
 
 section#main {
-    text-align: center;
+    /*text-align: center;*/
     color: #fff;
     background: #{{ site.color.primary }};
 }
@@ -23,12 +23,12 @@ section#main .intro-text .name {
     display: block;
     text-transform: uppercase;
     font-family: Montserrat,"Helvetica Neue",Helvetica,Arial,sans-serif;
-    font-size: 2em;
+    /*font-size: 2em;*/
     font-weight: 700;
 }
 
 section#main .intro-text .skills {
-    font-size: 1.25em;
+    /*font-size: 1.25em;*/
     font-weight: 300;
 }
 
@@ -43,11 +43,11 @@ section#main .intro-text .skills {
     }
 
     section#main .intro-text .name {
-        font-size: 4.75em;
+        /*font-size: 4.75em;*/
     }
 
     section#main .intro-text .skills {
-        font-size: 1.75em;
+        /*font-size: 1.75em;*/
     }
 }
 
@@ -56,7 +56,7 @@ section#main .intro-text .skills {
 }
 
 .content-body h2 {
-    text-align: center;
+    /*text-align: center;*/
 }
 
 .content-body ul,
@@ -71,7 +71,7 @@ section#main .intro-text .skills {
 .content-nav {
     /*background-color: green;*/
     margin-top: 40px;
-    font-size: 1.25em;
+    font-size: 1.2em;
 }
 
 .content-nav ul, .content-nav ol {
@@ -166,7 +166,7 @@ table.ship-options td:first-child {
 }
 
 #summary {
-    font-size: 18px;
+    /*font-size: 18px;*/
     padding-bottom: 0;
     margin-bottom: 0;
 }

data/docs/_includes/reference.md

@@ -0,0 +1,5 @@
+Easy Way to Build and Ship Docker Images to AWS ECS.  The main command is ufo ship. Here's summary of what it does:
+
+1. Builds a docker image.
+2. Registers the ECS template definition.
+3. Deploys to ECS.

data/docs/_includes/subnav.html

@@ -1,12 +1,7 @@
 <div class="col-md-3 content-nav">
     <ul>
         <li><a href="{% link quick-start.md %}">Quick Start</a></li>
-        <li><a href="{% link docs.md %}">Docs</a>
-            <ul>
-                <li><a href="{% link _docs/install.md %}">Installation</a></li>
-                <li><a href="{% link _docs/structure.md %}">Structure</a></li>
-            </ul>
-        </li>
+        <li><a href="{% link _docs/install.md %}">Installation</a></li>
         <li><a href="{% link _docs/tutorial.md %}">Tutorial</a>
             <ul class="tutorial">
                 <li><a href="{% link _docs/tutorial-ufo-init.md %}">Setup Ufo</a></li>
@@ -16,35 +11,23 @@
                 <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>
+        <li><a href="{% link docs.md %}">Docs</a>
             <ul>
-                <li><a href="{% link _docs/ufo-init.md %}">ufo init</a></li>
-                <li><a href="{% link _docs/ufo-ship.md %}">ufo ship</a></li>
-                <li><a href="{% link _docs/ufo-ships.md %}">ufo ships</a></li>
-                <li><a href="{% link _docs/ufo-deploy.md %}">ufo deploy</a></li>
-                <li><a href="{% link _docs/ufo-scale.md %}">ufo scale</a></li>
-                <li><a href="{% link _docs/ufo-destroy.md %}">ufo destroy</a></li>
-                <li><a href="{% link _docs/ufo-docker-build.md %}">ufo docker build</a></li>
-                <li><a href="{% link _docs/ufo-docker-push.md %}">ufo docker push</a></li>
-                <li><a href="{% link _docs/ufo-docker-base.md %}">ufo docker base</a></li>
-                <li><a href="{% link _docs/ufo-docker-name.md %}">ufo docker name</a></li>
-                <li><a href="{% link _docs/ufo-docker-clean.md %}">ufo docker clean</a></li>
-                <li><a href="{% link _docs/ufo-tasks-build.md %}">ufo tasks build</a></li>
-                <li><a href="{% link _docs/ufo-tasks-register.md %}">ufo tasks register</a></li>
-                <li><a href="{% link _docs/ufo-help.md %}">ufo help</a></li>
+                <li><a href="{% link _docs/structure.md %}">Structure</a></li>
+                <li><a href="{% link _docs/settings.md %}">Settings</a></li>
+                <li><a href="{% link _docs/ufo-env.md %}">UFO_ENV</a></li>
+                <li><a href="{% link _docs/variables.md %}">Shared Variables</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/auto-completion.md %}">Auto-Completion</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>
+                <li><a href="{% link reference.md %}">Reference</a></li>
             </ul>
         </li>
-        <li><a href="{% link _docs/settings.md %}">Settings</a></li>
-        <li><a href="{% link _docs/ufo-env.md %}">UFO_ENV</a></li>
-        <li><a href="{% link _docs/variables.md %}">Shared Variables</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/auto-completion.md %}">Auto-Completion</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>
 </div>

data/docs/_reference/ufo-completion.md

@@ -0,0 +1,46 @@
+---
+title: ufo completion
+reference: true
+---
+
+## Usage
+
+    ufo completion *PARAMS
+
+## Description
+
+Prints words for auto-completion.
+
+Example:
+
+    ufo completion
+
+Prints words for TAB auto-completion.
+
+## Examples
+
+    ufo completion
+    ufo completion hello
+    ufo completion hello name
+
+To enable, TAB auto-completion add the following to your profile:
+
+    eval $(ufo completion_script)
+
+Auto-completion example usage:
+
+    ufo [TAB]
+    ufo hello [TAB]
+    ufo hello name [TAB]
+    ufo hello name --[TAB]
+
+
+## Options
+
+```
+[--verbose], [--no-verbose]  
+[--mute], [--no-mute]        
+[--noop], [--no-noop]        
+[--cluster=CLUSTER]          # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/_reference/ufo-completion_script.md

@@ -0,0 +1,27 @@
+---
+title: ufo completion_script
+reference: true
+---
+
+## Usage
+
+    ufo completion_script
+
+## Description
+
+Generates a script that can be eval to setup auto-completion.
+
+To use, add the following to your ~/.bashrc or ~/.profile
+
+    eval $(ufo completion_script)
+
+
+## Options
+
+```
+[--verbose], [--no-verbose]  
+[--mute], [--no-mute]        
+[--noop], [--no-noop]        
+[--cluster=CLUSTER]          # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/_reference/ufo-deploy.md

@@ -0,0 +1,51 @@
+---
+title: ufo deploy
+reference: true
+---
+
+## Usage
+
+    ufo deploy SERVICE
+
+## Description
+
+Deploy task definition to ECS service without re-building the definition.
+
+It is useful to sometimes deploy only the task definition without re-building it.  Say for example, you are debugging the task definition and just want to directly edit the `.ufo/output/hi-web.json` definition. You can accomplish this with the `ufo deploy` command.  The `ufo deploy` command will deploy the task definition in `.ufo/output` unmodified.  Example:
+
+    ufo deploy hi-web
+
+The above command does the following:
+
+1. register the `.ufo/output/hi-web.json` task definition to ECS untouched.
+2. deploys it to ECS by updating the service
+
+The `ufo deploy` command does less than the `ufo ship` command.  Typically, people use `ufo ship` over the `ufo deploy` command do everything in one step:
+
+1. build the Docker image
+2. register the ECS task definition
+3. update the ECS service
+
+The `ufo ships`, `ufo ship`, `ufo deploy` command support the same options. The options are presented here again for convenience:
+
+{% include ufo-ship-options.md %}
+
+
+## Options
+
+```
+[--task=TASK]                                        # ECS task name, to override the task name convention.
+[--target-group=TARGET_GROUP]                        # ELB Target Group ARN.
+[--target-group-prompt], [--no-target-group-prompt]  # Enable Target Group ARN prompt
+                                                     # Default: true
+[--wait], [--no-wait]                                # Wait for deployment to complete
+[--pretty], [--no-pretty]                            # Pretty format the json for the task definitions
+                                                     # Default: true
+[--stop-old-tasks], [--no-stop-old-tasks]            # Stop old tasks after waiting for deploying to complete
+[--ecr-keep=N]                                       # ECR specific cleanup of old images.  Specifies how many images to keep.  Only runs if the images are ECR images. Defaults keeps all images.
+[--verbose], [--no-verbose]                          
+[--mute], [--no-mute]                                
+[--noop], [--no-noop]                                
+[--cluster=CLUSTER]                                  # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/_reference/ufo-destroy.md

@@ -0,0 +1,34 @@
+---
+title: ufo destroy
+reference: true
+---
+
+## Usage
+
+    ufo destroy SERVICE
+
+## Description
+
+Destroy the ECS service.
+
+## Examples
+
+Ufo provides a quick way to destroy an ECS service. To destroy an ECS service, you must make sure that the desired number of tasks is first set to 0. It is easy to forget 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 destroys the service.  Ufo also prompts you before destroying the service.
+
+    ufo destroy hi-web
+
+If you would like to bypass the prompt, you can use the `--sure` option.
+
+    ufo destroy hi-web --sure
+
+
+## Options
+
+```
+[--sure], [--no-sure]        # By pass are you sure prompt.
+[--verbose], [--no-verbose]  
+[--mute], [--no-mute]        
+[--noop], [--no-noop]        
+[--cluster=CLUSTER]          # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/{_docs → _reference}/ufo-docker-base.md

@@ -1,8 +1,27 @@
 ---
 title: ufo docker base
+reference: true
 ---
 
-### Concept
+## Usage
+
+    ufo docker base
+
+## Description
+
+Build docker image from `Dockerfile.base` and update current `Dockerfile`.
+
+The docker cache task builds a docker image using the `Dockerfile.base` file and
+updates the FROM `Dockerfile` image with the generated image from `Dockerfile.base`.
+
+## Summarized Example
+
+    ufo docker base
+    ufo docker base --no-push # do not push the image to the registry
+
+Docker image `tongueroo/hi:base-2016-10-21T15-50-57-88071f5` built.
+
+## 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.
 
@@ -10,33 +29,33 @@ The `ufo docker base` commands allows you to build an Docker image from `Dockerf
 
 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 rebuilds the base Docker image at least nightly.
 
-### Demo
+## 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
-```
+    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 .
-```
+    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 forgetting to copying and pasting it the `Dockerfile` yourself.
 
-<a id="prev" class="btn btn-basic" href="{% link _docs/ufo-docker-push.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>
+
+## Options
+
+```
+[--push], [--no-push]  
+                       # Default: true
+```
 

data/docs/_reference/ufo-docker-build.md

@@ -0,0 +1,81 @@
+---
+title: ufo docker build
+reference: true
+---
+
+## Usage
+
+    ufo docker build
+
+## Description
+
+Build docker image.
+
+The `ufo docker build` builds a Docker image using the Dockerfile in the current project folder.  This simply is 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:
+
+    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):
+
+    $ 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.
+
+    ufo docker build --push
+
+You should see it being pushed at the end:
+
+    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 registry 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.
+
+
+## Options
+
+```
+[--push], [--no-push]  
+```
+