technicalpickles edited this page Aug 26, 2012 · 14 revisions

This guide provides basic, step-by-step directions on getting Moonshine installed and configured for your Rails 2.x or 3.x application. We strongly recommend following these steps in order.


We'll preface commands to run on your local machine like so:

rm@macbook:~$ some command

And we'll preface commands to run on your server like so:

rails@blackbox:~$ some command

And we'll make blocks of text (either output or contents of a file) like so:

Look at me! I'm a big ol' block o' text!

Aren't I great?

Initial Server Setup

You'll need an Ubuntu server or machine to get started. After the basic install you'll need to run a few commands to get the box ready. If you're a RailsMachine customer, you should be able to skip to the next section (titled 'Adding Moonshine...') as we put your SSH key(s) on the server for you.

First, log into your server via SSH and reset your root password:

rm@macbook:~$ ssh root@

root@blackbox:~$ passwd

NOTE Replace with the IP of your server everywhere you see it.

Add a new user called rails and give it a password:

root@blackbox:~$ adduser rails

and give it sudo pemissions:

root@blackbox:~$ visudo

In that file, add this line below "root ALL=(ALL) ALL"

rails   ALL=(ALL) ALL

Or optionally, if you don't want to have to enter the rails user password every time you deploy:


On your local machine, run:

rm@macbook:~$ test ! -f ~/.ssh/id_rsa.pub || echo "SSH key has already been generated!"

If you do not see a message saying that the SSH key has already been generated, you'll need to run the following command:

rm@macbook:~$ ssh-keygen -t rsa

Next, we're going to copy your public key to your server so you can securely connect to it without having to enter your password.

There are two ways to accomplish this step.

Again on your local machine, run:

rm@macbook:~$ ssh-copy-id rails@

Command ssh-copy-id should be available on most of modern system, but if its not, here are the steps you have to take, in order to copy your public key to your server. Follow next 7 steps if ssh-copy-id failed or is unavailable.

On your local machine, run:

rm@macbook:~$ scp ~/.ssh/id_rsa.pub rails@

rm@macbook:~$ ssh rails@

Now on your server, run these:

rails@blackbox:~$ mkdir /home/rails/.ssh

rails@blackbox:~$ tee -a my_key.pub /home/rails/.ssh/authorized_keys

rails@blackbox:~$ sudo chown -R rails:rails /home/rails/.ssh

rails@blackbox:~$ sudo chmod 700 /home/rails/.ssh

rails@blackbox:~$ sudo chmod 600 /home/rails/.ssh/authorized_keys

Now your keys should be in place.

Let's make it easy to connect with your server. On your local machine, open ~/.ssh/config file with any text editor (Textmate, Emacs, Vim, etc) and add your information using the template below:

Host blackbox
  User rails

Don't forget to change your IP as well as pick a name for your server that makes sense.

Save & close that file. Now you should be able to connect to your server by just typing:

rm@macbook:~$ ssh blackbox

Okay, we've got one final thing we need to get your initial server setup - give your server access to your github account (you may or may not store your application's code on github, but we do recommend it).

Once you've ssh'd into your server as the rails user, generate your ssh key similar to how to you did it on your local machine:

rails@blackbox:~$ ssh-keygen -t rsa

It will ask you if you want to give it a password. For ease of use, you should just leave the password blank here. When you're done, you want to output the public key it generates by running this:

rails@blackbox:~$ cat /home/rails/.ssh/id_rsa.pub

Copy the key that is printed out and enter it into your github account which you can usually do on "your account page":https://github.com/account.

Adding Moonshine to your Application and Doing Initial Configuration

In this step, you'll add the moonshine plugin to your project and configure it properly so it knows what you want it to do on your server.

On your local machine, go to your rails project directory and add the plugin:

For Rails 2:

rm@macbook:~$ ruby script/plugin install git://github.com/railsmachine/moonshine.git

For Rails 3:

rm@macbook:~$ rails plugin install git://github.com/railsmachine/moonshine.git

If you are using Rails 2 with out bundler, make absolutely sure all the gems you are using are listed out in your config/environment.rb or config/environments/*.rb files!

If you are using bundler, it will take care of installing your gems.

Next, run the moonshine generator to create the necessary files:

For Rails 2:

rm@macbook:~$ ruby script/generate moonshine

For Rails 3:

rm@macbook:~$ rails generate moonshine

This should make an output like this:

After the Moonshine generator finishes don't forget to:

- Edit config/moonshine.yml
Use this file to manage configuration related to deploying and running the app: 
domain name, git repos, package dependencies for gems, and more.

- Edit app/manifests/application_manifest.rb
Use this to manage the configuration of everything else on the server:
define the server 'stack', cron jobs, mail aliases, configuration files 

      create  app/manifests
      create  app/manifests/templates
      create  app/manifests/application_manifest.rb
      exists  app/manifests/templates
      create  app/manifests/templates/README
      exists  config
      create  config/moonshine.yml
      create  config/gems.yml

As the output suggests, the next thing you should do is edit config/moonshine.yml

Editing Moonshine.yml

First give your app a name (such as your_app_name), pick where the files of your app will reside (by setting deploy_to) & tell moonshine where to grab your application from (by setting repository)

:application: your_app_name
:deploy_to: /srv/your_app_name
:repository: git@github.com:username/your_app_name.git

Note: if you are using subversion you will want to add the following:

:scm: subversion
:scm_username: svnuser
:scm_password: svnpass

Next, if your app has directories in the public directory that need to stay persistent, uncomment this:

  - uploads

If you don't, the files will be removed every time you deploy since it gets the files from your git repo and they won't be there.

You'll also probably want to uncomment the shared_config section, which will upload your local copies of certain files to the server. This is useful for any files you need to get on the server but don't want to keep in version control.

  - config/database.yml

For more information on how the shared_config system in Moonshine works, see Shared Configuration Files.

Now save the file and run (required only for Rails 2 projects):

rm@macbook:~$ rake moonshine:gems

This command reads in your application's environment and creates a file at config/gems.yml which Moonshine uses to satisfy the dependencies of your application. Note that if you have certain gems only included in a particular environment, for example the 'production' environment, you may need to prefix the command with RAILS_ENV=production or whatever environment applies.

For other configuration options, take a gander at our documentation on Configuration.

Editing the Application Manifest

The application manifest is where all of the real customization of your server happens. Here you can define packages and gems to install, cron jobs, log rotation, mail aliases, configuration files, and more.


The file that is generated uses the 'default_stack' recipe. What this means is it will install Apache, Passenger, Rails, NTP, Cron, Postfix and whichever database you specified in database.yml: MySQL, Postgres, or sqlite (if you use mongodb or other databases, we have Moonshine plugins for them). For most applications, the default will work fine. Take a look at vendor/plugins/moonshine/lib/moonshine/manifest/rails.rb to see if you'd prefer to customize your base stack.


Moonshine plugins allow you to easily add on to capabilities of your manifest. Here's an example of setting up SSH on an alternate port and firewalling the system with iptables.

First, install the plugins:

rm@macbook:~$ ruby script/plugin install git://github.com/railsmachine/moonshine_iptables.git

rm@macbook:~$ ruby script/plugin install git://github.com/railsmachine/moonshine_ssh.git

Now add these lines to your application manifest:

  :ssh => { :port => 2222, :allow_users => ['rails'] },
  :iptables => { :rules => [
      '-A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT',
      '-A INPUT -p icmp -j ACCEPT',
      '-A INPUT -p tcp -m tcp --dport 25 -j ACCEPT',
      '-A INPUT -p tcp -m tcp --dport 2222 -j ACCEPT',
      '-A INPUT -p tcp -m tcp --dport 80 -j ACCEPT',
      '-A INPUT -p tcp -m tcp --dport 443 -j ACCEPT',
      '-A INPUT -s -j ACCEPT',
      '-A INPUT -p tcp -m tcp --dport 8000:10000 -j ACCEPT',
      '-A INPUT -p udp -m udp --dport 8000:10000 -j ACCEPT'
recipe :iptables
recipe :ssh

After you deploy your application with the above settings, SSH will be listening on port 2222. If you do this, be sure to update your ~/.ssh/config to specify the new port:

Host blackbox
  User rails
  Port 2222

You don't need to update this until after your first deployment since it's still listening on the default SSH port until then.

Additional configuration

The application_packages method is a good place to define the custom components and configurations for your server if they're not extensive or common enough to warrant making a Moonshine plugin. There are tons of examples in the comments, and more on the Shadow Puppet overview page.

Bootstrap rake tasks

Moonshine allows you to define a rake task called moonshine:app:bootstrap that will be run after the first deployment. Create a rake file - lib/tasks/bootstrap.rake, for example - and add the task there:

namespace :moonshine do
  namespace :app do
    task :bootstrap do
      # define your bootstrap task here

Bootstrap data

If you need to load initial data into your application, add fixture files for this data into db/bootstrap.

Capify your project

Once you've got your application configured, capify your app by running the following code while inside your rails app directory:

rm@macbook:~$ capify .

Now open config/deploy.rb and replace its content with this:

server "blackbox", :app, :web, :db, :primary => true

Be sure to replace blackbox with the name you give your server in your ~/.ssh/config file.

Next, commit your changes to your repository and if necessary push them to your remote repository (svn commits do this by default; git requires a push).

An example using git:

rm@macbook:~$ git add . && git commit -am "added moonshine" && git push

And an example using svn:

rm@macbook:~$ svn up && svn add . && svn ci -m "added moonshine"


Once all the configuration is done, you'll get to see the fruits of your labor.

First thing you'll need to do is set up the server. From your rails app root, run this:

rm@macbook:~$ cap deploy:setup

Once that is done, run this:

rm@macbook:~$ cap deploy

That's it! You should be good to go now. And if you're in the market for managed hosting, particularly for your Rails apps, definitely check out RailsMachine, creators of moonshine!


We get a few questions from time to time. Here's a short list of some of the most commons ones.

Is there a way I can get detailed outputs for errors?

There sure is! Simply take a look at our page on Debugging to get more detailed output from the deployment process.

What about gems that I've got in the vendor/gems folder?

One approach that works is to manually go into the config/gems.yml file and remove the gems that are in vendor/gems/, though we heartily recommend using Moonshine's built-in facilities as much as possible.