Punter

This is a simple tool for configuring, starting, and stopping servers in Amazon's EC2 cloud. It's specifically geared towards "one off" deployment and light weight prototyping.

If you're looking for sophisticated deployment and dependency management, I suggest you look at Chef or Puppet -- they're quite nice for bigger deployments and complex configurations.

Punter has four basic tasks:

• Starting servers
• Stopping servers
• Listing running servers
• Listing server configurations

Out of the box, it's configured to start Ubuntu 12.04 LTS images on "small" EC2 instances with EBS storage. If you're not sure what that means, check out the AWS Instance Types.

Punter works by stitching together shell scripts found in the fragments/ directory, and running them on the server after it boots. Pretty simple!

Installation

Punter is a set of Ruby rake tasks; as such, please install Ruby 1.9.2 and the bundler gem. Run bundle install in the Punter root directory to install the other Ruby dependencies.

Then, update the config.yml file with your AWS credentials and the name of your default EC2 key pair.

Running

To see the available configuration profiles:

$ rake profiles
basic:
       Fragments: basic
  Security Group: default
   Key Pair Name: YOUR_AWS_KEYPAIR_NAME

ruby:
       Fragments: basic, ruby
  Security Group: default
   Key Pair Name: YOUR_AWS_KEYPAIR_NAME

credit:
       Fragments: basic, credit
  Security Group: default
   Key Pair Name: YOUR_AWS_KEYPAIR_NAME

This lists out the names of each profile, and the script fragments they use.

In the first case, basic is the name of a profile that just runs the basic fragment. Second, the ruby profile stitches together the basic and ruby fragments. The lamp profile stitches together the basic and lamp fragments. Simple, 'eh?

$ rake start PROFILE=basic

This will start a server with the basic profile. Easy.

What servers are currently running?

$ rake servers
PROFILE     IP               INSTANCE    STATUS         STARTED
basic       123.45.67.8      i-98e4a9e2  running        2012-09-13 22:37:12 UTC
basic                        i-26f5b85c  terminated     2012-09-13 22:45:04 UTC

This will list out all of the servers running on your AWS account, with the profile they started with, IP, AWS instance identifier, and a startup timestamp.

Maybe you want to terminate a server?

$ rake terminate INSTANCE=i-12345678
Terminate the server running the 'ruby' profile at 23.45.67.89? [y/N]
Terminating.

It's interactive, and gives you a bit of information so that you can avoid a gnarly OH SHIT moment.

Fragments

Fragments are the building blocks of a profile: bash scripts that are concatenated together, then run as root on the box, immediately after it boots. The basic fragment is the simplest of the bunch:

# update packages
apt-get update
apt-get -y upgrade

# install packages we always want
apt-get -y install git-core tmux

All fragments can be found in the fragments directory.

Fragments also support ERB templating. Here's fragments/credit.sh.erb:

<%= runtime_log("User #{`whoami`.chomp} started this server at #{Time.now}") %>

Please note that the ERB is evaluated before you start the server.

Profiles

A profile is simply a list of fragments to put together, and is specified in the profiles.yaml file. For example:

ruby:
  fragments:
    - basic
    - ruby
  security-groups:
    - ssh

This specifies that the ruby profile is dependent on the basic and ruby fragments, and that it will belong to the ssh security group (assuming you have it configured on EC2).

Punter will look for both .sh and .sh.erb fragments for a given name, so don't worry about the extension.

To inspect the the completely assembled and rendered profile before you start a server with it, you can inspect it. For example:

$ rake inspect PROFILE=credit

That displays the entire credit profile, including a rendered ERB fragment.

Logging

You can check the status of a new instance by looking at the /punter.log file on the server. It's not particularly detailed, but it can help you figure out what the system is doing, and if it's completed setting up the environment. For example, the log for a ruby profile looks like this:

STARTED PROFILE ruby
Started fragment 'basic'
Finished fragment 'basic'
Started fragment 'ruby'
Finished fragment 'ruby'
COMPLETED PROFILE ruby. Have fun!

Punter automatically adds the profile and fragment starting and finishing messages.

Contributing

You're welcome to contribute fragments and other updates; just send over a pull request, and tell me if you're cool with the Apache License 2.0.