Getting Started with Ruby on Rails

From DreamHost
Jump to: navigation, search
DreamHost does not directly support any of the features described on this page and is not responsible for keeping this content updated or accurate. Use at your own risk!
There may be additional information on the talk page.


Deploying a simple Rails application is relatively easy, but there are still a number of steps that need to be taken. You need to create your application on your computer, add the domain to your account, create a database for your application in the panel, upload your application to DreamHost's servers, set your domain to use Passenger in the panel, and make sure the version of Rails and any gems you're using are available. These steps will be outlined in this article and should get you well on your way to having your application up and running.

Creating Your Rails Application

To create your Rails application, you'll want to follow these steps (if you already have a Rails application to upload, you can skip this section).

First, you'll need to make sure Rails is installed. To see if this works, run this command from your terminal window:

gem list --local | grep rails

You should see something like this:

rails (3.0.3, 2.3.8, 2.3.5, 2.3.4, 2.3.3, 2.2.2, 2.1.2, 2.1.1, 2.1.0, 2.0.5, 2.0.2)

You may see more versions listed, but so long as it shows up you should be good to go. After confirming that Rails is installed, run this command:

rails new test_app --database=mysql --freeze

That command will generate a new Rails application in the "test_app" folder. The --database=mysql parameter tells it to generate a MySQL database.yml template and the --freeze parameter tells it to freeze the version of Rails you're using to the application, which is always highly recommended. When you run that command, you should see something like this:

$ rails new test_app --database=mysql --freeze
     create  app/controllers
     create  app/helpers
     create  app/models
     create  app/views/layouts
     create  config/environments
     create  config/initializers
     create  config/locales
     create  db
     create  doc
     create  lib
     create  lib/tasks
     create  log
     create  public/images
     create  public/javascripts
     create  public/stylesheets
     create  script/performance
     create  test/fixtures
     create  test/functional
     create  test/integration
     create  test/performance
     create  test/unit
     create  vendor
     create  vendor/plugins
     create  tmp/sessions
     create  tmp/sockets
     create  tmp/cache
     create  tmp/pids
     create  Rakefile
     create  README
     create  app/controllers/application_controller.rb
     create  app/helpers/application_helper.rb
     create  config/database.yml
     create  config/routes.rb
     create  config/locales/en.yml
     create  db/seeds.rb
     create  config/initializers/backtrace_silencers.rb
     create  config/initializers/inflections.rb
     create  config/initializers/mime_types.rb
     create  config/initializers/new_rails_defaults.rb
     create  config/initializers/session_store.rb
     create  config/environment.rb
     create  config/boot.rb
     create  config/environments/production.rb
     create  config/environments/development.rb
     create  config/environments/test.rb
     create  script/about
     create  script/console
     create  script/dbconsole
     create  script/destroy
     create  script/generate
     create  script/runner
     create  script/server
     create  script/plugin
     create  script/performance/benchmarker
     create  script/performance/profiler
     create  test/test_helper.rb
     create  test/performance/browsing_test.rb
     create  public/404.html
     create  public/422.html
     create  public/500.html
     create  public/index.html
     create  public/favicon.ico
     create  public/robots.txt
     create  public/images/rails.png
     create  public/javascripts/prototype.js
     create  public/javascripts/effects.js
     create  public/javascripts/dragdrop.js
     create  public/javascripts/controls.js
     create  public/javascripts/application.js
     create  doc/README_FOR_APP
     create  log/server.log
     create  log/production.log
     create  log/development.log
     create  log/test.log
rm -rf vendor/rails
mkdir -p vendor/rails
cd vendor/rails
mv activesupport-2.3.4 activesupport
mv activerecord-2.3.4 activerecord
mv actionpack-2.3.4 actionpack
mv actionmailer-2.3.4 actionmailer
mv activeresource-2.3.4 activeresource
cd -

At this point, you *should* have a fully functional, vanilla Rails application in your "test_app" directory.

Creating a Database for Your Application

Sqlite is currently the default database for Rails, however this is yet to be supported by Dreamhost. You must switch to MySQL for your application to work correctly.

You'll want to create a database for your application by going to the MySQL Databases area of your webpanel. Scroll to the bottom of the page and fill out the form to create a new database. In a production environment, you would usually have at least a development and production database, but for the purposes of this guide we'll just make a production database. Fill out the form and click the "Add new database now!" link.

Rails create database.jpg

Now that you have a database to use go back to your Rails application and edit the config/database.yml file. Edit the production area with the appropriate information. For the application being setup above, it would look something like this:

  adapter: mysql
  encoding: utf8
  reconnect: false
  database: test_app_prod
  pool: 5
  username: my_rails_user
  password: aFk3!pQ93mw1

Adding the Domain to your Account

Now you want to add the domain to your account via the Manage Domains area of your webpanel.

Rails add new domain.jpg

Just fill out the form like you would for any other domain. Usually the default options will work, although you may want to change the "Do you want the www in your URL?" option to "Leave it alone".

Rails domain settings.jpg

At this point, don't change the web directory path or worry about checking the Passenger checkbox. Just click the "Fully host this domain" button. Note that it may take some time for the domain's DNS to propagate once you add it (this can take anywhere from a couple hours to a couple days depending upon your exact location and ISP).

Uploading Your Application

At this point, your domain is setup and has a web directory on the server. So, you now need to get your application uploaded to the server. Usually, if you're going to be doing a lot of development where you deploy frequently, you'll be using some kind of version control system like Subversion or Git and can use Capistrano to deploy. For the purposes of this guide though, we'll simply upload the application via FTP.

Log into your server via whatever FTP client you use. For the purposes of this guide FileZilla is being used. In the left pane, navigate to your "test_app" directory. Once you get there, select all the files and folders from the left panel and drag them to the folder in the right panel.

Rails filezilla upload.jpg

The upload may take a while since you have the entire Rails framework frozen to your application, so there's quite a number of files. There are lots of more efficient ways of doing this that will be discussed elsewhere, so if you know a better way of doing this, feel free. If you don't, then the above will work fine even if it does take a while.

It will be quicker if you zip the app, upload the single zipfile and then unzip it on the server. Here are some instructions to help you.

Configuring Your Domain to Use Passenger

Now that your application is uploaded, you need to set your domain up to use Passenger so the application will actually run. Go to the Manage Domains area of the webpanel and Edit your domain's Web Hosting options.

The first thing you'll likely notice is that the Passenger option under the Web Options area on the edit page isn't available to check. This is because Passenger needs to have the web directory of your domain point to the public folder inside your application.

Rails domain settings prepassenger.jpg

Since you uploaded the contents of your "test_app" directory to the root of your web directory, just update the web directory field and add a "/public" to the end like this:

Rails domain settings passenger.jpg

Once you've done that click the "Change settings" button. It may take up to 10 minutes or so for this change to go into effect.

Test Your Application

At this point, your application should be up and running! If you browse to it, you should see something like this:

Rails welcome page.jpg

Note that the "About your application's environment" link will display an error if you try clicking it. That's normal. It uses an internal route that Rails disables in production mode, which is what Passenger runs all the applications in. At this point, there's not much to test since no controllers or actions were created, however, if you had created any they would be available to see at this point.

Since this article was just covering getting a basic, vanilla Rails application setup on DreamHost, it doesn't cover getting your gems working. For the most part, simply freezing your gems to your application will do what you need, but a quick spin around Google turns up some common problems, some of which are discussed in the following sections.

Resolving the common mysql2 problem

Now that you've come this far, you'd expect you could do the following:

$ bundle install # NOTE this line in the output: "Installing mysql2 (0.3.11) with native extensions!"
$ bundle package
$ rails generate controller home index

However, you may end up with a WARNING like:

WARNING: This version of mysql2 (0.3.11) doesn't ship with the ActiveRecord adapter bundled anymore as it's now part of Rails 3.1
WARNING: Please use the 0.2.x releases if you plan on using it in Rails <= 3.0.x

To fix this, edit your Gemfile to specify an older version of the mysql2 gem. Edit the line that reads gem 'mysql2' like this:

gem 'mysql2', '< 0.3'

Save and:

$ bundle install # NOTE this line in the output: "Installing mysql2 (0.2.x) with native extensions"
$ bundle package

The "x" in in the preceeding snippet will be whatever the highest available version lower than 0.3 is. (In my case, it's 0.2.18.)

Resolving the dreaded rake 10.0.x problem

Many users run into a problem where the version of rake is not compatible with the other gem versions in the Dreamhost stack by default. When running rake db:migrate, for example, Bad Things™ may happen:

$ rake --trace db:migrate
rake aborted!
ERROR: 'rake/rdoctask' is obsolete and no longer supported. Use 'rdoc/task' (available in RDoc 2.4.2+) instead.
    C:/Programs/Ruby193/lib/ruby/gems/1.9.1/gems/rake-10.0.3/lib/rake/rdoctask.rb:1:in `<top (required)>'
    C:/Programs/Ruby193/lib/ruby/gems/1.9.1/gems/railties-3.0.3/lib/rails/tasks/documentation.rake:2:in `require'

To resolve this, downgrade rake:

$ gem install rake -v 0.8.7
$ gem uninstall rake -v 10.0.3

Then, edit your Gemfile.lock. Change the rake line to read like this:

rake (0.8.7)

Then, carry on:

$ bundle install
$ bundle package
$ rake --version
rake, version 0.8.7

Hope this helps!