-
Notifications
You must be signed in to change notification settings - Fork 69
Tutorial
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?
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 [email protected]
root@blackbox:~$ passwd
NOTE Replace 123.123.123.123 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:
rails ALL=NOPASSWD: ALL
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 [email protected]
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 [email protected]:/home/rails/my_key.pub
rm@macbook:~$ ssh [email protected]
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
Hostname 123.123.123.123
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.
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
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: [email protected]: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:
:app_symlinks:
- 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.
:shared_config:
- 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.
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:
configure({
: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 127.0.0.1 -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
Hostname 123.123.123.123
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.
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.
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
end
end
end
If you need to load initial data into your application, add fixture files for
this data into db/bootstrap.
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.
There sure is! Simply take a look at our page on Debugging to get more detailed output from the deployment process.
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.