<commit_before>With Rudy you can launch complex environments in EC2 with a single command (that includes EBS volumes). This document takes you through all steps required to get started.

*NOTE: The current release of Rudy (0.6) is still in alpha status. See the Alpha Notice in the README before continuing.*

h2. Create an Amazon Web Services account

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

# Go to <a href="http://aws.amazon.com/">Amazon Web Services</a> and click, "Sign up now"
# Fill out the form to create your account.
# Sign up for each of the following services: <a href="http://aws.amazon.com/ec2/">EC2</a>, <a href="http://aws.amazon.com/s3/">S3</a>, <a href="http://aws.amazon.com/simpledb/">SimpleDB</a>
# Go to the <a href="https://aws-portal.amazon.com/gp/aws/developer/account/index.html?ie=UTF8&amp;action=access-key">Access Indentifiers</a> page, and collect the following: Account Number, Access Key ID, Secret Key
# 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:
* Amazon Account Number
* Access Key ID
* Secret Key
* X.509 Private Key (<tt>pk-XXXX.pem</tt>)
* X.509 Certificate (<tt>cert-XXXX.pem</tt>)

*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!*

h2. Install 

You can install Rudy via Rubygems with the command below or download as a <a href="http://github.com/solutious/rudy/zipball/latest">tar</a> or <a href="http://github.com/solutious/rudy/zipball/latest">zip</a>. 

<pre><code>  $ sudo gem install rudy
  Successfully installed rudy
  1 gem installed</code></pre>

h2. 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.

<pre><code>  $ rudy generate-config
  Creating /Users/delano/.rudy
  Creating /Users/delano/.rudy/config
  Add your AWS credentials to /Users/delano/.rudy/config</code></pre>

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

<pre><code>  accounts do
    aws do
      name "Account Name"
      accountnum "123456789012"
      accesskey "ACCESSACCESSACCESSACCESS"
      secretkey "SECRETSECRETSECRETSECRET"
      privatekey "~/path/2/pk-****.pem"
      cert "~/cert-****.pem"
    end
  end</code></pre>

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

<pre><code>  $ rudy init
  Creating SimpleDB domain rudy_state
  Initialized</code></pre>


h2. 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 <tt>stage-app</tt>.

First, we'll generate a skeleton configuration file:

<pre><code>  $ rudy config --project > Rudyfile</code></pre>

If you take a look at <tt>Rudyfile</tt>, you can see that the project configuration is organized into two sections: <tt>machines</tt> and <tt>routines</tt>. 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.

h4. 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 <tt>key-stage-app</tt> and a security group called <tt>g-stage-app</tt>. 

h4. Can I use my own keypair?

Yep! You can specify your own keypairs in the machines config. You can find an example in the <tt>Rudyfile</tt> 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.

h2. 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:

<pre><code>  $ rudy startup</pre></code>
<pre><code>  Starting m-us-east-1b-stage-app-01
    
    ===  m-us-east-1b-stage-app-01  i-f6e9829f:pending  
    Waiting for instance.............it's up!
    Waiting for SSH daemon.....................it's up!
    
    ===  DISK ROUTINES  =======================================
    Creating disk-us-east-1b-stage-app-01-rudy-disk1 
    Creating volume... done
    Attaching vol-fa0cef93 to i-f6e9829f... done
    Creating ext3 filesystem for /dev/sdr... done
    Mounting at /rudy/disk1... done
    
    ===  INFO  ================================================
    Filesystem on m-us-east-1b-stage-app-01:
      /dev/sdr              2.0G   68M  1.9G   4% /rudy/disk1
    
    The following machines are now available:
    m-us-east-1b-stage-app-01  ec2-11-22-33-44.compute-1.amazonaws.com</code></pre>

We can now see that there is a new machine running:

<pre><code>  $ rudy machines
  m-us-east-1b-stage-app-01  ec2-11-22-33-44.compute-1.amazonaws.com</code></pre>

h2. SSH into the machine

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

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

The <tt>-u root</tt> 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 <tt>-u</tt> Rudy will attempt to login with the name of the current user. 


h2. Shutdown the Machine Group

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

<pre><code>  $ rudy shutdown</pre></code>
<pre><code>  All machines in stage-app will be shutdown and
  the following filesystems will be destroyed:
  /rudy/disk1
  Are you sure? To continue, resolve (5 * 2): 10
  Waiting for instance...it's up!
  Waiting for SSH daemon...it's up!
  
  ===  DISK ROUTINES  =========================================
  Destroying disk-us-east-1b-stage-app-01-rudy-disk1
  Unmounting /rudy/disk1... done
  Detaching vol-fa0cef93... .done
  Destroying metadata... done
  
  ===  m-us-east-1b-stage-app-01  ec2-11-22-33-44.compute-1.amazonaws.com 
  Destroying m-us-east-1b-stage-app-01
  
  No instances running</code></pre>
<commit_msg>Added built in help commands<commit_after>With Rudy you can launch complex environments in EC2 with a single command (that includes EBS volumes). This document takes you through all steps required to get started.

*NOTE: The current release of Rudy (0.6) is still in alpha status. See the Alpha Notice in the README before continuing.*

h2. Create an Amazon Web Services account

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

# Go to <a href="http://aws.amazon.com/">Amazon Web Services</a> and click, "Sign up now"
# Fill out the form to create your account.
# Sign up for each of the following services: <a href="http://aws.amazon.com/ec2/">EC2</a>, <a href="http://aws.amazon.com/s3/">S3</a>, <a href="http://aws.amazon.com/simpledb/">SimpleDB</a>
# Go to the <a href="https://aws-portal.amazon.com/gp/aws/developer/account/index.html?ie=UTF8&amp;action=access-key">Access Indentifiers</a> page, and collect the following: Account Number, Access Key ID, Secret Key
# 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:
* Amazon Account Number
* Access Key ID
* Secret Key
* X.509 Private Key (<tt>pk-XXXX.pem</tt>)
* X.509 Certificate (<tt>cert-XXXX.pem</tt>)

*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!*

h2. Install 

You can install Rudy via Rubygems with the command below or download as a <a href="http://github.com/solutious/rudy/zipball/latest">tar</a> or <a href="http://github.com/solutious/rudy/zipball/latest">zip</a>. 

<pre><code>  $ sudo gem install rudy
  Successfully installed rudy
  1 gem installed</code></pre>

h2. 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.

<pre><code>  $ rudy generate-config
  Creating /Users/delano/.rudy
  Creating /Users/delano/.rudy/config
  Add your AWS credentials to /Users/delano/.rudy/config</code></pre>

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

<pre><code>  accounts do
    aws do
      name "Account Name"
      accountnum "123456789012"
      accesskey "ACCESSACCESSACCESSACCESS"
      secretkey "SECRETSECRETSECRETSECRET"
      privatekey "~/path/2/pk-****.pem"
      cert "~/cert-****.pem"
    end
  end</code></pre>

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

<pre><code>  $ rudy init
  Creating SimpleDB domain rudy_state
  Initialized</code></pre>


h2. 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 <tt>stage-app</tt>.

First, we'll generate a skeleton configuration file:

<pre><code>  $ rudy config --project > Rudyfile</code></pre>

If you take a look at <tt>Rudyfile</tt>, you can see that the project configuration is organized into two sections: <tt>machines</tt> and <tt>routines</tt>. 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.

h4. 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 <tt>key-stage-app</tt> and a security group called <tt>g-stage-app</tt>. 

h4. Can I use my own keypair?

Yep! You can specify your own keypairs in the machines config. You can find an example in the <tt>Rudyfile</tt> 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.

h2. 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:

<pre><code>  $ rudy startup</pre></code>
<pre><code>  Starting m-us-east-1b-stage-app-01
    
    ===  m-us-east-1b-stage-app-01  i-f6e9829f:pending  
    Waiting for instance.............it's up!
    Waiting for SSH daemon.....................it's up!
    
    ===  DISK ROUTINES  =======================================
    Creating disk-us-east-1b-stage-app-01-rudy-disk1 
    Creating volume... done
    Attaching vol-fa0cef93 to i-f6e9829f... done
    Creating ext3 filesystem for /dev/sdr... done
    Mounting at /rudy/disk1... done
    
    ===  INFO  ================================================
    Filesystem on m-us-east-1b-stage-app-01:
      /dev/sdr              2.0G   68M  1.9G   4% /rudy/disk1
    
    The following machines are now available:
    m-us-east-1b-stage-app-01  ec2-11-22-33-44.compute-1.amazonaws.com</code></pre>

We can now see that there is a new machine running:

<pre><code>  $ rudy machines
  m-us-east-1b-stage-app-01  ec2-11-22-33-44.compute-1.amazonaws.com</code></pre>

h2. SSH into the machine

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

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

The <tt>-u root</tt> 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 <tt>-u</tt> Rudy will attempt to login with the name of the current user. 


h2. Shutdown the Machine Group

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

<pre><code>  $ rudy shutdown</pre></code>
<pre><code>  All machines in stage-app will be shutdown and
  the following filesystems will be destroyed:
  /rudy/disk1
  Are you sure? To continue, resolve (5 * 2): 10
  Waiting for instance...it's up!
  Waiting for SSH daemon...it's up!
  
  ===  DISK ROUTINES  =========================================
  Destroying disk-us-east-1b-stage-app-01-rudy-disk1
  Unmounting /rudy/disk1... done
  Detaching vol-fa0cef93... .done
  Destroying metadata... done
  
  ===  m-us-east-1b-stage-app-01  ec2-11-22-33-44.compute-1.amazonaws.com 
  Destroying m-us-east-1b-stage-app-01
  
  No instances running</code></pre>

h2. Built-in Help

The Rudy command line tools have plenty of built-in documentation. 

* @$ rudy -h@
* @$ rudy-ec2 -h@
* @$ rudy-sdb -h@
* @$ rudy-s3 -h@
{'fraction_non_alphanumeric': 0.12247283729885848, 'fraction_numerical': 0.026337505157474902, 'mean_word_length': 3.6051298290057, 'pattern_counts': {'":': 0, '<': 179, '<?xml version=': 0, '>': 181, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2469819', 'n_tokens_mistral': 4766, 'n_tokens_neox': 4456, 'n_words': 1775}