How To Use the Dokku One-Click DigitalOcean Image to Run a Ruby on Rails App
Note: The Dokku project has changed significantly since this guide was written. The instructions below may not reflect the current state of the Dokku project.
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:
If you select the "Use virtualhost naming for apps" check box, your apps will be accessible using a virtualhost instead:
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.
To install the PostgreSQL plugin run:
dokku plugin:install https://github.com/dokku/dokku-postgres.git
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:
. . . plugins Print active plugins postgres:create <app> Create a PostgreSQL container postgres:delete <app> Delete specified PostgreSQL container postgres:info <app> Display database informations postgres:link <app> <db> Link an app to a PostgreSQL database postgres: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 postgres: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:
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:
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:
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:
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:
In a web browser, visit the IP address of the computer you are developing on, followed by
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':
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.
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:
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:
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
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 postgres/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:
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 postgres: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:
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.