How To Use the Dokku One-Click DigitalOcean Image to Run a Ruby on Rails App

Introduction

---

A significant hurdle in developing an application is providing a sane and easy way to deploy your finished product. Dokku is a Platform as a Service solution that enables you to quickly deploy and configure an application to a production environment on a separate server.

Dokku is similar to Heroku in that you can deploy to a remote server. The difference is that Dokku is built to deploy to a single, personal server and is extremely lightweight. Dokku uses Docker, a Linux container system, to easily manage its deployments.

In this guide, we will cover how to deploy a Ruby on Rails app with Dokku using the DigitalOcean Dokku one-click installation image.

Step One –– Create the Dokku Droplet

---

The first thing we need to do is create the VPS instance that contains our Dokku installation. This is simple to set up using the DigitalOcean Dokku application.

Click on the "Create" button to create a new droplet:

Name your droplet, and select the size and region that you would like to use:

Scroll down and click on the "Applications" tab. Select the Dokku application image:

Select your SSH keys if you have them available. If you do not already have them configured, now is a great time to create SSH keys to use with your DigitalOcean droplets. This step will help you later.

Click "Create Droplet". Your Dokku VPS instance will be created.

Once your droplet is created, you should set up your domain name to point to your new Dokku droplet. You can learn how to configure domain names with DigitalOcean here.

Step Two –– Access the Droplet To Complete Configuration

---

You can complete your Dokku configuration by accessing your VPS from a web browser.

If you configured a domain name to point to your Dokku installation, you should visit your domain name with your favorite web browser. If you do not have a domain name configured, you can use your droplet's IP address.

You will be given a simple configuration page. There are a few parts that you need to configure here.

First, check that the Public Key matches the computer that you will be deploying from. This means that if your project is on your home computer, you should use the public key that corresponds to that set up.

If you selected multiple SSH keys to embed during droplet creation, only the first will be available here. Modify it as necessary.

Next, modify the Hostname field to match your domain name. Leave this as your IP address if you do not have a domain name configured.

Choose the way that you want your applications to be referenced. By default, the application will be served like this:

http://your_domain.com:app_specific_port_number

If you select the "Use virtualhost naming for apps" check box, your apps will be accessible using a virtualhost instead:

http://app_name.your_domain.com

Click the "Finish Setup" button to complete the configuration.

Step Three –– Deploy a Sample Ruby on Rails Application to your Dokku Droplet

---

Now that we have Dokku configured, we can begin to work on the application that we want to deploy. For the most part Ruby on Rails applications should work as expected, especially if they have been optimized for Heroku.

Install the PostgreSQL Database Plugin

---

We will actually begin on the Dokku droplet that we just deployed. Log into the droplet as root.

Dokku handles database resources through a plugin system. If your application needs a database, you need to install the plugin and create a database in that way.

Change to the plugins directory:

cd /var/lib/dokku/plugins

We will clone the PostgreSQL plugin to this directory with git:

git clone https://github.com/Kloadut/dokku-pg-plugin.git postgresql

Now, we need to issue the Dokku command that builds the plugins:

dokku plugins-install

This will install and configure the necessary components to provide Postgres access to our applications. If we issue the Dokku help command, we can see that we now have new commands available:

dokku help

. . .
plugins         Print active plugins
postgresql:create <app>     Create a PostgreSQL container
postgresql:delete <app>     Delete specified PostgreSQL container
postgresql:info <app>       Display database informations
postgresql:link <app> <db>  Link an app to a PostgreSQL database
postgresql:logs <app>       Display last logs from PostgreSQL container
run <app> <cmd>                                 Run a command in the environment of an application
url <app>                                       Show the URL for an application
. . .

The next step is actually creating a database that our app can plug into and use. As you can see above, this is easy with the new plugin commands that we have available:

dokku postgresql:create app_name

It is important that you choose the app_name carefully here. It must be the same name that you plan to use when deploying your application. You will be accessing the application through:

http://app_name.domain.com

Create a Basic Rails Application

---

From your development computer (the one with the SSH key that matches the one you entered during the Dokku installation), you need to install Ruby and Rails. A good way to do this is with RVM, the Ruby version manager.

You can install Ruby on Rails with RVM on an Ubuntu droplet here.

We will also download a few things that are needed for our Rails application:

sudo apt-get install nodejs postgresql-server-dev-all

Now, we will create a new, simple blog with Rails. We can do that easily by typing:

rails new blog

This will create a new Rails application in a directory called blog in the current directory.

Change into the directory:

cd blog

We can now use Rails scaffolding abilities to generate some components for our blog:

rails generate scaffold post title:string body:text

We need to migrate the database created by the scaffolding into our application:

rake db:migrate

Finally, we need to tell Rails which page to use as the default when visiting the site. Open the config/routes.rb file with your text editor:

nano config/routes.rb

You need to add a line that specifies the default file to server by adding the root route (in red):

Stuff::Application.routes.draw do
  root 'posts#index'
  resources :posts
  . . .
  . . .
end

Save and close the file.

It is important to test your blog on the current computer before trying to deploy to Dokku. Type this into your terminal to start the rails development server:

rails s

In a web browser, visit the IP address of the computer you are developing on, followed by :3000.:

your_dev_ip_address:3000

You should see a bare-bones Rails blog:

Back in the terminal, exit out of the rails server by holding the control key and hitting 'C':

CTRL+C

Now that we have verified that our application is functioning correctly, we need to make a few modifications to make our app work with Dokku.

First, the Rails development environment uses an SQLite database to manage its information, but Dokku requires you to deploy with Postgres. We can change this by modifying the Gemfile in the application directory.

nano Gemfile

We need to comment out the SQLite requirement and add the Postgres requirement:

source 'https://rubygems.org'

# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
gem 'rails', '4.0.1'

# Use sqlite3 as the database for Active Record
# gem 'sqlite3'
gem 'pg'

# Use SCSS for stylesheets
gem 'sass-rails', '~> 4.0.0'
. . .

Save and close the file.

Make the project aware of these changes by issuing this command:

bundle install

Initiate Version Control Through Git

---

Now, we need to add our project to git in order to push it to Dokku.

If you do not have git installed, you will need to do that now. If your development machine is an Ubuntu machine, you can install using:

sudo apt-get install git

You need to configure some global settings so that git will allow you to add commits:

git config --global user.email "your_email"
git config --global user.name "your_name"

Now, initialize a git repository in the root application directory:

git init

Add all of the project's files and commit them:

git add .
git commit -m 'Initial commit'

Push the App to Dokku and Deploy

---

To deploy to Dokku, you simply need to add the domain name as a remote of your git repository:

git remote add remote_name dokku@your_domain.com:app_name

The remote_name can be anything that you'd like to refer to your Dokku machine. In most cases dokku is a good choice. The app_name must match the name you chose when you created your PostgreSQL database on the Dokku droplet.

Now, to deploy, just push your app to Dokku:

git push remote_name master

Dokku will deploy your app and give you a URL where you can reach your application:

-----> app_name linked to redis/app_name container

-----> app_name linked to postgresql/app_name database
-----> Deploying app_name ...
-----> Cleaning up ...
=====> Application deployed:
       http://app_name.your_domain.com

To dokku@your_domain.com:app_name
 * [new branch]      master -> master

There is one last step that we need to take before your app will work correctly. Because our application is using a new database in a new environment, we need to re-run the rake db:migrate command within our application environment.

We can do this by SSHing into our Dokku droplet. Dokku allows you to pass commands directly to an application environment.

Change into the application directory and then issue the command:

cd /home/dokku/app_name

Note: Due to a change in the PostgreSQL plugin, you now must link the database to your application explicitly by issuing a command that looks like:

dokku postgresql:link app_name database_name

Afterwards, we can migrate the database like this:

dokku run app_name rake db:migrate

You should now be able to visit your application at:

http://app_name.your_domain.com

Conclusion

---

You should now have a working Rails application deployed and running on your Dokku droplet. You can learn more about Dokku by visiting the project's page on GitHub. We also have a section of other Dokku tutorials at DigitalOcean.