In this tutorial we will cover how to use our Ruby on Rails Unicorn one-click install image to easily run a Ruby on Rails application. Our ready to use Ruby on Rails image includes lot of pre-installed tools to ease the development and deployment of Ruby apps. The OS running on the image is Ubuntu.

Ruby on Rails image

What's already in the image

Nginx

This is the web server that client requests will first hit. It is used both to serve the static content and as a proxy in front of the application server.

Unicorn and Thin

Unicorn is the server that actually runs the application. You will see how to configure how many instances of the application are preloaded and running ready to serve requests. For those who prefer the Thin application server it is also installed.

PostgreSQL and Percona RDBMS

Almost every project nowadays needs an RDBMS to store relational data. PostgreSQL is a state of the art RDBMS supporting a lot of enhanced features while keeping the best performance amongst open-source RDBMS. For those who prefer MySQL there is also a Percona Server installed that just needs to be started.

RVM

The RVM tool is used to easily manage several different Ruby on Rails versions installed on the same server/container and easily install and run new versions.

Bundler

The Bundler tool is used to manage Ruby gems. Each project needs different versions of the same gems. This tool allows you to easily install gems for each project. Thus, upgrading one gem for one project won't affect the functionality of the other projects that are running on the same sever.

GIT

Git is a free and open-source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. It is the standard for keeping track of source code changes nowadays.

Redis and memcached key-value stores

Redis is an advanced key-value store and cache service. For those who prefer memcached we also have it installed

a newly-started Ruby on Rails project

This is just for convenience for those who want to start coding a brand new application from scratch. Project location is:

/home/getclouder/myapp

How to install the application?

For the purpose of this tutorial, we will show how to install a blog platform called Publify that is written in Ruby on Rails. Its source code is available on Github.

Create a new user in the container

Lets set up each application to run as a separate user in the container. This way we get a new layer of security because if an attacker compromises one of your applications, it would not directly affect the others.

In order to create a new user run the following command as root:

Get the apps' code to the container

The first thing you need to do in order to install an application is to get the application's code to the container. Since the application I am installing is available on Github I will just use git to clone the source tree from there. I will clone it in the Publify’s user home folder as user publify.

If you change to the newly created folder publify you will see the following message:

We intentionally picked an application that requires a specific version of Ruby which is not installed in the image in order to show how easy it is to install and manage different Ruby versions.

Install the required version of Ruby

This step is not obligatory for all applications. We have included it just as an example of how to install a new Ruby version. What you need to do is run the command that rvm showed as the root user:

This will take some time as it downloads and validates the new Ruby version.

Using RVM to manage Ruby versions:

Once you have several ruby versions installed you can:

- list them with

- switch between the versions you use in your session with

- specify ruby version to use in a folder by adding to the Gemfile the following line

- install a gem for the version you are using with

Configure your database

In this section we will show you how to configure your application to use PostgreSQL as the DB server.

Create a new PostgreSQL user

In order to connect to the database you will need a user and a password. It is a good security practice to use different DB users for each application. Here is how to create a new user for PostgreSQL called publify. Run the following command as root:

This command will ask you for a password. Be sure to fill-in a strong password.

Configure your application

Before you continue you need to specify what database you are going to use. Normally every rails project contains a YAML file that specifies the connection details. It is located at config/database.yml. When you pull publify from the source tree this file is missing and there are three template files - database.yml.postgresql, database.yml.mysql and database.yml.sqlite. You just need to copy one of them to config/database.yml and edit it. In the example below I will use VIM to edit the file but you can use whatever editor you are comfortable with:

What you need to change are the lines that specify username and password. After you edit the file it should look similar to the following:

Now that your application knows what database you are about to use you can proceed to install the Ruby gems. You should not create the database until you have installed the gems.

Install the gems required by your application

The gems are libraries of code for Ruby. Every big project uses libraries to get some functionality that has already been implemented instead of implementing it from scratch again. Thus installing these libraries, or gems in the case of ruby, is part of each deployment.

The gems required by each projects are often described in a file called Gemfile along with their required version (minimal, maximal or exact). Publify and most of the Ruby on Rails projects also use the Gemfile approach. For such applications all the gems required may be easily installed with the Bundler tool.

When installing gems with Bundler you have to choose if you want to install them system-wide or on a per-project basis. I prefer installing them on a per-project basis because each project might have specific requirements for a gem's version and if they are installed system-wide you might get a version conflict or even break some applications when updating a single gem.

Our Ruby on Rails image comes with two Gemfiles to prevent you from having to modify the application's Gemfile and adding unicorn or thin as a dependency. To use one of them we just need to link it in your application's root folder as Gemfile.local. These files load your Gemfile, check what gems are included and include the gem for the respective application server if it is not already included. To use one of them just create a link:

In order to install all the gems needed for a project just use the following command as the publify user from /home/publify/publify (be patient - it will take some time to install all the gems):

If you’re wondering if these will install the gems twice - the second run will install unicorn only and detect all the rest as already installed.

Now that you are done with this you can create the database and apply existing DB migrations to the database.

Create and migrate the database

To create and migrate the database we will use the rake command. In order to tell our Rails application this is our production server and we want to use the production setup we have to export the RAILS_ENV environment variable and set it to "production". This is done by prepending RAILS_ENV=production to the commands we enter. There is only one detail here - we have to use bundle exec to execute the right version of rake that we installed with our gems specifically for this application. Thus the command you should run as the publify user is:

This command creates the database, applies all migrations to it and inserts the initial data. The result is a fresh database with the schema and initial data required by the application.

Precompile assets

For all the projects that follow the Rails Assets Pipeline there is an additional step that needs to be done in order to precompile some static content (minify javascript files for example). Run the following as the publify user:

Configure Unicorn

At this point we have an application with its database and static files ready to run. We just need to setup the application server that will actually start the application. In order to do this we have to create two configuration files.

The first one should be located in the application's folder in config/unicorn.rb and contain something like the following:

This specifies where unicorn has to put the pidfile, logfiles and the socket. It also specifies how many instances of the application should be running. If you ever feel two instances of the application can't handle the load your users are causing, you should increase the worker_processes configuration option.

The last thing specified is the timeout. It says how long will the master process wait for output from the worker process before killing it and spawning a new process.

The second file is just a configuration file so your application is managed by the unicorn init script. Create it as root in /etc/unicorn. Let's name it /etc/unicorn/publify.conf. It should contain the following:

At this point you are ready to start the application so run the following as root:

This will start three more processes in the container:

The first one is the master process which is responsible for managing the workers. The last two processes that are his child processes are the workers that process requests.

Configure Nginx

The last step before we can see our new blog in the web browser is to configure Nginx. In order to do this we have to create a config file for Nginx to handle requests to our domain. I will use /etc/nginx/sites-available/ror-tutorial.com. Here is the content:

You should pay attention to the following details:

- the server directive in the upstream block must contain the same path as the listen directive we added to config/unicorn.rb in 8.

- the server_name directive specifies the domain name this server will handle. If you want to use it with your container's IP address specify _ as the server_name and be sure to remove the default application as shown below in 10.

- the root of the server must point to the public/ folder of the application

Now create a symlink in /etc/nginx/sites-enabled to /etc/nginx/sites-available/ror-tutorial.com:

And reload nginx:

Now if you've pointed your domain to the container's IP address you should be able to open a browser, enter your domain name and see your new blog's configuration page.

Remove the default application from the image (optional)

As mentioned in the beginning of this tutorial, our Ruby on Rails image comes configured with a new Ruby on Rails project ready to start hacking. If however, you have no plans of developing a new application, we recommend removing it from your container. Here is how to do this:

Remove the unicorn configuration for the application

Remove the Nginx configuration

Remove the Kyup user

That's it, you are now ready to use Ruby on Rails on your Kyup container!