ASOwiki: Pre-requisites

So you have developed an application and are ready to deploy it for the world to see? Standard deployment is relatively simple on A Small Orange's shared plans. You may also want to consider Capistrano∞.

Pre-requisites

First and foremost, you will need SSH. You need to create a support ticket for your account to get it enabled. In this tutorial, we will use the "ssh" command-line utility (which comes bundled with most Unix-like systems). There are some Windows applications available as well.

File upload

Second, we are going to use a utility called "scp" that uses the SSH protocol to transfer files. The following commands will transfer a directory called "myapp" to your account in a folder called "myapp" (where "username" is your ASO account username and "example.com" is your domain).

~
scp -r myapp/ username@example.com:

After some time, it will complete. Now:

ssh username@example.com

Enter your password.

Database initialisation

At this point, if you have not set up your MySQL database on ASO, you should do that now. You have to create a database, user, and password on your cPanel (accessed at http://example.com/cpanel∞). Now back at the terminal let's update the config file:

~/myapp/config/
nano database.yml

And update the data under "production:" to reflect the database and user you created.

If you developed on Windows

You probably developed (and generated) your application locally. Because of this, the path to Ruby will be incorrect for the ASO server. To fix this:

~/myapp/public/

Now run the "nano" command and edit the following files:

dispatch.cgi
dispatch.fcgi
dispatch.rb

In each of the files, change the first line to:

#!/usr/local/bin/ruby

You must also ensure that these files are executable. (I believe Windows uses the executable bit to mark archive status. This means you can't be sure your files will have correct executable status after they've been copied from Windows.)

So, run the following command (while you are still in ~/myapp/public/):

chmod  x dispatch.cgi dispatch.fcgi dispatch.rb

Permissions

Ruby on Rails won't start if your source code is write enabled for anyone other than you.

ls -lh myapp
drwxrwsrwx  14 me mygroup 4.0K Aug 23 08:39 myapp/

That second 'w' means that group writing is enabled. While the third 'w' indicates that anyone can write to myapp/. Rails will refuse to start if either of these are set, so we must turn them off:

chmod -R go-w myapp

This will remove (-) write permissions (w) from myapp/ and all subdirectories (-R) for groups (g) and other users (o).

Database update

Now our application is on the server, but the database isn't set up/up to date. To do this:

~/myapp
rake environment RAILS_ENV=production

This will use the database migrations to create the database and set the Rails environment to production. Just to be sure, however:

config/
nano environment.rb

And remove the comment before the line:

ENV['RAILS_ENV'] ||= 'production'

Linking to public_html

Finally, we uploaded the application to the directory ~/myapp. However, when a request is made to the server, you can only actually see requests in ~/public_html directory. You should NEVER upload your application to the public_html directory. Instead, we create a symbolic link:

~
ln -sf ~/myapp/public ~/public_html/myapp

This would create a symbolic link between your applications public directory and the /myapp directory on your domain. So, now, to view your application, you would go to http://example.com/myapp∞. If you wanted it to be just at http://example.com∞, you would have to create a symbolic link with public_html. So instead of the last command, you would do (THIS WILL DELETE ALL OF YOUR public_html CONTENTS):

~
rm -rf ~/public_html
ln -sf ~/myapp/public ~/public_html

Now there isn't actually a directory called "public_html", but instead it is a link to ~/myapp/public. So by now your application is up and running. Wonderful! However, you probably noticed that it is rather slow. That is because it is using standard CGI. Now that you can see your application is working fine, you can switch to FastCGI:

~/myapp/public
nano .htaccess

You should search for ".cgi" in this file and replace it with ".fcgi". At the time of this writing, this line:

RewriteRule ^(.*)$ dispatch.cgi [QSA,L]

Is replaced with:

RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]

Now if you load your application, it will probably take a few seconds for the FastCGI process to start-up. After that, though, it will load faster.

A note on updating your application

When you update your application (a.ka. upload updated files), the chances are that there will still be a FCGI process running. To fix this, you need to kill off the process to force it to re-load your updating application. First, lets search for any FastCGI processes:

technel@cindy [~/myapp]# ps aux | grep fcgi
32041    14746  0.0  1.4 62840 29640 ?       S    Sep07   0:00 /usr/local/bin/ruby dispatch.fcgi
nobody   14557  0.0  0.6 261004 13248 ?      S    17:31   0:00 /usr/local/apache/bin/fcgi- -DSSL
technel   5656 15.5  1.6 69876 34632 ?       S    19:32   0:01 /usr/local/bin/ruby dispatch.fcgi
technel   5682  0.0  0.0  3728  552 ?        S    19:32   0:00 grep fcgi

We need to kill the process owned by us (technel). There are two processes owned by us listed there. The last one is just the "grep" command we ran to filter the processes. So we just need to kill the process 5656. (Note that the PID (process id) is the second number displayed.)

kill 5656

Now when you load your site, it will take a few extra seconds, but your updated will be live!

Congratulations, you have successfully deployed a Rails application on A Small Orange!

: RubyOnRailsDeployment