Moonshine¶ ↑

Moonshine is Rails deployment and configuration management done right.

Deploying Your Rails Application with Moonshine in 15 minutes¶ ↑

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¶ ↑

ruby script/plugin install git://github.com/railsmachine/moonshine.git
Ensure all required gems are declared using config.gem calls in config/environment.rb.
ruby script/generate moonshine
Edit the configuration file at config/moonshine.yml with your apps’s details. (If you’re using a user other than rails, specify this here)
Edit the Moonshine::Manifest::Rails manifest generated for your application at app/manifests/application_manifest.rb to declare other packages, services, or files your application depends on (memcached, sphinx, etc).
capify your application
- Your config/deploy.rb can be super barebones, as Moonshine loads the contents of config/moonshine.yml in as Cap variables and sets some sane defaults. Here’s what I use:
```
server "myubuntuserver.com", :app, :web, :db, :primary => true
```
git add . && git commit -am "added moonshine" && git push
cap deploy:setup
- This will bootstrap your Ubuntu server with Ruby Enterprise Edition.
cap deploy
- 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 config/moonshine.yml hash, allowing your Capistrano configuration to be extremly barebones.

By default, Capistrano applies the manifest at app/manifests/application_manifest.rb. 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 (config/database.yml, 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 config/database.yml out of your SCM, add the following line to your config/moonshine.yml:

:shared_config:
  - config/database.yml

This file will then be automatically uploaded when you run deploy:setup and symlinked to current/config/database.yml 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 local_config functionality is still supported, but shared_config is recommended.

You can also specify a local file:

set :local_config { 'local_folder/database.yml', 'config/database.yml' }

If the local file is missing, the upload is skipped and it is symlinked to the shared folder file.

Multisite¶ ↑

I (Andrew Roth) added multisite support. This is useful if you have a suite of web applications that you want to install to one or more servers. It also uses capistrano-ext for stage support.

For example, suppose you had a web app “app1” and stages “dev”, “prod” and domains “foo-domain.com” and “bar-domain.com”. You would have:

config file moonshine_multisite.yml in the moonshine_multisite plugin directory.
shortcuts “foo” and “bar” to refer to those servers
four stages: foo/dev, foo/prod, bar/dev, bar/prod
cap foo/dev deploy, cap foo/prod deploy tasks (same with deploy:setup)

The process is:

github fork this repository
use moonshine_multisite.simple.yml to make a moonshine_multisite.yml with your own stages and server info. You will choose a short “app identifier” for each app and “host identifier” for each server.
install capistrano-ext

sudo gem install capistrano-ext

in each of your sites, install your moonshine_multisite

ruby script/plugin install git://github.com/your_username/moonshine_multisite.git

in your applications, make a new branch for each host and stage with the name <host identifier>.<stage>. For example, branches abc.dev, abc.prod if you have a host identifier abc and stages dev and prod. Make sure these branches have moonshine_multisite and capistrano-ext.

to deploy the first application, run

cap <host identifier>/<stage> deploy:setup
cap <host identifier>/<stage> deploy

to deploy more sites to the server, don’t run deploy:setup again, as that will compile ruby enterprise edition again. Instead, run
```
cap <host identifier>/<stage> moonshine:setup_directories
cap <host identifier>/<stage> deploy
```

TODO: provioning rake task, database setup/copying/downloading

Running Tests¶ ↑

To run the test suite, follow these steps to create a testbed app:

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

Getting Help¶ ↑

You can find more examples in the documentation and on the Wiki.

For help or general discussion, visit the Moonshine newsgroup.

andrewroth/moonshine_multisite