Merge pull request #66 from acquia/adding-sample

Adding sample

.gitignore

@@ -1,4 +1,5 @@
 /Gemfile.lock
 /vendor
 /coverage
-site/
+site/
+sample/gems

docs/example.md

@@ -1,10 +1,31 @@
 # Example usage of the Moonshot Library
 
+In this example we are going to use the resources of the sample directo
 This example assumes you have access to an Amazon AWS account and have sufficient permissions to create roles and resources.
 
-## Configuring your AWS account
+## So, what's in it for me?
 
-### CodeDeploy Role
+After setup, you will be able to repeatedly deploy a PHP app to one or more
+isolated environments on AWS by running the following command:
+
+```shell
+bundle exec bin/environment deploy-code
+```
+
+You will also be able to update the OS and supporting software by pulling the
+latest changes in this repository and updating the stack with following command:
+
+```shell
+bundle exec bin/environment update
+```
+
+Lastly, you get a disposable, light-weight application that can be used to learn
+and hack on Moonshot without having to muck with applications that actually
+matter.
+
+## Setup
+
+### Create a service role for Code Deploy in your AWS account.
 
 Create a role called CodeDeployRole with the AWSCodeDeployRole policy
 
@@ -27,64 +48,71 @@ aws iam create-role --role-name CodeDeployRole --assume-role-policy-document '{
 aws iam attach-role-policy --role-name CodeDeployRole --policy-arn arn:aws:iam::aws:policy/service-role/AWSCodeDeployRole
 ```
 
-## Create a Ruby wrapper
+If you wish to do this manually, follow the
+[Create a Service Role for AWS CodeDeploy](http://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-service-role.html)
+documentation, and make sure to name the role `CodeDeployRole` as that is
+what Moonshot expects.
+
+### Install Moonshot and it's dependencies.
 
-Now, let's create a ruby wrapper that implements the Moonshot tool and makes your CLI.
-The base class is a subclass of Thor, so you can extend it using the [full Thor extensibility](http://whatisthor.com/). Here's a basic example using all the defaults:
+This step assumes that you have [Bundler](http://bundler.io/) and a modern version of Ruby installed on your system. See Moonshot's [requirements](index.md#requirements)
 
-```ruby
-#!/usr/bin/env ruby
+```shell
+bundle install
+```
 
-require 'moonshot'
+## Usage of the CLI
 
-# Set up Moonshot tooling for our environment.
-class MyService < Moonshot::CLI
-  self.application_name = 'my-service'
-  self.artifact_repository = S3Bucket.new('my-service-builds')
-  self.build_mechanism = Script.new('build/script.sh')
-  self.deployment_mechanism = CodeDeploy.new(asg: 'AutoScalingGroup')
-end
+Run the following commands to create your environment and deploy code to it.
+Note that you will have to set the `AWS_REGION` environment variable prior to running these commands. If it's not set, it will use the default AWS region which at the time of this writing is us-east-1.
 
-MyService.start
-```
+A detailed explanation of [all the CLI commands can be found in the User Guide](user-guide/cli.md)
 
-This example assumes:
-- You have a CloudFormation JSON template in folder called "cloud_formation/my-service.json".
-- You have an S3 bucket called "my-service-builds".
-- You have a script in "script/build.sh" that will build a tarball output.tar.gz.
-- You have a working CodeDeploy setup, including the CodeDeployRole.
+You can now deploy your software to a new stack with:
 
-If all that is true, you can now deploy your software to a new stack with:
-```
+```shell
 $ ./bin/environment create
 ```
 
-By default, you'll get a development environment named `my-service-dev-giraffe`,
-where `giraffe` is your username. If you want to provision test or production
+By default, you'll get a development environment named `moonshot-sample-app`. If you want to provision test or production
 named environment, use:
-```
+
+```shell
 $ ./bin/environment create -n my-service-staging
 $ ./bin/environment create -n my-service-production
 ```
 
 By default, create launches the stack and deploys code. If you want to only
 create the stack and not deploy code, use:
-```
+
+```shell
 $ ./bin/environment create --no-deploy
 ```
 
 If you make changes to your application and want to release a development build
 to your stack, run:
-```
+
+```shell
 $ ./bin/environment deploy-code
 ```
 
 To build a "named build" for releasing through test and production environments,
 use:
+
+```shell
+$ ./bin/environment build-version v0.1.0
+$ ./bin/environment deploy-version v0.1.0 -n <environment-name>
 ```
+
+To see the outputs of the stack you just spun up:
+
+```shell
 $ ./bin/environment build-version v0.1.0
 $ ./bin/environment deploy-version v0.1.0 -n <environment-name>
 ```
 
-We recommend using a CI system like Jenkins to perform those activities, for
-consistency.
+Tear down your stack by running the following command:
+
+```shell
+bundle exec bin/environment delete
+```

docs/index.md

@@ -37,10 +37,11 @@ Or install it yourself as:
 
     $ gem install moonshot
 
+After installation, there is still some work required. Follow the [example documentation](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](example.md) documentation or look at our [sample application](https://github.com/acquia/moonshot-sample-app)
+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.
 
 ## Requirements
 

docs/mechanisms/artifact-repository.md

@@ -0,0 +1,16 @@
+## ArtifactRepository
+
+Supported ArtifactRepositories:
+- S3
+
+### S3Bucket
+
+To create a new S3Bucket ArtifactRepository:
+```ruby
+class MyApplication < Moonshot::CLI
+  self.artifact_repository = S3Bucket.new('my-bucket-name')
+end
+```
+
+The store action will simply upload the file using the S3 PutObject API call.
+The local environment must be configured with appropriate credentials.

docs/mechanisms/build.md

@@ -0,0 +1,12 @@
+## BuildMechanism
+
+### Script
+
+The Script BuildMechanism will execute a local shell script, with certain
+expectations. The script will run with some environment variables:
+
+- `VERSION`: The named version string passed to `build-version`.
+- `OUTPUT_FILE`: The file that the script is expected to produce.
+
+If the file is not created by the build script, deployment will fail. Otherwise,
+the output file will be uploaded using the ArtifactRepository.

docs/mechanisms/deployment.md

@@ -0,0 +1,24 @@
+
+## DeploymentMechanism
+
+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.
+
+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.
+
+For more information about CodeDeploy, see the [AWS Documentation][1].
+
+[1]: http://docs.aws.amazon.com/codedeploy/latest/userguide/welcome.html