Commercial Products
welcome to solutious - home of good natured tools

Getting Started

This document takes you through all steps required to get started with Rudy. By the end, you’ll be able to launch multiple EC2 machines with EBS volumes from a single command.

Note: The current release of Rudy (0.9) is in BETA status. That means Rudy is not ready for production use! See Project Status.

This document covers the following steps:

Create an Amazon Web Services account

Skip to this step if you have already signed up for EC2, S3, and SimpleDB.

  1. Go to Amazon Web Services and click, “Sign up now”
  2. Fill out the form to create your account.
  3. Sign up for each of the following services: EC2, S3, SimpleDB
  4. Go to the Access Indentifiers page, and collect the following: Account Number, Access Key ID, Secret Key
  5. At the bottom of the page, click the “Create New” button to create your private key and certificate. Make sure you download the private key because Amazon does not keep a copy.

You should now have the following identifiers:

NOTE: Your Access Identifiers are the keys to your castle. Keep them safe. If you suspect someone may have them, you can go back to the Access Identifiers page at any time to generate a new secret key. And don’t forget to update your Rudy config!

Install Rudy

You can install Rudy via Rubygems with the command below or download as a tar or zip.

  $ sudo gem install rudy
  Successfully installed rudy
  1 gem installed

Create Accounts Configuration

Rudy stores configuration in two places: your home directory and your project directory. This allows you to keep your Amazon Access Identifiers and private keys in a secure place (~/.rudy). Your project configuration, which we create in the next step, can be kept inside your project directory so it can be versioned with your application.

In this step, we’ll create the accounts configuration file.

  $ rudy generate-config
  Creating /Users/delano/.rudy
  Creating /Users/delano/.rudy/config
  Add your AWS credentials to /Users/delano/.rudy/config

The accounts section of your ~/.rudy/config file should look like this:

  accounts {
    aws {
      name "Account Name"
      accountnum "123456789012"
      accesskey "ACCESSACCESSACCESSACCESS"
      secretkey "SECRETSECRETSECRETSECRET"
      privatekey "path/2/pk-****.pem"
      cert "path/2/cert-****.pem"
    }
  }

Rudy stores metadata about your machines and disks in SimpleDB. The init command creates a SimpleDB domain called rudy_state to store this metadata.

  $ rudy init
  Creating SimpleDB domain rudy_state
  Authorizing public keys for user@localhost

Create Project Configuration

The project configuration tells Rudy about the machine groups you want to create. Machine groups are named after the current environment and role. In this example, we’ll configure the default machine group called stage-app.

First, we’ll generate a skeleton configuration file:

  $ rudy config --project > Rudyfile

If you take a look at Rudyfile, you can see that the project configuration is organized into two sections: machines and routines. The machines configuration describes the “physical” characteristics of your machine groups. The routines configuration describes what happens when you startup and shutdown a machine group (Rudy refers to these as routines).

We’ll use the configuration in the next section to launch a machine group within EC2.

What about security groups and keypairs?

Rudy creates these for you based on the same naming convention as machines. The default group will get a key called key-stage-app and a security group called g-stage-app.

Can I use my own keypair?

Yep! You can specify your own keypairs in the machines config. You can find an example in the Rudyfile we generated above. Note: if you’re specifying a launch keypair, the filename will need to match the name of the keypair that’s registered with EC2. i.e. If the path is, /path/2/defaultkey it must be registered as defaultkey with EC2.

Launch a Machine Group

Rudy now has all everything it needs to launch the default machine group. To launch a machine group, you call the startup routine:

$ rudy startup
  Authorizing group: 70.49.123.222 (22, 22)
  Starting m-us-east-1d-stage-app-01........
  Waiting for SSH on port 22.....
  Creating volume... 
  Attaching vol-0023c869 to i-e523298c... 
  Creating ext3 filesystem for /dev/sdr... 
  Mounting at /rudy/disk1... 

  The following machines are now available:
  m-us-east-1d-stage-app-01

Using the machines command we can list the machines running in the default machine group.

  $ rudy machines
  m-us-east-1d-stage-app-01

SSH into the machine

You can log into the default machine with the following command:

  $ rudy -u root ssh
  Connecting root@ec2-11-22-33-44.compute-1.amazonaws.com
  Linux domU-12-31-39-03-48-D4 2.6.21.7-2.fc8xen #1 SMP Fri Feb 15 12:39:36 i686
  
  root@m-us-east-1d-stage-app-01:~#

The -u root tells Rudy to open a connection as the root user. If you create an account on that instance, you can login as that user too. If you don’t provide -u Rudy will attempt to login with the name of the current user.

Shutdown the Machine Group

When you want to shutdown the machine, you use the shutdown routine:

$ rudy shutdown
  All machines in stage-app will be shutdown
  The following filesystems will be destroyed:
  /rudy/disk1
  Unmounting /rudy/disk1... 
  Detaching vol-0023c869.....
  Destroying disk-us-east-1d-stage-app-01-rudy-disk1
  
  The following instances have been destroyed:
  m-us-east-1d-stage-app-01 i-e523298c

Built-in Help

The Rudy command line tool has plenty of built-in documentation.

More Examples