ufo 3.1.2 → 3.2.0

data/docs/_reference/ufo-task.md

@@ -0,0 +1,37 @@
+---
+title: ufo task
+reference: true
+---
+
+## Usage
+
+    ufo task TASK_DEFINITION
+
+## Description
+
+Run a one-time task.
+
+## Examples
+
+To run a one time task with ECS:
+
+    ufo task hi-migrate
+
+You can also override the command used by the Docker container in the task definitions via command.
+
+    ufo task hi-web --command bin/migrate
+    ufo task hi-web --command bin/with_env bundle exec rake db:migrate:redo VERSION=xxx
+
+
+## Options
+
+```
+[--docker], [--no-docker]    # Enable docker build and push
+                             # Default: true
+[--command=one two three]    # Override the command used for the container
+[--verbose], [--no-verbose]  
+[--mute], [--no-mute]        
+[--noop], [--no-noop]        
+[--cluster=CLUSTER]          # Cluster.  Overrides ufo/settings.yml.
+```
+

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

@@ -0,0 +1,179 @@
+---
+title: ufo tasks build
+reference: true
+---
+
+## Usage
+
+    ufo tasks build
+
+## Description
+
+Build task definitions.
+
+## Summarized Example
+
+    ufo tasks build
+
+Builds all the task defintiions. Note all the existing ufo/output generated task defintions are wiped out.
+
+## Explanation
+
+The command `ufo tasks build` generates the task definitions locally and writes them to the `output/` folder.  There are 2 files that it uses in order to produce the raw AWS task definitions files.
+
+1. ufo/templates/main.json.erb
+2. ufo/task_definitions.rb
+
+Here's an example of each of them:
+
+**main.json.erb**:
+
+    {
+        "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**:
+
+```ruby
+task_definition "hi-web" do
+    source "main" # will use ufo/templates/main.json.erb
+    variables(
+    family: task_definition_name,
+    name: "web",
+    container_port: helper.dockerfile_port,
+    command: ["bin/web"]
+  )
+end
+
+task_definition "hi-worker" do
+    source "main" # will use ufo/templates/main.json.erb
+    variables(
+    family: task_definition_name,
+    name: "worker",
+    command: ["bin/worker"]
+  )
+end
+
+task_definition "hi-clock" do
+    source "main" # will use ufo/templates/main.json.erb
+    variables(
+    family: task_definition_name,
+    name: "clock",
+    command: ["bin/clock"]
+  )
+end
+```
+
+The shared variables are set in the variables folder:
+
+**ufo/variables/base.rb**:
+
+```ruby
+@image = helper.full_image_name # includes the git sha tongueroo/hi:ufo-[sha].
+@cpu = 128
+@memory_reservation = 256
+@environment = helper.env_file(".env")
+```
+
+**ufo/variables/production.rb**:
+
+```ruby
+@environment = helper.env_vars(%Q{
+    RAILS_ENV=production
+    SECRET_KEY_BASE=secret
+})
+```
+
+Ufo combines the `main.json.erb` template, `task_definitions.rb` definitions, and variables in the `.ufo/variables` folder.  It then generates the raw AWS formatted task definition in the `output` folder.
+
+To build the task definitions:
+
+    ufo tasks build
+
+You should see output similar to below:
+
+    $ ufo tasks build
+    Building Task Definitions...
+    Generating Task Definitions:
+      ufo/output/hi-web.json
+      ufo/output/hi-worker.json
+      ufo/output/hi-clock.json
+    Task Definitions built in ufo/output.
+    $
+
+Let's take a look at one of the generated files: `.ufo/output/hi-web.json`.
+
+    {
+      "family": "hi-web",
+      "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
+        }
+      ]
+    }
+
+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.
+
+
+## Options
+
+```
+[--pretty], [--no-pretty]  # Pretty format the json for the task definitions
+                           # Default: true
+```
+

data/docs/_reference/ufo-tasks-help.md

@@ -0,0 +1,15 @@
+---
+title: ufo tasks help
+reference: true
+---
+
+## Usage
+
+    ufo tasks help [COMMAND]
+
+## Description
+
+Describe subcommands or one specific subcommand
+
+
+

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

@@ -0,0 +1,29 @@
+---
+title: ufo tasks register
+reference: true
+---
+
+## Usage
+
+    ufo tasks register
+
+## Description
+
+Register all built task definitions in `ufo/output` folder.
+
+The `ufo tasks register` command registers all the generated task definitions in `output/` to AWS ECS. Let's run it:
+
+    ufo tasks register
+
+You should see something similiar to this:
+
+    hi-clock task definition registered.
+    hi-web task definition registered.
+    hi-worker task definition registered.
+
+You can verify that the task definitions have been registered properly by viewing the AWS ECS Console Task Definitions page.  You should see something similar to this:
+
+<img src="/img/tutorials/ecs-console-task-definitions.png" class="doc-photo" />
+
+
+

data/docs/_reference/ufo-tasks.md

@@ -0,0 +1,35 @@
+---
+title: ufo tasks
+reference: true
+---
+
+## Usage
+
+    ufo tasks SUBCOMMAND
+
+## Description
+
+task definition subcommands
+
+## Examples
+
+    ufo tasks build
+
+Builds all the task defintiions.
+
+Note all the existing ufo/output generated task defintions are wiped out.
+
+## Subcommands
+
+* [ufo tasks build]({% link _reference/ufo-tasks-build.md %}) - Build task definitions.
+* [ufo tasks register]({% link _reference/ufo-tasks-register.md %}) - Register all built task definitions in `ufo/output` folder.
+
+## Options
+
+```
+[--verbose], [--no-verbose]  
+[--mute], [--no-mute]        
+[--noop], [--no-noop]        
+[--cluster=CLUSTER]          # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/_reference/ufo-upgrade3.md

@@ -0,0 +1,23 @@
+---
+title: ufo upgrade3
+reference: true
+---
+
+## Usage
+
+    ufo upgrade3
+
+## Description
+
+Upgrade from version 2 to 3.
+
+
+## Options
+
+```
+[--verbose], [--no-verbose]  
+[--mute], [--no-mute]        
+[--noop], [--no-noop]        
+[--cluster=CLUSTER]          # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/_reference/ufo-version.md

@@ -0,0 +1,23 @@
+---
+title: ufo version
+reference: true
+---
+
+## Usage
+
+    ufo version
+
+## Description
+
+Prints version number of installed ufo.
+
+
+## Options
+
+```
+[--verbose], [--no-verbose]  
+[--mute], [--no-mute]        
+[--noop], [--no-noop]        
+[--cluster=CLUSTER]          # Cluster.  Overrides ufo/settings.yml.
+```
+

data/docs/articles.md

@@ -6,3 +6,5 @@ title: Articles
 * This presentation covers ufo also: [Ufo Ship on AWS ECS](http://www.slideshare.net/tongueroo/ufo-ship-for-aws-ecs-70885296)
 
 <a id="prev" class="btn btn-basic" href="{% link _docs/next-steps.md %}">Back</a>
+<a id="next" class="btn btn-primary" href="{% link reference.md %}">Next Step</a>
+<p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>

data/docs/docs.md

@@ -2,7 +2,7 @@
 title: Docs
 ---
 
-### Overview
+## Overview
 
 Ufo is a tool that makes building and shipping Docker containers to AWS ECS super easy. Ufo provides a `ufo ship` command that does this. Essentially:
 
@@ -14,7 +14,7 @@ Ufo was built directly from real life production use cases after seeing the same
 
 Next we'll cover different ways to install ufo.
 
-<a id="prev" class="btn btn-basic" href="{% link quick-start.md %}">Back</a>
-<a id="next" class="btn btn-primary" href="{% link _docs/install.md %}">Next Step</a>
+<a id="prev" class="btn btn-basic" href="{% link _docs/tutorial-ufo-ships.md %}">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/quick-start.md

@@ -12,7 +12,7 @@ ufo init --app=hi --image=tongueroo/hi
 ufo ship hi-web
 ```
 
-### What Happened
+## What Happened
 
 The `ufo ship hi-web` command does the following:
 
@@ -49,6 +49,6 @@ Note: This quick start does require that you have a docker working on your envir
 
 Learn more in the next sections.
 
-<a id="next" class="btn btn-primary" href="{% link docs.md %}">Next Step</a>
+<a id="next" class="btn btn-primary" href="{% link _docs/install.md %}">Next Step</a>
 <p class="keyboard-tip">Pro tip: Use the <- and -> arrow keys to move back and forward.</p>
 

data/docs/reference.md

@@ -0,0 +1,18 @@
+---
+title: CLI Reference
+---
+{% include reference.md %}
+
+* [ufo completion]({% link _reference/ufo-completion.md %})
+* [ufo completion_script]({% link _reference/ufo-completion_script.md %})
+* [ufo deploy]({% link _reference/ufo-deploy.md %})
+* [ufo destroy]({% link _reference/ufo-destroy.md %})
+* [ufo docker]({% link _reference/ufo-docker.md %})
+* [ufo init]({% link _reference/ufo-init.md %})
+* [ufo scale]({% link _reference/ufo-scale.md %})
+* [ufo ship]({% link _reference/ufo-ship.md %})
+* [ufo ships]({% link _reference/ufo-ships.md %})
+* [ufo task]({% link _reference/ufo-task.md %})
+* [ufo tasks]({% link _reference/ufo-tasks.md %})
+* [ufo upgrade3]({% link _reference/ufo-upgrade3.md %})
+* [ufo version]({% link _reference/ufo-version.md %})

data/lib/ufo/cli.rb

@@ -8,11 +8,11 @@ module Ufo
     class_option :noop, type: :boolean
     class_option :cluster, desc: "Cluster.  Overrides ufo/settings.yml."
 
-    desc "docker SUBCOMMAND", "docker related tasks"
+    desc "docker SUBCOMMAND", "docker subcommands"
     long_desc Help.text(:docker)
     subcommand "docker", Docker
 
-    desc "tasks SUBCOMMAND", "task definition related tasks"
+    desc "tasks SUBCOMMAND", "task definition subcommands"
     long_desc Help.text(:tasks)
     subcommand "tasks", Tasks
 
@@ -20,7 +20,7 @@ module Ufo
     Init.cli_options.each do |args|
       option *args
     end
-    register(Init, "init", "new", "setup initial ufo files")
+    register(Init, "init", "new", "Set up initial ufo files.")
 
     # common options to deploy. ship, and ships command
     ship_options = Proc.new do
@@ -33,7 +33,7 @@ module Ufo
       option :ecr_keep, type: :numeric, desc: "ECR specific cleanup of old images.  Specifies how many images to keep.  Only runs if the images are ECR images. Defaults keeps all images."
     end
 
-    desc "deploy SERVICE", "deploys task definition to ECS service without re-building the definition"
+    desc "deploy SERVICE", "Deploy task definition to ECS service without re-building the definition."
     long_desc Help.text(:deploy)
     ship_options.call
     def deploy(service)
@@ -43,7 +43,7 @@ module Ufo
       ship.deploy
     end
 
-    desc "ship SERVICE", "builds and ships container image to the ECS service"
+    desc "ship SERVICE", "Builds and ships container image to the ECS service."
     long_desc Help.text(:ship)
     ship_options.call
     def ship(service)
@@ -57,7 +57,7 @@ module Ufo
       cleanup(builder.image_name)
     end
 
-    desc "ships [LIST_OF_SERVICES]", "builds and ships same container image to multiple ECS services"
+    desc "ships [LIST_OF_SERVICES]", "Builds and ships same container image to multiple ECS services."
     long_desc Help.text(:ships)
     ship_options.call
     def ships(*services)
@@ -74,7 +74,7 @@ module Ufo
       cleanup(builder.image_name)
     end
 
-    desc "task TASK_DEFINITION", "runs a one time task"
+    desc "task TASK_DEFINITION", "Run a one-time task."
     long_desc Help.text(:task)
     option :docker, type: :boolean, desc: "Enable docker build and push", default: true
     option :command, type: :array, desc: "Override the command used for the container"
@@ -84,7 +84,7 @@ module Ufo
       Task.new(task_definition, options).run
     end
 
-    desc "destroy SERVICE", "destroys the ECS service"
+    desc "destroy SERVICE", "Destroy the ECS service."
     long_desc Help.text(:destroy)
     option :sure, type: :boolean, desc: "By pass are you sure prompt."
     def destroy(service)
@@ -92,31 +92,31 @@ module Ufo
       Destroy.new(service, options).bye
     end
 
-    desc "scale SERVICE COUNT", "scale the ECS service"
+    desc "scale SERVICE COUNT", "Scale the ECS service."
     long_desc Help.text(:scale)
     def scale(service, count)
       Scale.new(service, count, options).update
     end
 
-    desc "completion *PARAMS", "prints words for auto-completion"
+    desc "completion *PARAMS", "Prints words for auto-completion."
     long_desc Help.text("completion")
     def completion(*params)
       Completer.new(CLI, *params).run
     end
 
-    desc "completion_script", "generates script that can be eval to setup auto-completion", hide: true
+    desc "completion_script", "Generates a script that can be eval to setup auto-completion.", hide: true
     long_desc Help.text("completion_script")
     def completion_script
       Completer::Script.generate
     end
 
-    desc "upgrade3", "upgrade from version 2 to 3"
+    desc "upgrade3", "Upgrade from version 2 to 3."
     long_desc Help.text("upgrade3")
     def upgrade3
       Upgrade3.new(options).run
     end
 
-    desc "version", "Prints version number of installed ufo"
+    desc "version", "Prints version number of installed ufo."
     def version
       puts VERSION
     end