Merge branch 'master' of github.com:acquia/moonshot

README.md

@@ -1,21 +1,40 @@
-# Moonshot [![Documentation Status](https://readthedocs.org/projects/moonshot/badge/?version=latest)](http://moonshot.readthedocs.org/en/latest/?badge=latest)[![Build Status](https://travis-ci.org/acquia/moonshot.svg?branch=master)](https://travis-ci.org/acquia/moonshot)[![Test Coverage](https://codeclimate.com/github/acquia/moonshot/badges/coverage.svg)](https://codeclimate.com/github/acquia/moonshot/coverage)[![Code Climate](https://codeclimate.com/github/acquia/moonshot/badges/gpa.svg)](https://codeclimate.com/github/acquia/moonshot)
+# <img src="docs/logo.png" width="48"> Moonshot [![Documentation Status](https://readthedocs.org/projects/moonshot/badge/?version=latest)](http://moonshot.readthedocs.org/en/latest/?badge=latest)[![Build Status](https://travis-ci.org/acquia/moonshot.svg?branch=master)](https://travis-ci.org/acquia/moonshot)[![Test Coverage](https://codeclimate.com/github/acquia/moonshot/badges/coverage.svg)](https://codeclimate.com/github/acquia/moonshot/coverage)[![Code Climate](https://codeclimate.com/github/acquia/moonshot/badges/gpa.svg)](https://codeclimate.com/github/acquia/moonshot)[![Gem Version](https://badge.fury.io/rb/moonshot.svg)](https://badge.fury.io/rb/moonshot)
 _Because releasing services shouldn't be a moonshot._
 
-Moonshot is a tool for provisioning infrastructure and applications in AWS with CloudFormation and CodeDeploy using a CLI. Its main goal is to make it possible to control the deployment in a programmable and extensible way so that there is less room for human errors in the AWS console when creating and updating cloudformation templates but also deploying new software using CodeDeploy.
+## Overview
 
-![General Flow](docs/moonshot.png "General Flow")
+[We also have pretty docs, lots more to find there.](http://moonshot.readthedocs.org/en/latest/)
 
-The software is relying on a single CloudFormation stack and supported by pluggable systems:
+Moonshot is a Ruby gem for provisioning environments in AWS using a CLI.
+The environments are centered around a single CloudFormation stack and supported
+by pluggable systems:
 
 - A DeploymentMechanism controls releasing code.
 - A BuildMechanism creates a release artifact.
 - A ArtifactRepository stores the release artifacts.
 
-You can read [nicely formatted documentation][1] on how Moonshot works and how to extend it. We also want to [help you contribute and answer all your questions][2] on how Moonshot is maintained.
+![General Flow](docs/moonshot.png "General Flow")
+
+## Design Goals
+
+These are core ideas to the creation of this project. Not all are met to the
+level we'd like (e.g. CloudFormation isn't much of a Choice currently), but we
+should aspire to meet them with each iteration.
+
+- Simplicity: It shouldn't take more than a few hours to understand what your
+  release tooling does.
+- Choice: As much as possible, each component should be pluggable and omittable,
+  so teams are free to use what works best for them.
+- Verbosity: The output of core Moonshot code should explain in detail what
+  changes are being made, so knowledge is shared and not abstracted.
+
+## Existing limitations
+
+- Moonshot does not support detailed error logging from Cloudformation substacks.
+- Moonshot does not support a non-local cloudformation file.
 
-## Super Basic Installation Instructions
+## Installation
 
-Seriously, go and see our [nicely formatted documentation][1] for more details.
 Add this line to your application's Gemfile:
 
     gem 'moonshot'
@@ -28,5 +47,19 @@ Or install it yourself as:
 
     $ gem install moonshot
 
-[1]: http://moonshot.readthedocs.org/en/latest/
-[2]: http://moonshot.readthedocs.org/en/latest/about/contribute
+After installation, there is still some work required. Follow the [example documentation](docs/example.md) as described below to dig in!
+
+## Getting started
+
+The Moonshot tool has been designed to be an extensible library for your specific use-case. Interested in how it can be used? See our [example documentation](http://moonshot.readthedocs.org/en/latest/example). The example doc uses the files shown in the [sample directory](https://github.com/acquia/moonshot/tree/master/sample) so you can figure out how to modify this for your own deployment strategy.
+
+We also want to [help you contribute and answer all your questions](http://moonshot.readthedocs.org/en/latest/about/contribute) on how Moonshot is maintained.
+
+## Requirements
+
+- Ruby 2.1 or higher
+
+## Attributions
+
+Thanks to [Acquia Inc.](https://acquia.com) for sponsoring the time to work on this tool.
+Thanks to [Ted](https://github.com/tottey) for the funky logo.

docs/example.md

@@ -1,6 +1,6 @@
 # Example usage of the Moonshot Library
 
-In this example we are going to use the resources of the sample directo
+In this example we are going to use the resources in the sample directory.
 This example assumes you have access to an Amazon AWS account and have sufficient permissions to create roles and resources.
 
 ## So, what's in it for me?
@@ -61,6 +61,25 @@ This step assumes that you have [Bundler](http://bundler.io/) and a modern versi
 bundle install
 ```
 
+### Create an S3 bucket and update the sample tools.
+
+First, create your own bucket to put your artifacts in:
+```shell
+$ aws s3api create-bucket --bucket moonshot-sample-your-name
+```
+
+Then update `bin/environment` to refer to that bucket in the `S3Bucket` configuration.
+
+### Create a configuration for your stack.
+
+We'll have to copy the base stack configuration and modify the ArtifactBucket
+parameter so that the instance has access to the release bucket (via the
+IAM Role in the CloudFormation stack).
+
+```shell
+$ cp cloud_formation/parameters/moonshot-sample-app.yml cloud_formation/parameters/moonshot-sample-app-dev-$USER.yml
+```
+
 ## Usage of the CLI
 
 Run the following commands to create your environment and deploy code to it.
@@ -115,4 +134,4 @@ Tear down your stack by running the following command:
 
 ```shell
 bundle exec bin/environment delete
-```
+```

docs/index.md

@@ -1,11 +1,12 @@
-# Moonshot
+# <img src="logo.png" width="48"> Moonshot
 _Because releasing services shouldn't be a moonshot._
 
 ## Overview
 
 Moonshot is a Ruby gem for provisioning environments in AWS using a CLI.
 The environments are centered around a single CloudFormation stack and supported
 by pluggable systems:
+
 - A DeploymentMechanism controls releasing code.
 - A BuildMechanism creates a release artifact.
 - A ArtifactRepository stores the release artifacts.
@@ -25,6 +26,11 @@ should aspire to meet them with each iteration.
 - Verbosity: The output of core Moonshot code should explain in detail what
   changes are being made, so knowledge is shared and not abstracted.
 
+## Existing limitations
+
+- Moonshot does not support detailed error logging from Cloudformation substacks.
+- Moonshot does not support a non-local cloudformation file.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -45,6 +51,13 @@ After installation, there is still some work required. Follow the [example docum
 
 The Moonshot tool has been designed to be an extensible library for your specific use-case. Interested in how it can be used? See our [example documentation](example.md). The example doc uses the files shown in the [sample directory](https://github.com/acquia/moonshot/tree/master/sample) so you can figure out how to modify this for your own deployment strategy.
 
+We also want to [help you contribute and answer all your questions](http://moonshot.readthedocs.org/en/latest/about/contribute) on how Moonshot is maintained.
+
 ## Requirements
 
 - Ruby 2.1 or higher
+
+## Attributions
+
+Thanks to [Acquia Inc.](https://acquia.com) for sponsoring the time to work on this tool.
+Thanks to [Ted](https://github.com/tottey) for the funky logo.

docs/mechanisms/artifact-repository.md

@@ -1,9 +1,9 @@
-## ArtifactRepository
+# ArtifactRepository
 
-Supported ArtifactRepositories:
-- S3
+## S3Bucket
 
-### S3Bucket
+The store action will upload the file using the S3 PutObject API call.
+The local environment must be configured with appropriate credentials.
 
 To create a new S3Bucket ArtifactRepository:
 ```ruby
@@ -12,5 +12,14 @@ class MyApplication < Moonshot::CLI
 end
 ```
 
-The store action will simply upload the file using the S3 PutObject API call.
-The local environment must be configured with appropriate credentials.
+## S3BucketViaGithubReleases
+
+S3 Bucket repository backed by GitHub releases.
+If a SemVer package isn't found in S3, it is downloaded from GitHub releases to avoid not being able to release in case there is trouble with AWS S3.
+
+To create a new S3BucketViaGithubReleases ArtifactRepository:
+```ruby
+class MyApplication < Moonshot::CLI
+  self.artifact_repository = S3BucketViaGithubReleases.new('my-bucket-name')
+end
+```

docs/mechanisms/build.md

@@ -1,6 +1,6 @@
-## BuildMechanism
+# BuildMechanism
 
-### Script
+## Script
 
 The Script BuildMechanism will execute a local shell script, with certain
 expectations. The script will run with some environment variables:
@@ -10,3 +10,55 @@ expectations. The script will run with some environment variables:
 
 If the file is not created by the build script, deployment will fail. Otherwise,
 the output file will be uploaded using the ArtifactRepository.
+
+Sample Usage
+```ruby
+#!/usr/bin/env ruby
+
+require 'moonshot'
+
+# Set up Moonshot tooling for our environment.
+class MoonshotSampleApp < Moonshot::CLI
+  self.build_mechanism = Script.new('bin/build.sh')
+...
+```
+
+## GithubRelease
+
+A build mechanism that creates a tag and GitHub release. Could be used to delegate other building steps after GitHub release is created.
+
+Sample Usage
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'moonshot'
+
+# Set up Moonshot tooling for our environment.
+class MoonshotSampleApp < Moonshot::CLI
+	wait_for_travis_mechanism = TravisDeploy.new("acquia/moonshot", true)
+  self.build_mechanism = GithubRelease.new(wait_for_travis_mechanism)
+...
+```
+
+## TravisDeploy
+
+The Travis Build Mechanism waits for Travis-CI to finish building a job matching the VERSION (see above) and the output of the travis job has to be 'BUILD=1'. Can be used to make sure that the travis job for the repository for that version actually finished before the deployment step can be executed.
+
+Sample Usage
+```ruby
+#!/usr/bin/env ruby
+
+require 'moonshot'
+
+# Set up Moonshot tooling for our environment.
+class MoonshotSampleApp < Moonshot::CLI
+  # First argument is the repository as known by travis.
+  # Second argument is wether or not you are using travis pro.
+  self.build_mechanism = TravisDeploy.new("acquia/moonshot", pro: true)
+...
+```
+
+## Version Proxy
+
+@Todo Document and clarify the use-case of the Version Proxy.

docs/mechanisms/deployment.md

@@ -1,24 +1,41 @@
+# DeploymentMechanism
 
-## DeploymentMechanism
+## CodeDeploy
 
-Supported DeploymentMechanisms:
-- CodeDeploy
-
-### CodeDeploy
-
-The CodeDeploy DeploymentMechanism will create a CodeDeploy Application and
-Deployment Group matching the application name. The created Deployment Group
-will point at the logical resource id provided to the constructor (e.g.
-`CodeDeploy.new(asg: 'MyAutoScalingGroup')`). During the `deploy-code` action,
-the ArtifactRepository is checked for compatibility with CodeDeploy. Currently
-only the S3Bucket is supported, though CodeDeploy itself supports deploying from
-a git source.
+The CodeDeploy DeploymentMechanism will create a CodeDeploy Application and Deployment Group matching the application name. The created Deployment Group will point at the logical resource id provided to the constructor (e.g. `CodeDeploy.new(asg: 'MyAutoScalingGroup')`). During the `deploy-code` action, the ArtifactRepository is checked for compatibility with CodeDeploy. Currently only the S3Bucket is supported, though CodeDeploy itself supports deploying from a git source.
 
 Assumptions made by the CodeDeploy mechanism:
+
 - You are using an S3Bucket ArtifactRepository.
 - You want to deploy using the OneAtATime method.
 - Your build artifact contains an appspec.yml file.
 
+Sample Usage
+```ruby
+#!/usr/bin/env ruby
+
+require 'moonshot'
+
+# Set up Moonshot tooling for our environment.
+class MoonshotSampleApp < Moonshot::CLI
+  self.deployment_mechanism = CodeDeploy.new(asg: 'AutoScalingGroup', role: 'CodeDeployRole', app_name: 'my_app_name')
+...
+```
+Parameters
+
+### asg | string
+
+The logical name of the AutoScalingGroup to create and manage a Deployment
+Group for in CodeDeploy.
+
+### role | string
+
+IAM role with AWSCodeDeployRole policy. CodeDeployRole is considered as default role if its not specified.
+
+### app_name | string,nil
+
+The name of the CodeDeploy Application and Deployment Group. By default, this is the same as the stack name, and probably what you want. If you have multiple deployments in a single Stack, they must have unique names.
+
 For more information about CodeDeploy, see the [AWS Documentation][1].
 
 [1]: http://docs.aws.amazon.com/codedeploy/latest/userguide/welcome.html