In this example, we are going to use the JumpBox for Ruby on Rails to deploy our very own application. This tutorial assumes that you're familiar with developing and running Ruby on Rails applications, at least on your local computer using 'script/server' to start a development application. If you aren't familiar with Rails development, please refer to the tutorials located at the Ruby on Rails documentation site.

Steps Involved

1. Develop your Application

   Develop your Rails application on your local machine as you normally would. While the JumpBox for Ruby on Rails makes deploying your Rails applications far more convenient, it's still quickest to develop and test on your local machine.

   The major difference between running your Rails application on your local machine versus in the JumpBox for Ruby on Rails is that the JumpBox executes your application using the Phusion Passenger Apache Module instead of the single process that 'script/server' initiates. The JumpBox is configured to use Phusion Passenger's default parameters. Customizations to the Passenger setup can be made in the file /etc/apache2/mods-available/passenger.conf. After making modifications to this file Apache must be restarted. Details on Passenger configuration can be found in the Phusion Passenger Users Guide.

   To deploy your rails applications, you will be using either SCP (Secure Copy Program) or SFTP (Secure FTP) to transfer your rails application to its proper home inside of the JumpBox for Ruby on Rails. You will also need to login to the JumpBox in order to perform several actions necessary in the configuration and deployment of your Rails application.

   All of the following shell commands will be executed directly on the JumpBox for Ruby on Rails. If you've already gone through the process of configuring and registering your JumpBox, then you're ready to begin. Use SSH to login to your JumpBox. The IP address is displayed on the JumpBox's console screen, the user name will be 'admin', and your password is what you set during the initial JumpBox setup.

   Once you're logged in, you can begin deploying your first Rails application by typing the following commands at the bash prompt. Note that you don't have to type the commented lines (they begin with a #).

2. Database Configuration

   The JumpBox for Ruby on Rails includes MySQL 5.0 as its default database. Often, a developer will target SQLite in the development of their software. While continuing to use SQLite for deployment is perfectly acceptable, a developer may choose to target MySQL instead. If you'd like to use MySQL instead of SQLite, you'll need to modify your application's default database.yml file. You can do this by using your favorite editor, but be careful that your editor expands tabs to spaces, as YAML files are sensitive to whitespace indentation levels.

   The MySQL server on the JumpBox for Ruby on Rails is preconfigured with Test, Application, and Development databases. These database are configured to accept connections from a user named 'appuser'. In order to have your Rails application connect to these databases, the contents of database.yml under your application's 'config' directory should look something like this.

   development:
     adapter: mysql
     database: app_development
     host: localhost
     username: appuser
     password: tah2quooL1
     socket: /var/run/mysqld/mysqld.sock
     
   test:
     adapter: mysql
     database: app_test
     host: localhost
     username: appuser
     password: tah2quooL1
     socket: /var/run/mysqld/mysqld.sock
     
   production:
     adapter: mysql
     database: app
     host: localhost
     username: appuser
     password: tah2quooL1
     socket: /var/run/mysqld/mysqld.sock

   You may also choose to only point your application at mysql for production deployments, in which case you'll only want to modify the 'production' section of the database.yml file.

3. Log in to your JumpBox

   Many of the following shell commands will be executed directly on the JumpBox for Ruby on Rails. If you've already gone through the process of configuring and registering your JumpBox, then you're ready to begin. Use SSH to login to your JumpBox. The IP address is displayed on the JumpBox's console screen, the user name will be 'admin', and your password is what you set during the initial JumpBox setup.

   Once you're logged in, you can begin deploying your first Rails application by typing the following commands at the bash prompt. Note that you don't have to type the commented lines (they begin with a #).

   # Stop the Apache Webserver and Passenger
   sudo /etc/init.d/apache2 stop

4. Upload Your Rails Application

   The default location for a deployed application on the JumpBox is '/var/data/app/current'. Before you've uploaded your application, you'll probably want to move the default skeletal Rails application out of the way.

   # Move the Skeletal Rails application out of the way
   mv /var/data/app/current /var/data/app/orig

   From your local computer, you'll now want to upload the contents of your Rails application's top level directory to its new home on the JumpBox for Ruby on Rails. If you're using a UNIX-based operating system and SCP, you can do so by changing the directory that stores your Rails application, and issuing the following command:

   # Transmit your local Rails application to the JumpBox
   scp -r MyRailsApp  admin@192.168.1.1:/var/data/app/current

   Replace 192.168.1.1 with the IP address that is displayed on your JumpBox's console screen. When prompted for a password, enter the password that you set during the initial JumpBox setup.

   From your SSH session with the JumpBox, you'll now need to set proper ownership for your Rails application.

   # Recursively change ownership of current so that it uses the www-data group
   sudo chown -R admin:www-data /var/data/app/current

5. Configure Your Database

   Once you've installed your Rails application, you'll need to perform an initial setup of your application's database. You'll do this by using the rake tool from your SSH session.

   # Change to the root of the Rails apps directory
   cd /var/data/app/current
   
   # Set your Rails environment to production
   export RAILS_ENV=production
   
   # Create the Rails database (uses RAILS_ENV)
   rake db:migrate

6. Restart the Apache Webserver

   The Apache Webserver running on the JumpBox needs to be started once again so that you may access your newly deployed Rails application.

   # Make sure the tmp directory is created
   mkdir -p /var/data/app/current/tmp
   
   # Restart the Apache Webserver
   sudo /etc/init.d/apache2 start

That's it! Your Rails application should now be running on your JumpBox. You can confirm this by pointing your browser to the standard http endpoint of the JumpBox.

Distributing the Rails Application

Distributing your Rails application is as simple as performing a backup using the JumpBox's backup feature, and making that file image available to your end users. When the end user receives this backup, they must perform a JumpBox restore using the backup image, and voila, they're ready to go.

For the moment, these files must not be renamed, and your users will be required to download their own copy of the JumpBox for Ruby on Rails, but that will all change soon.