So, you've 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.
Note: we use Ruby with Passenger while cPanel uses Ruby with Mongrel, so the cPanel Ruby app is not available.
First and foremost, you will need SSH. 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 (such as PuTTY) available as well.
Freezing Your App
If you've developed your app locally, you'll want to freeze your gems before you upload it. This means your code will run against the same gems you have installed on your computer, and not whatever version happens to be installed on ASO's servers. Make sure to keep your app's gems up to date with security fixes and such as time goes on.
cd ~/myapp rake rails:freeze:gems
You can use a utility called SCP that uses the SSH protocol to transfer files:
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) using the following commands:
scp -r myapp/ firstname.lastname@example.org:
After it completes:
- Enter your password
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 update the config file:
And update the data under 'production:' to reflect the database and user you created. In the database name and username include your account name prefix.
For example: if your account name is 'chiefwiggum' and you made database called 'perpetrators', the you'll type the database name 'chiefwiggum_perpetrators' into the database.yml file.
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/
Note: 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 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).
Now our application is on the server, but the database isn't set up/up to date. To update the database:
rake db:migrate RAILS_ENV=production
This will use the database migrations to create the database and set the Rails environment to production. Just to be sure, complete this:
And remove the comment before the line:
ENV['RAILS_ENV'] ||= 'production'
Note: for Rails 2.3.3 and above this line will not appear at all in environment.rb. You'll need to add it at the top of the file.
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. 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:
Note: 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.
If you're running your app out of a subdirectory of your site update the .htaccess file to use mod_rails/Passenger which ASO uses for running Rails apps. Add this line into the .htaccess file in your app's 'public' directory:
Note: you don't need to do this if you're replacing 'public_html'. 'mod_rails' will see the app automatically.
You will probably want to leave the existing contents of the .htaccess, as there might be custom rewrite rules in there for particular URLs used by the application. 'mod_rails' will override any use of FastCGI or CGI in the file.
Important Note About Updating Your Application
When you update your application the chances are that there will still be a 'mod_rails' process running. Restarting is very simple. Just upload a blank file named restart.txt into '~/myapp/tmp/'. 'mod_rails' looks at the time when the file was last updated and will restart your application if that file is newer than when it started your app. Any time you need to restart the application, simply upload the blank restart.txt file again to update it's timestamp.
You can also upload a blank always_restart.txt file into the 'tmp' directory and will always restart your application on every request. However, this will cause a significant performance degradation so only use it for debugging.
Congratulations, you have successfully deployed a Rails application on A Small Orange!
Deploying an Existing Rails Application to ASO Notes
These notes are for a Rails application that used MySQL and was developed on a Windows operating system. Follow the directions above with the following modifications:
Make sure to develop on the same version of Rails as is running on ASO, or at least qualify the app on the same version.
The cPanel Rails applet does not work and does not do the right thing. It creates the whole application in the 'public_html' folder. Do not use it.
Do not use 'db' migrations. Instead setup the MySQL database first through the cPanel applet '/ phpAdmin' import the schema. Comment out of the schema 'create database' and 'use database' commands in order to run the import script successfully, as they are not available in the shared environment on ASO.
The schema and the username created on ASO is automatically prepended with your ASO username and you need to take this into account when you edit the database.yml.
Create a Rails skeleton on ASO, using:
rails -d mysql myapp
Without '-d mysql' it creates a database.yml for SQLite, so it saves a little editing.
You can change the permissions to 600 on database.yml and install the plugins you need. The below example shows the install for the 'will_paginate' plugin, which is pretty much required since they took the paginator out of Rails 2.0. It may be possible to copy plugins from your deployment sources, however, you may want to minimize any possible problems deploying the application.
script/plugin source svn://errtheblog.com/svn/plugins
script/plugin install will_paginate
Edit the 'environment.rb' to comment out the line setting the 'RAILS_ENV' to production since I was not running the script described above.
Then deploy MyApp:
copy everything in app
copy files I created or modified in public
copy files I created or modified in 'config/initializers'
merged changes in 'config/routes.rb'