Skip to content

Commit

Permalink
Updated documentation, moved lots of it to the wiki.
Browse files Browse the repository at this point in the history
  • Loading branch information
technicalpickles committed Feb 17, 2010
1 parent 240696a commit 4766878
Showing 1 changed file with 18 additions and 117 deletions.
135 changes: 18 additions & 117 deletions Readme.rdoc
Expand Up @@ -2,133 +2,34 @@

Moonshine is Rails deployment and configuration management done right.

=== Deploying Your Rails Application with Moonshine in 15 minutes
By leveraging capistrano and puppet, moonshine allows you have a working application server in 15 minutes, and be able to sanely manage it's configuration from the comfort of your version control of choice.

==== Requirements
* Step-by-step intsturctions for getting started: http://wiki.github.com/railsmachine/moonshine/step-by-step-instructions
* Managing server configuration with ShadowPuppet: http://wiki.github.com/railsmachine/moonshine/shadow-puppet-overview-and-examples
* Managing gems: http://wiki.github.com/railsmachine/moonshine/add-a-gem
* Managing moonshine.yml: http://wiki.github.com/railsmachine/moonshine/configuring-moonshineyml
* Managing additional Apache vhosts: http://wiki.github.com/railsmachine/moonshine/managing-additional-apache-vhosts
* Moonshine plugins: http://wiki.github.com/railsmachine/moonshine/moonshine-plugins
* Details about capistrano-integration: http://wiki.github.com/railsmachine/moonshine/capistrano
* Rails 3 notes: http://wiki.github.com/railsmachine/moonshine/rails-3

* A server running Ubuntu 8.10 (Want to see your favorite platform supported?
Fork Moonshine on GitHub!)
== Requirements

* A server running Ubuntu 8.10 (Want to see your favorite platform supported? Fork Moonshine on GitHub!)
* A user on this server that can:
* Execute commands via sudo
* Access your application's Git repository

==== Instructions

* Install the plugin: <tt>ruby script/plugin install git://github.com/railsmachine/moonshine.git</tt>
* Ensure all required gems are declared using <tt>config.gem</tt> calls in
<tt>config/environment.rb</tt>.
* Review generator options: <tt>ruby script/generate moonshine --help</tt>
* Run the generator: <tt>ruby script/generate moonshine</tt>
* Review and edit <tt>config/moonshine.yml</tt> to reflect your application's details.
For example, if you're using a user other than <tt>rails</tt>, include a line like <tt>:user: myawesomeuser</tt>
* Review and edit <tt>app/manifests/application_manifest.rb</tt> to declare other packages,
services, or files your application depends on (memcached, sphinx, etc).
* Review and edit your <tt>config/deploy.rb</tt> as necessary. In particular, you must make sure the correct <tt>server</tt> is defined.
* Commit it to git: <tt>git add . && git commit -am "added moonshine" && git push</tt>
* Run <tt>cap deploy:setup</tt>
* This will bootstrap your Ubuntu server with Ruby Enterprise Edition and shadow_puppet.
* Run <tt>cap deploy</tt>
* This will install all needed dependencies for your application and deploy
it for the first time. The initial deploy will take awhile, as things such
as MySQL, etc, are being installed. It's worth the wait though, because
what you end up with is an extremely maintainable server that you'll
never need to SSH into again!

== Moonshine and Capistrano

Moonshine tightly integrates with Capistrano, utilizing its callback system
to apply your manifests to the server on each deploy. In addition, variables
are set in Capistrano for all keys on the <tt>config/moonshine.yml</tt> hash,
allowing your Capistrano configuration to be extremly barebones.

By default, Capistrano applies the manifest at
<tt>app/manifests/application_manifest.rb</tt>. To run a different manifest,
for example one to install and maintain packages on a server of a different
role:

set :moonshine_manifest, 'memcached_manifest'

If you'd like to prevent Capistrano from applying your Moonshine manifests for
any reason:

set :moonshine_apply, false


=== Shared Config

Often, certain files (<tt>config/database.yml</tt>, etc) are excluded from an
application's SCM, but required to be present for deploy. We've abstracted
this pattern with some Capistrano automation that goes great with Moonshine.

For example, if you keep <tt>config/database.yml</tt> out of your SCM, add the
following line to your <tt>config/moonshine.yml</tt>:

:shared_config:
- config/database.yml

This file will then be automatically uploaded when you run <tt>deploy:setup</tt>
and symlinked to <tt>current/config/database.yml</tt> on each deploy.

There are some extra cap tasks for working with these files manually, if needed:

* cap shared_config:upload
* cap shared_config:download
* cap shared_config:symlink

The old <tt>local_config</tt> functionality is still supported, but
<tt>shared_config</tt> is recommended.

== Managing gem dependencies

Moonshine can handle installing your gem dependencies, as well as automatically installing any system dependencies for them. All you need to do is:

* Specify them in <tt>config/environment.rb</tt>
* Run <tt>rake moonshine:gems</tt> to regenerate <tt>config/gems.yml</tt> and commit and push the
* Deploy

For example, if you specify nokogiri as a dependency, both the nokogiri gem and the libxml dependency will be installed.

=== Gem bundler

If you have a Gemfile in your app, then <tt>bundle install</tt> is run for you automatically during deploy. It will also take care of system dependencies of these gems.

Currently, the bundler support will not install system dependencies, pending a rubygems 1.3.6 release. In the interim, you will need to manually specify these in your <tt>application_manifest.rb</tt>. For nokogiri, for example, you'd need this:

def application_packages
package 'libxml2-dev', :before => exec('bundle install')
package 'libxslt1-dev', :before => exec('bundle install')
end
recipe :application_packages

== Rails 3

Moonshine does indeed work with Rails 3. There a few points worth mentioning:

* The generator call would be <tt>rails generate moonshine</tt> instead of <tt>ruby script/generate moonshine</tt>
* Gem bundler is required by Rails 3, so moonshine's gem bundler support will be used
* Rails 3 requires ruby 1.8.7, so Ruby Enterprise Edition 1.8.7 is setup by default
* Rails 3 is Rack based, so Passenger's Rack support is used. Passenger does not support it's smart spawn mode for rack applications yet though. Contrary to some reports, removing <tt>config.ru</tt> will not allow Passenger's Rails support to be used instead of its Rack support, because your application won't be bootable.

If you are upgrading an application to Rails 3, and it is already deployed using moonshine, there are a couple manual things you will need to do:

* Edit <tt>config/moonshine.yml</tt> to use ree187, ie <tt>:ruby: ree187</tt>
* Run <tt>cap ruby:upgrade</tt>

At this point, you should be able to do your usual <tt>cap deploy</tt>
* Access your application's source code repository

== Running Tests

To run the test suite, follow these steps to create a testbed app:
It's easy enough:

rails moonshine_tests
cd moonshine_tests
git clone git://github.com/railsmachine/moonshine.git /vendor/plugins/moonshine
script/generate moonshine
cd vendor/plugins/moonshine
rake test

The tests do not currently run against a Rails 3 app, because of changes made with loading the containing application's environment.

Ginger[http://github.com/freelancing-god/ginger] is used to test against multiple versions of rails:

ginger test

== Getting Help

You can find more examples in the documentation[http://railsmachine.github.com/moonshine] and on the Wiki[http://wiki.github.com/railsmachine/moonshine].
Expand Down

0 comments on commit 4766878

Please sign in to comment.