README.textile in pauldowman-ec2onrails-0.9.10 vs README.textile in pauldowman-ec2onrails-0.9.10.0
- old
+ new
@@ -1,12 +1,12 @@
h1. EC2 on Rails
h2. Deploy a Ruby on Rails app on EC2 in five minutes
-Main Page: "https://ec2onrails.rubyforge.org":https://ec2onrails.rubyforge.org
+Main Page: "http://ec2onrails.rubyforge.org":http://ec2onrails.rubyforge.org
-Code on Github: "https://github.com/pauldowman/ec2onrails":https://github.com/pauldowman/ec2onrails
+Code on Github: "http://github.com/pauldowman/ec2onrails":http://github.com/pauldowman/ec2onrails
EC2 on Rails is an Ubuntu Linux server image for "Amazon's EC2 hosting service":http://www.amazon.com/b/ref=sc_fe_l_2/102-6342260-7987311?ie=UTF8&node=201590011&no=3435361 that's ready to run a standard Ruby on Rails application with little or no customization. It's a Ruby on Rails "virtual appliance":http://en.wikipedia.org/wiki/Virtual_appliance.
If you have an EC2 account and can start EC2 instances you're five minutes away from deploying your Rails app.
@@ -24,11 +24,11 @@
"Coda Hale's excellent guide":http://blog.codahale.com/2006/06/19/time-for-a-grown-up-server-rails-mongrel-apache-capistrano-and-you/
* Ruby on Rails 2.1.0, 2.0.2 and 1.2.6
* Ruby 1.8.6
* MySQL 5
* "memcached":http://www.danga.com/memcached/
-* "monit":http://www.tildeslash.com/monit/ configured to monitor apache, mongrel, mysql, memcached, drive space and system load
+* "god":http://god.rubyforge.org/ configured to monitor apache or nginx, mongrel, mysql, memcached, drive space and system load
* Ubuntu 8.04 LTS "Hardy" base image built using "Eric Hammond's EC2 Ubuntu script":http://alestic.com/
* SSL support
* Amazon AMI tools installed
* Apache or Nginx web proxies
* MySQL, Apache/Nginx, and syslog configured to use /mnt for data and logging so you don't fill up EC2's small root filesystem
@@ -55,23 +55,23 @@
<pre>sudo gem install ec2onrails</pre>
h4. 2. Add the config files to your Rails app
-You will need to place "Capfile":http://github.com/pauldowman/ec2onrails/tree/master/examples/Capfile?raw=true in the root of your rails folder, and put "deploy.rb":http://github.com/pauldowman/ec2onrails/tree/master/examples/deploy.rb?raw=true and "s3.yml":http://github.com/pauldowman/ec2onrails/tree/master/examples/s3.yml?raw=true in the config folder.
+You will need to place "Capfile":http://github.com/pauldowman/ec2onrails/raw/master/examples/Capfile in the root of your rails folder, and put "deploy.rb":http://github.com/pauldowman/ec2onrails/raw/master/examples/deploy.rb and "s3.yml":http://github.com/pauldowman/ec2onrails/raw/master/examples/s3.yml in the config folder.
Within your rails directory, run
-<code>
- wget -q -O Capfile http://github.com/pauldowman/ec2onrails/tree/master/examples/Capfile?raw=true
- wget -q -O config/deploy.rb http://github.com/pauldowman/ec2onrails/tree/master/examples/deploy.rb?raw=true
- wget -q -O config/s3.yml http://github.com/pauldowman/ec2onrails/tree/master/examples/s3.yml?raw=true
-</code>
+<pre>
+ wget -q -O Capfile http://github.com/pauldowman/ec2onrails/raw/master/examples/Capfile
+ wget -q -O config/deploy.rb http://github.com/pauldowman/ec2onrails/raw/master/examples/deploy.rb
+ wget -q -O config/s3.yml http://github.com/pauldowman/ec2onrails/raw/master/examples/s3.yml
+</pre>
_Be sure to customize those files and read the comments._
-Also, use the hostname "db_primary" in your database.yml file. After running "cap ec2onrails:server:set_roles" it will resolve to the instance defined in your Capistrano "db" role.
+In your database.yml file, add <code>host: db_primary</code> to the host of other database configuration options. After running "cap ec2onrails:server:set_roles" it will resolve to the instance defined in your Capistrano "db" role.
h4. 3. Start up one or more instances of the image.
There is nothing EC2 on Rails-specific here yet (though soon there will be a Capistrano task to do this for you), if you've started EC2 instances before you can skip this section. Otherwise, I'm not going to lie, this part is complicated and will take a lot more than 5 minutes the first time.
@@ -79,11 +79,11 @@
For the AMI id's of the current images do <code>cap ec2onrails:ami_ids</code> from within the app that you configured in the previous step (they're also listed earlier on this page).
_NOTE: Only use the images that match the current version of the gem._
-Please see the "change log":http://ec2onrails.rubyforge.org/svn/trunk/gem/CHANGELOG for release notes, and see the "list of open issues":http://rubyforge.org/tracker/?atid=17558&group_id=4552&func=browse.
+Please see the "change log":http://github.com/pauldowman/ec2onrails/raw/master/gem/CHANGELOG for release notes, and see the "list of open issues":http://rubyforge.org/tracker/?atid=17558&group_id=4552&func=browse.
As is "standard for public AMI's":http://docs.amazonwebservices.com/AWSEC2/2007-08-29/DeveloperGuide/public-ami-guidelines.html, password-based logins are disabled. You log in with your own "public/private keypair":http://docs.amazonwebservices.com/AWSEC2/2007-08-29/GettingStartedGuide/running-an-instance.html.
Most basic things can be configured automatically by the Capistrano tasks, but if you want to you can login by ssh as a user named "admin" (has sudo ability) or as "app" (the user that the app runs as, does not have sudo ability). The Capistrano tasks automatically use the app user to deploy the app, and the admin user for server admin tasks that require sudo.
@@ -104,11 +104,10 @@
h4. 5. Deploy the app with Capistrano
Now that the gem is installed, your deploy.rb is configured and you can start and stop EC2 instances, this is the only thing you'll need to do from now on.
<pre>
-cap ec2onrails:setup
cap deploy:cold
</pre>
Yes, it's that easy! The setup task will set the server's timezone, install any gems and Ubuntu packages that you specified in the config file, and create your database.
@@ -125,12 +124,10 @@
You'll mostly need just the following Capistrano tasks:
* <code>cap ec2onrails:ami_ids</code> Shows the AMI id's of the images that match the current version of the gem.
-* <code>cap ec2onrails:setup</code> This task configures a newly-launched instance. This is the first thing you should do after starting a new instance. It can be run more than once without ill effect. After running "cap ec2onrails:setup" the next thing to do is run "cap deploy:cold"
-
* <code>cap ec2onrails:db:enable_ebs</code> This task will move the _primary_ mysql database onto an Amazon Elastic Storage Block (EBS) volume. You can call this task with the optional SIZE parameter defined (defaults to 10 gigs) like <pre>cap ec2onrails:db:enable_ebs SIZE=10</pre>
You should then specify your own volume (or the one created by this task) in your capistrano deploy.rb file like so: <pre>role :db, "ec2-xx-xxx-xx-xxx.compute-1.amazonaws.com", :primary => true, :ebs_vol_id => 'vol-12345abc'</pre>
*NOTE* MySQL EBS is not enabled by default. You may call this task at anytime to move your MySQL over to EBS, but just make sure you keep track of the volume-id that is printed out by this task and use it to modify your deploy.rb file
@@ -148,39 +145,45 @@
To get a full list of the Capistrano tasks at any time type <code>cap -T</code> from with your rails app root.
h2. Building the image
-Building the image is not required, most people will simply use the prebuilt public image, but there is also a build script that builds the image. It's meant to be called by "Eric Hammond's EC2 Ubuntu script":http://alestic.com/.
+The EC2 on Rails server image is built using "Eric Hammond's EC2 Ubuntu build script":http://alestic.com/
-Here is how you go about setting it up:
+Note that building your own AMI is not necessary, other options are:
+* Use one of the public AMI's and configure it at run-time (recommended).
+* Re-bundle one of the public AMI's and save it as your own (not recommended because you won't be able to take advantage of any bug fixes or updates).
+
+Instructions:
-h4. Notes
+1. Start an EC2 instance that will be used to run the build script. The recommended AMI's are Amazon's public developer images:
+<pre>32-bit: ami-f51aff9c
+64-bit: ami-f21aff9b</pre>
-* amazon-keypair is your amazon keypair, which in this case has has had the public and private keys copied into the ~/.ssh folder
-* we need to copy the ec2onrails source folder onto the image instance
-* HOST_PUBLIC_INSTANCE is the hostname of the instance that you will soon be creating. run <code>ec2-describe-instances</code> to find this value. It will look something like <code>ec2-xxx-xxx-xxx-xxx.compute-x.amazonaws.com</code>
+2. Copy your certificate file and private key file to the EC2 instance ephemeral storage, using your ssh _IDENTITY_ (key) file:
+<pre>scp -i _IDENTITY_ pk-XXXXXXXXXX.pem root@_HOSTNAME_:/mnt/
+scp -i _IDENTITY_ cert-XXXXXXXXXX.pem root@_HOSTNAME_:/mnt/</pre>
-h4. Getting started...
+3. Copy the entire ec2onrails source folder _EC2ONRAILS_ to the EC2 instance ephemeral storage, using your ssh IDENTITY file:
+<pre>rsync -rlvzcC --delete --exclude='output*' --exclude='.git' --rsh='ssh -i _IDENTITY_' _EC2ONRAILS_ root@_HOSTNAME_:/mnt/</pre>
+Note: make sure NOT to include a trailing slash on the ec2onrails directory name, rsync behaves differently when copying directories if there is no slash at the end of the folder name! After this step you should have a directory on the server named /mnt/ec2onrails (e.g. use /rails/ec2onrails not /rails/ec2onrails/ or /rails/ec2onrails/.)
-* launch one of Eric's default images (see "Eric Hammond's":http://alestic.com/ page for the most recent ami-images): <code>ec2-run-instances ami-179e7a7e -k amazon-keypair</code> (for a 64-bit image, launch: <code>ec2-run-instances ami-f89d7991 -k amazon-keypair --instance-type m1.large</code>)
-* lets get your amazon keypair up onto the instance: <code>scp -i ~/.ssh/id_rsa-amazon-keypair ~/.ec2/{cert,pk}-*.pem root@HOST_PUBLIC_ADDRESS:/mnt/</code>
-* ditto for getting the ec2onrails server code up onto your new instance: <code>scp -rp -i ~/.ssh/id_rsa-amazon-keypair ~/your/copy/of/ec2onrails/. root@HOST_PUBLIC_ADDRESS:/mnt/ec2onrails</code>
-* time to log into your instance: <code>ssh -i ~/.ssh/id_rsa-amazon-keypair root@HOST_PUBLIC_ADDRESS</code>
-* get the most recent ec2ubuntu script: <code>curl -Lo /mnt/ec2ubuntu-build-ami http://ec2ubuntu-build-ami.notlong.com</code>
-* time to get the instance ready for ec2onrails. The script will end with a command you need to run to finish creating an amazon ami-image. <pre>bash /mnt/ec2ubuntu-build-ami \
---codename hardy \
---bucket YOURNAME_ec2onrails \
---prefix ec2onrails \
---user YOUR_AMAZON_USER_ID \
---access-key AMAZON_ACCESS_KEY \
---secret-key AMAZON_SECRET_KEY \
---private-key /mnt/pk-*.pem \
---cert /mnt/cert-*.pem \
---script /mnt/ec2onrails/server/build-ec2onrails.sh</pre>
+4. Using ssh, log in to the EC2 instance _HOSTNAME_ using your ssh _IDENTITY_ file:
+<pre>ssh -i _IDENTITY_ root@_HOSTNAME_</pre>
+5. On the server, run the build script with the appropriate arguments: (_ARCH_ is either i386 or amd64)
+<pre>ruby /mnt/ec2onrails/server/build \
+ --bucket ec2onrails \
+ --prefix ec2onrails-custom \
+ --arch _ARCH_
+ --user XXXX-XXXX-XXXX \
+ --access-key XXXXXXXXXX \
+ --secret-key XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
+ --private-key /mnt/pk-XXXXXXXXXX.pem \
+ --cert /mnt/cert-XXXXXXXXXX.pem</pre>
+
h2. Mailing lists
There are two Google groups, one for "announcements":http://groups.google.com/group/ec2-on-rails-announce (usually just new release announcements) and one for "discussion":http://groups.google.com/group/ec2-on-rails-discuss.
@@ -189,22 +192,38 @@
Comments are welcome. Send an email to "Paul Dowman":http://pauldowman.com/contact/ or to the "Google group":http://groups.google.com/group/ec2-on-rails-discuss. If you find bugs please file them "here":http://rubyforge.org/tracker/?atid=17558&group_id=4552&func=browse or send me an "email":http://pauldowman.com/contact/.
h2. Change log
-See the "change log":http://ec2onrails.rubyforge.org/svn/trunk/gem/CHANGELOG.
+See the "change log":http://github.com/pauldowman/ec2onrails/raw/master/gem/CHANGELOG.
h2. How to submit patches
-Pleae read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/. The source code can be checked out anonymously using:
+Please read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/. The source code can be checked out anonymously using:
<pre>
-svn checkout http://ec2onrails.rubyforge.org/svn/trunk ec2onrails
+git clone git://github.com/pauldowman/ec2onrails.git
</pre>
-Code on Github: "https://github.com/pauldowman/ec2onrails":https://github.com/pauldowman/ec2onrails
-
Patches can be submitted to the "RubyForge Tracker":http://rubyforge.org/tracker/?atid=17560&group_id=4552&func=browse or "emailed directly to me":http://pauldowman.com/contact/ .
+
+h2. Contributors
+
+(In alphabetical order)
+
+"Adam Greene":http://github.com/skippy
+"Arpit Jain":http://github.com/arpitjain11
+"Barry Paul":http://github.com/bpaul
+"Ben Woosley":http://github.com/Empact
+"Chris Nolan":http://github.com/ChrisNolan
+Ed Wagner
+"Mark Lane":http://github.com/DrMark
+"Paul Dowman":http://github.com/pauldowman
+"Pivotal Labs":http://github.com/pivotal
+"Randy Harmon":http://github.com/rjharmon
+"Robert J. Berger":http://github.com/rberger
+"Sebastian Johnsson":http://github.com/Agiley
+(If you've contributed code and you're not listed here I apologize, _please_ send me an email!)
h2. License
This code is free to use under the terms of the GPL v2.