====== Installing a Rails application ======

Installing a Rails application on Joyent Shared Accelerators involves three steps:

  - Configuring and uploading your application, which is the focus of this article.
  - Deploying your application using [[rails-with-mongrel|Mongrel]] (the preferred way) or [[rails-with-lighttpd|Lighttpd]].
  - And finally, [[proxying|proxying your port]] to a domain.

First, let's get things setup and configured.


===== Adjusting Rails to work on your account =====

If you intend to execute any part of your Rails application via Ruby scripts (e.g. for Cron based automated tasks etc.), you should make sure that the Ruby scripts (such as ''dispatch.fcgi'') contain a correct [[shebang|shebang]] line to the Ruby binary, which is ''/usr/local/bin/ruby''. This where Ruby is located on Joyent's Shared Accelerators and without this change you'll get an error message when you try to start your application.



===== Freezeing Gems =====
It's better to be safe than sorry and freeze your Gems and not rely on the versions installed on the shared accelerator.  Do a checklist of which gems you are using and their versions numbers.
<code>
rails --version
gem list
</code>
Ok so you checked it out and found mismatched and/or missing gems.  
<note important>It is best practice to have all of your required gems installed into your project.  Then you are sure that you are insulated from any changes in the shared environment</note>

==== Need a different version of rails? ====

You want to use the version of rails you have installed on your local machine instead of the version provided.  On your **local machine** run the following command in your project directory
<code>
rake rails:freeze:gems
</code>

==== Need a gem which is not installed? ====
This works for missing and incorrect versions as well.  The exception is a gem which requires native libraries (like RMagick does) you can freeze them into vendor just like rails.  On your **local machine** run the following command in your vendor/gems directory.
<code>
gem unpack GEMNAME
</code>


=== Unpacking Radiant ===

If you're installing a Radiant site, you'll need to use its own Rake task for unpacking/freezing the Radiant gem. On your **local machine** run this from the root of your app:
<code>
rake radiant:freeze:gems
</code>


=== Config/environment.rb ===

Once you've unpacked your gems, add the following to your config/environment.rb file to pull all of the newly added gems into your load_path
<code ruby>
config.load_paths += Dir["#{RAILS_ROOT}/vendor/gems/**"].map do |dir| 
  File.directory?(lib = "#{dir}/lib") ? lib : dir
end
</code>
Note: Using Radiant 0.6.5 this code caused server startup to fail with references to localhosting path. Removing this addition to config/environment.rb worked fine.


===== Getting databases ready =====

In case your application needs a database, you have to create one first:

  * [[manage-mysql#creating-a-mysql-database|Creating a MySQL database]]
  * [[manage-pgsql#create-a-postgresql-database|Creating a PostgreSQL database]]
  * [[backing-up-databases|Backing up and Restoring a MySQL database]]

Some people consider it a good practice to have a separate MySQL user created for their application(s), rather than using the master login. You can learn how to do that here:

  * [[mysql-users]]

<note important>Make sure that your ''database.yml'' file contains correct MySQL access infomation, specific to your Shared Accelerators hosting account (login, password, database name), matching the Rails environment model your Rails application will run in (should always be //production//).</note>

===== Uploading your application =====

Now you need to choose a good location for your Rails application. If you only need a single application running on a domain, the easiest approach is to use the existing ''web'' directory, so that the various ''app'', ''config'', ''db'' etc. directories are stored right under the default ''web'' directory, and the contents of the Rails ''public'' directory goes into the existing ''web/public'' directory. Having only one ''public'' directory simplifies deployment, and staging a localhosted testing version too.

<note tip>To put it simply, if you only have one application for your domain, upload its files into the ''web'' directory of the respective virtual server</note>

Contrary to traditional web hosting technologies (e.g. PHP) and old legacy Rails deployment techniques (e.g. using //mod_fastcgi// to serve your application on Apache), your application does not have to be uploaded into your public directories (i.e. anywhere under your [[document-root]]) since Mongrel (and Lighttpd) will be proxied to from Apache. In fact, uploading your entire Rails application into your document root directory is considered a bad practice since it could potentially expose some sensitive data of your Rails code or configuration.

<note tip>However, it makes sense to keep the Rails ''public'' directory the same as the Apache [[document-root]] directory of your virtual server, if you intend to have static files served by Apache instead of Mongrel (see [[proxying]] for more information).</note>

If you intend to run more than one Rails application per domain (e.g. you want to have two different subdomains proxying to two different applications), you may want to choose a different location. For instance, you might want to create a single ''rails'' or ''sites'' directory in your main account home, and have each Rails application under that in it's own directory (e.g. ~/sites/typo, ~/sites/myapp, etc). Keep in mind that you’ll need to use [[proxying#htaccess-proxy-advanced|.htaccess to proxy]] the sites, and managing ~/web/public/ and the app’s public/ folders becomes more involved.

<note important>When you upload your Rails application, you should lock down the ''config/database.yml'' file for increased security by setting the [[file permissions]] to **600**. This will prevent other users on your account, or someone who has found their way into your account directory structures, from seeing the contents of the file and gaining access to your database.</note>

===== Testing your application =====
Now it's time to prove to your self that you have everything correctly configured to run on the server.  In the example below there is a model called User.  If you do not have a model named User then substitute User with the name of one of your models. 
<code>
cd ~/path/to/rails/application/dir 
script/console production
Loading production environment.
>> User.find 1
=> #<User:0x328bc54  @attributes={}>
</code>
Congratulations you have your database correctly configured.  And all gems in your config/environment.rb file are correctly frozen or already available on the server.  You still might run into some gem issues, but you will see those error messages in your production.log file. 

===== Deploying your application =====

Once your Rails application has been uploaded and configured, you'll now need to to deploy it using either Mongrel (the preferred method) or Lighttpd. Instructions for either approach can be found here:

  * [[rails-with-mongrel]]
  * [[rails-with-lighttpd]]