Step-by-step setup using Capistrano 2.0 and Mongrel
From OCS Support Wiki
Contents |
Introduction
You've developed the next killer Ruby on Rails application. You've signed up for an account with OCS. Now what? This guide will take you step-by-step through setting up your website on the OCS server. By the end, you will have a production site that can easily be updated at any time. We will be using Capistrano 2.0 to automate all of our deployment needs, and a single Mongrel process for serving the application.
Assumptions
This guide makes a lot of assumptions about your working environment. You can still follow it even if you're not, but heads up that some commands may need tweaking.
- You are developing a Ruby on Rails application (this guide was written using Rails 1.2.3)
- You have been using Subversion all along, with the normal branches/tags/trunk format
- Your local machine (the one you're developing on)...
- is running either Mac OS X or some variety of Linux.
- has RubyGems installed.
- You have a shared hosting account with OCS Solutions, using Webmin, and one domain name.
Local Preparations
Set up SSH access
To make deployment easy, Capistrano will log into the OCS server for you and run a lot of commands. You can, if you want, type your password in every time. The much easier, but still just as secure, way of doing it is by Generating an SSH key. Unless you have incredibly special circumstances, you will want to do this step.
Install Capistrano
If you do not yet have Capistrano 2.0 installed on your local machine, make sure to do it now with the command:
sudo gem install -y capistrano
Server-side Preparations
Request a Port
You will need a port for Mongrel to listen on. If you haven't done so already, please see the guide on Requesting a Mongrel or Lighttpd Port. The port typically starts with 60, like 60040, for example.
Once you've gotten the response email that tells you what port number you have, write it down. We will use 60040 through-out this guide as an example, but it is critical that you always use your assigned number.
Cache the SVN credentials
Every time you deploy a new version of your website with Capistrano, it checks out a new version from your Subversion repository. To make this process work, you've got to first manually check it out on the server. That way, the credentials used are cached so that you won't run into problems later.
First, log into your remote server via SSH. If you do not yet have a folder called "rails_apps", make it now.
mkdir rails_apps cd rails_apps
Now, checkout a copy of your trunk. If the username needed to access the repository is different than your account username on the OCS server, specify explicitly what it should be.
svn co --username USER http://svn.yourdomain.com/path/to/repo/trunk
Let it run until the entire thing is checked out, then delete the folder
rm -rf trunk/
Capify your Application
Now you need to add Capistrano support to your application. On your local machine, open a terminal window and navigate to the root of your application folder (i.e. where you can run rake tasks, etc). Enter the following:
capify .
Customize your Deployment Recipe
The next step is to customize the config/deploy.rb file that Capistrano added to your app. Open it up in your favorite editor and change it to look roughly like the following. Be sure to change the values to match your setup!
abort "needs capistrano 2" unless respond_to?(:namespace)
# =============================================================================
# REQUIRED VARIABLES
# =============================================================================
set :application, "website_name" # CHANGE THIS LINE TO USE YOUR WEBSITE'S NAME
set :repository, "http://svn.yourdomain.com/path/to/repo/trunk" # CHANGE THIS LINE TO USE YOUR SVN REPO
# =============================================================================
# ROLES
# =============================================================================
role :web, "yourserver.ocssolutions.com" # CHANGE THESE LINES TO USE YOUR OCS SERVER NAME
role :app, "yourserver.ocssolutions.com"
role :db, "yourserver.ocssolutions.com", :primary => true
# =============================================================================
# OPTIONAL VARIABLES
# =============================================================================
set :deploy_to, "/home/username/rails_apps/website_name" # CHANGE THIS LINE TO POINT TO THE CORRECT PATH
set :user, "username" # CHANGE THIS LINE TO USE YOUR OCS USERNAME
set :use_sudo, false
set :deploy_via, :export
set :port_number, "60040" # CHANGE THIS LINE TO USE YOUR ASSIGNED PORT NUMBER
# =============================================================================
# TASKS
# =============================================================================
namespace :deploy do
task :start, :roles => :app do
run "cd #{deploy_to}/current; mongrel_rails start -e production -p #{port_number} -d"
end
task :stop, :roles => :app do
run "cd #{deploy_to}/current; mongrel_rails stop"
end
task :restart, :roles => :app do
run "cd #{deploy_to}/current; mongrel_rails stop; mongrel_rails start -e production -p #{port_number} -d"
run "echo \"WEBSITE HAS BEEN DEPLOYED\""
end
after "deploy:update_code", :link_production_db
end
# database.yml task
desc "Link in the production database.yml"
task :link_production_db do
run "ln -nfs #{deploy_to}/shared/config/database.yml #{release_path}/config/database.yml"
end
Setup the remote directory structure
Thankfully, getting the remote server set up is something that Capistrano can handle for you. Once you have your deploy recipe setup, type this command on your local machine:
cap deploy:setup
This will automatically log into the OCS server, create a new folder with the name you specified under set :deploy_to, and in there, create the folders "releases" and "shared".
Now, log back into the OCS server using SSH, so that you can do a little extra work. We need to create your server-side database.yml file.
cd rails_apps/website_name/shared mkdir config touch config/database.yml nano -w config/database.yml
You should now have your new, server-side database.yml file open for editing in Nano. Copy in the following, adjusting for your own setup. Press Ctrl-X to exit, then y and Enter to save the file.
production: adapter: mysql database: <database_name> username: <ocs_username> password: <ocs_password> socket: /var/run/mysqld/mysqld.sock
Deploy Your Website
If you've followed the instructions so far, you should now be ready to deploy the first version of your application. On your local machine, type the following:
cap deploy:cold
Give it a minute or two to run. If all went well, you should see something like this:
[server.ocssolutions.com] executing command
** [out :: server.ocssolutions.com] WEBSITE HAS BEEN DEPLOYED
command finished
If the end of the command looked much different from that, you've got a bug somewhere and need to go back and tweak. If you did get that message, let's move forward.
Test your Deployed Website
Before we go any further, you should make sure that Mongrel is serving up your website correctly. Open a web browser and go to http://yoursite.com:60040 (where yoursite.com is your website, and 60040 is the port you are assigned) and you should see your Rails application. If you have not yet transfered your website to us, you can use http://servername:60040, where servername is the name of the server from your welcome letter (for example, if you were on the Zeus webmin server, your URL would be http://zeus.ocssolutions.com:60040).
If your website shows up correctly, congratulations! You've done it! Only a few more steps and you'll be able to kick back and relax.
Setting Up a Proxy For Your Site
You probably don't want to reference your site by port number for anything other than testing. To have your website go to your Rails app without the port number, please see How to Proxy Your Mongrel to Your Website.
Starting Your Application on Reboot
Once you have your Mongrel instance running, you'll want to make sure it gets started again if the server has to reboot. To do this, see the guide Starting Your Application At Boot.
Troubleshooting
If you are having trouble getting your Mongrel instance to start, see the guide Troubleshooting a Ruby on Rails Application.
Credits
This article was put together by Marc Leglise, a private Rails developer, for the OCS wiki. It borrows a lot from related articles on this same site, as well as documentation from countless other places.
