As step 1 of my latest experiment, I’ve started by configuring a Ruby on Rails site with DreamHost. This actually involved quite a bit of setup work, which is not unusual when remotely hosting a new website. I have documented the steps as fully as I can for anyone else curious about trying development in Rails.
Step 1 – Signup with DreamHost
You can sign up using this link or use the promo code LETMETRYRAILS and receive $50 off (i.e. no setup fee).
Step 2 – Configure your domain
The next step is to configure your domain. We’ll start at the DreamHost configuration panel. Select Domains and then Manage Domains from the left-hand sidebar. This will bring up the list of domains in your account. Click the Edit button in the Web Hosting column.
This will open the settings page for that domain. Check the FastCGI and Passenger (mod_rails) checkboxes. Finally click the Change fully hosted settings now! button (note that this button is not at the bottom of the page, rather at the end of the first section).
FastCGI support allows your Rails project to run much faster. The Passenger (mod_rails) option allows your Rails application to be configured much more easily and is the preferred DreamHost method for hosting Ruby on Rails applications.
Step 3 – Configure your FTP/SSH user
We will be performing much of the setup and configuration of the website via SSH. We will need to setup a user account for this purpose. During your initial setup you should have created an ftp account for your domain, probably with the same name as that domain (if you accepted the defaults). Select the Users and then Manage Users options from the left side-bar. Click the Edit button next to your user in the Actions column.
This will open the following page where you can edit your user. Change the User Account Type to Shell account and select the /bin/bash shell type. Finally, hit the Save Changes button at the bottom of the page.
This enables the user to connect using a Telnet/SSH client, which is exactly what we are going to do next.
Step 4 – Download some tools
Next we’re going to download the tools we’ll need to create and configure our rails website. We’ll need the latest release of Ruby, MySQL, HeidiSql, and PuTTY. HeidiSql is a free gui for maintaining MySQL databases. PuTTY is a free Telnet/SSH client that we’ll use for remote configuration of our site. Note that you do not need to signup on the MySQL site to get the download. Click the No thanks, just let me download link.
Step 5 – Installing Rails
Now that we have the necessary tools installed it is time to setup Rails locally. Fortunately, Ruby comes with everything we need to get setup and running, including the WEBrick web server that we can use to run and test our site before deployment. When installing Ruby, be sure to check the Enable RubyGems option on the first page of the installer.
Once the installer completes, open up a command window and execute the following commands:
cd ruby/bin
gem update –system
gem install rails –version 2.1.2
This will use the gem system to install rails locally. If everything is successful, your command window should look something like this:
You may need to restart your system at this point. Ughh. This is because Windows Vista and XP sometimes struggle to detect that new environment variables were added to the $PATH. Unless you relish fully qualifying the C:/Ruby/bin directory on the next few commands, I’d advise you restart now. It’s also not a bad idea since we did just install four new programs. I’ve found Windows seems to run more smoothly if you reboot after installing new things.
Step 6 – Create your Rails site locally
Now that we have Rails setup, let’s create a simple site locally. I created a new directory on C:\ called projects in which to develop the site. Open a command prompt and type the following:
cd \
md projects
cd projects
rails MyRailsSite
This will create your rails site in C:\projects\MyRailsSite. Before we add our first view and controller, let’s quickly check that everything wired up properly. To do this we need to start the WEBrick server:
cd C:\projects\MyRailsSite
ruby script/server
Vista may ask if you wish to unblock Ruby, which you do. Your command prompt should look something like the following:
You can now navigate to http://127.0.0.1:3000 to see your site. If everything is configured correctly you should see the Ruby on Rails welcome page:
We can shutdown the WEBrick server by pressing Ctrl-C in the command prompt window.
Now let’s create our first controller and view. We’re going to keep it simple and put up a page that displays the message “Hello World!”. At the command prompt type the following:
cd projects\MyRailsSite
ruby script/generate controller HelloWorld
This will generate a new controller for you as well as a new view. If you aren’t familiar with MVC development, just follow along for now until the sample becomes clear. The rest will come in time and with additional reading and practice. For now it is suffice to say that a controller will perform the work for a web page request where the view will display the results of that work.
Let’s edit the controller that was generated. To do this, open up an explorer window, navigate to C:\projects\MyRailsSite\app\controllers, right-click over the hello_world_controller.rb file and select Edit from the context menu. This should open the controller file in the SciTE editor. We need to add lines to the class to respond to the index action. The index action is the default action that will be performed for a controller. To do this, edit the file to look like the following:
This controller will now set the variable @message to the literal “Hello World”; when the index action is requested. Controllers perform actions.
Save the file and close it. Now we will create a view to display the message. Navigate to the C:\projects\MyRailsSite\app\views\hello_world directory in explorer (notice how Rails created the view directory for us). Right-click in the directory and create a new file called index.html.erb. Now right-click this file and open it in your favorite editor (Notepad will suffice). Add the following to the file:
Save the file and close the editor. We’re almost ready to test out our new controller and view. First, however, we need to configure a route for our site. A route is a mapping from an end-point (url) in our site to an actual controller and view that will fulfil the request. In explorer, navigate to C:\projects\MyRailsSite\config, right-click the file routes.rb and select Edit from the context-menu. This will open your routes file in the SciTE editor. Almost the entire file is commented out. Most of this file contains instructions for configuring custom routes. We’re going to comment out the last two lines of the file and insert a single mapped route of our own. Edit the end of the file to look like the following:
This line connects the helloworld route to the hello_world controller for the index action. The action specification isn’t actually necessary as the index action is assumed by default if none is specified, but I prefer to be explicit.
There is one final thing we’ll need to do before we can browse to our page locally. We need to install and configure MySQL.
Step 7 – Install and configure MySQL
This is a very short step. Run the MySQL setup package you downloaded earlier and select the Typical installation option. Then hit Next->Next->Finish all the way to the end. When the configuration wizard runs, choose Detailed Configuration, then Developer Machine, then Multifunctional Database. When asked for a location for the Inno files, I used C:\projects\MySQL. Choose Decision Support (DSS)/OLAP then leave both boxes checked on the next dialog with 3306 as the port number. Choose Standard Character Set, then check Install As Windows Service and leave Include Bin Directory in Windows PATH unchecked. Enter a new root password, leave Create An Anonymous Account unchecked. Finally, hit Execute to finish the configuration wizard. MySQL is now installed and configured.
Step 8 – Create a database for our project
We’ll need to create a database for our project. To do this we’ll need to install HeidiSql. Let’s run that installer now. I use the defaults from the installer except on the Select Additional Tasks dialog where I uncheck Associate .SQL Files with HeidiSQL. When the installer completes it will launch the HeidiSQL gui. Click the New button at the top of the first dialog. Name the connection MyRailsSite, click OK, and then enter the password you selected during your MySQL installation into the password box provided. The first thing we’re going to do is create a new database. Right-click over root@127.0.0.1 in the left side-bar and select Create database from the context menu. Enter MyRailsSite as the database name and click ok. Now select Tools->User-Manager from the top menu. We’re going to create a new user to avoid using the root user in our application. For the Username type myrailsdbuser, set From Host to localhost, and type a password for your new user. Don’t use the same password you used for root. In the Allow access to list, left-click over the myrailssite database (it will turn yellow). Now click Add User. Then click Close to close the user manager dialog. Now we’ve created a database and a specific user for our Rails application to use.
Step 9 – Configure Rails to use the database
Finally we need to configure our Rails site to use our new database. In an Explorer window, navigate to C:\projects\MyRailsSite\config, right-click the database.yml file and edit it in your favorite editor (I use TextPad but NotePad will suffice). Edit your file to look like the following:
Step 10 – Testing the site locally
We’re finally ready to test the site locally! Open up a command window are run the following to start the WEBrick server:
cd c:\projects\myrailssite
ruby script/server
Then open a browser and navigate to http://127.0.0.1:3000/. You’ll notice that the Rails welcome page still displays. However, change the url in the browser to point to http://127.0.0.1:3000/helloworld. You should now see your view displaying the message “Hello World!”. Let’s remove the default index page now and then make your default route point to your helloworld view. To do this, open up Explorer and navigate to c:\projects\myrailssite\public. This is your site’s public directory. From here, delete the index.html file. That’s the welcome page gone; we don’t need it anymore. Now navigate to c:\projects\myrailssite\config and open the routes.rb file again. Add the following line just before the map.connect line we added earlier:
map.root :controller=>”hello_world”
This configures the root route to point to our hello world controller. As we stated earlier, there is no need to specify the index action as it is assumed by default. Save and close the file, then browse to http://127.0.0.1:3000 once more. Your site should now be displaying your “Hello World!” message. Note how the url is just http://127.0.0.1:3000 and doesn’t have helloworld at the end. This is an important point about routes. You aren’t navigating a particular directory structure on the site, you are simply navigating routes and actions. The controller could be named anything you like as long as the route for a particular end-point correctly routed requests for that end-point to your controller. For now, let’s stop the WEBrick server and close the command window. The final task is to get your Rails site up to DreamHost and serve your “Hello World!” request remotely.
Step 11 – Configuring DreamHost for your site
This final configuration step may seem a little confusing at first, but only if you aren’t familiar with Linux and BASH. It doesn’t take very long and it isn’t important to understand how it works because you’ll only need to do it once. We’re going to install version 2.1.2 of rails to your remote host because that’s the version that Passenger (mod_rails) needs in order to run your site. This is where we’ll need PuTTY. Fortunately there is no installation step with PuTTY. It is simply an executable that you download and run.
When you run PuTTY, you will need to supply the username and password of the user we configured in step 3. This will connect you to the server that will host your site. The following instructions are commands to enter into the BASH shell as well as instructions on editing your ~/.bash_profile file (which is similar to environment settings for the command shell in Windows). The first part of these instructions is about editing your ~/.bash_profile file to ensure that some paths and other required settings are configured before beginning installation. These instructions have been adapted from the DreamHost wiki article on this topic.
Before we update rails, let’s first create our Rails site remotely. To do this, first run PuTTY. For the Host Name you will supply your domain name in the form www.MyDomainName.com. Then click Open. I choose No from the next dialog as I don’t want to store anything in the registry. You will now enter the username and password for the user we created in step 3. When you connect, type ls and hit enter. This is the BASH command to list the contents of the current directory. You should see MyDomainName.com listed in the output. We are going to navigate to that folder and then create a rails site inside that folder.
cd MyDomainName.com
rails MyRailsSite
This will create a Rails site on the DreamHost server, the same way we did it locally earlier. We’re going to create the site like this and then upload our site files from our local machine to the remote site. To upload our files, we’ll use an Explorer window and ftp. First, however, we need to create a copy of our database.yml and environment.rb files. This is because those files will be different on our remote host than they are locally. Create a copy of each of those files called database.yml.live and environment.rb.live now. Now edit the database.yml.live file to look like the following:
Edit your environment.rb.live file and uncomment the following line (its on line 5):
ENV['RAILS_ENV'] ||= ‘production’
This is important because running in development mode under FastCGI will cause memory leaks on the DreamHost server. They will catch them and clean them up but it’s better to run in full production mode and not cause problems.
One final change we need to make locally is to update the c:\projects\myrailssite\config\environments\production.rb file. Comment out the config.action_view.cache_template_loading = true line as it causes problems with the Passenger product that will host our site.
Now we’re ready to install Rails 2.1.2 remotely. Switch back to your PuTTY session (or log in again if you exited). Let’s first edit the ~/.bash_profile file. To do this we will be using the nano text editor. To open the ~/.bash_profile file in nano, type the following:
nano ~/.bash_profile
Now you can use the cursor keys to navigate the file. We need to add the following lines to the end of the file:
# Path settings
export GEM_HOME=”$HOME/.gems”
export GEM_PATH=”$GEM_HOME:/usr/lib/ruby/gems/1.8″
export PATH=”$HOME/bin:$HOME/.gems/bin:$PATH”
export RUBYLIB=”$HOME/lib:$RUBYLIB”
# Stops the DreamHost processes from killing the gem install process
alias gem=”nice -n19 ~/bin/gem”
To save your changes press Ctrl-O then hit enter. Press Ctrl-X to exit the editor and return to the shell. You can now type cat ~/.bash_profile and the contents of the file should be printed out. This is a good way to check that your changes were saved and that you typed everything correctly.
Now we need to perform the installation. The following commands will achieve this:
cd ~
mkdir .gems
mkdir bin lib src
cd ~/src
wget http://rubyforge.org/frs/download.php/43985/rubygems-1.3.0.tgz
tar xzvf rubygems-1.3.0.tgz
cd rubygems-1.3.0
ruby setup.rb –prefix=$HOME
cd ~/bin
ln -s gem1.8 gem
For more information on what each of these steps is doing check the DreamHost wiki article. We can check that the path and gem versions are correct by typing the following:
which gem
gem -v
These commands should return /home/USERNAME/bin/gem and 1.3.0 respectively. Now we can execute the command to install Rails 2.1.2, which is:
gem install rails –version 2.1.2
What we’ve accomplished here is to install RubyGems and Rails 2.1.2 to our hosted server. The last thing we need to do to make everything work is to use rake to freeze our version of Rails to 2.1.2 so that Passenger will use our Rails installation when running our site. The commands to do this are as follows. Please note that you need to supply your domain name in the format MyDomainName.com and the name of your Rails site in place of MyRailsSite in the first command. This simply changes the current directory so that we’re running rake in the right place.
cd ~/MyDomainName.com/MyRailsSite/
rake rails:freeze:edge TAG=rel_2-1-2
That’s it! Phew. That felt like a lot of work, but at least you only have to do it once.
Step 12 – Deploying and testing your site remotely
Now that we’ve set up the environment with DreamHost, the only task left is to deploy the site remotely and test it out. Before we do that though, we are going to check one last configuration setting in the DreamHost control panel, just to be sure that everything is setup correctly. If you navigate to Domains->Manage Domains in the left side-bar and then click the Edit button again (see step 2), then check out the Specify your web directory setting. This is where DreamHost will send requests to MyDomainName.com. It should be set to:
/home/username/MyDomainName.com/MyRailsSite/public
By setting the directory to the public directory of your Rails site, it means that users cannot navigate outside of that directory and browse places that they aren’t supposed to be.
Let’s finish up and deploy our Rails site from the local machine to the remote server. We’ll use Explorer and ftp to do this. Open up Explorer and type ftp://ftp.MyDomainName.com into the address bar. Now open up the MyDomainName.com and then MyRailsSite folders. You will need to copy your app directory from your local machine at c:\projects\myrrailssite\app up to the remote server. When you have copied these files, navigate to the pubilc directory on the remote server and delete the index.html file. We don’t need the Rails welcome page on live anymore either! Then navigate to the config directory and copy the routes.rb, environment.rb.live and database.yml.live files up to the corresponding folder on the server. Don’t forget to rename these to environment.rb and database.yml on the remote server. We only renamed them so that we could have two different files locally. Finally, navigate to the config/environments folder and copy the production.rb file that we edited up to the corresponding location on the remote server. From now on, when you deploy your site, you will only have to copy the app folder to the remote server (unless you change config settings that is).
The final step before we can test our site on live is to setup the MySQL database on the DreamHost side to match the one we set up locally. Since we didn’t create any database tables, this is fairly simple to do through the DreamHost interface. Go to Goodies->Manage MySQL and repeat the same steps here as we did in step 8. You can also use HeidiSQL if you want to manage your database remotely that way. However, for now I recommend using the DreamHost web interface to do this work. All you need to ensure is that the database name and username/password for that database match the settings you specified in your database.yml file. I’m going to cover using databases in Rails in more detail in a future article. For now we just need to get an empty database and a user that has access to keep Rails happy.
Congratulations! Assuming that everything was wired up correctly, you should now be able to open a browser and navigate to http://www.MyDomainName.com to see your site being hosted remotely.
Hopefully this article will help you get up and running with a basic Rails site that is hosted remotely. The focus of this article was understanding the relationship between running a Rails site locally and hosting it on a remote server. Setting up your development in this way from day one will save a lot of headaches later when it comes to deployment time. Developing and testing locally, then deploying to a live host means that problems can be identified early and that changes can be tested locally rather than on a live site. I’m going to expand upon this article as part of my ongoing experiement with ASP.NET, Silverlight, PHP, and Ruby on Rails. Next we’re going to develop a database, understand models using ActiveRecord, and dig a little deeper into Rails. For now: happy hosting!
Rails, Ruby
DreamHost, Instructions, Ruby on Rails, Setup, The Experiment
