Ruby on Rails Dokku Guide

Preparing the App

Specify the Ruby version in your Gemfile:

ruby '2.7.6'

To meet HIPAA/security requirements, use a stable version of Ruby that is currently receiving security updates. The list of stable releases can be found this page.

Create a file named Procfile in your project's root directory to define the command used to start your app (in a production environment, in most cases):

web: bundle exec puma -C config/puma.rb

This declares a single process type, web, and the command needed to run it. The name web is important here - this process type will be able to receive web traffic when deployed. 

Procfiles can contain additional process types. For example, you might declare one for a background worker process that processes items off of a queue:

worker: bundle exec rake jobs:work

Create the Dokku App on the Server

Connect to the Healthcare Blocks virtual machine:


Tip: alternately, use the Dokku Client directly from your local machine instead of connecting to the server.

Create a new Dokku app:

dokku apps:create my-app

Configure Environment Variables

Define app-specific environment variables that your framework can use to control environment-specific behavior:

dokku config:set my-app RAILS_LOG_TO_STDOUT=true

An important setting in Rails 5+ is the RAILS_LOG_TO_STDOUT variable, which is queried by production.rb. Setting this variable to true will route your logs to the Dokku log interface.

Healthcare Blocks recommends storing sensitive values, including database credentials, in an .env file or equivalent on the server. See this topic for details.

Be sure your application is configured to communicate with any non-local databases using SSL/TLS. Details here.

Configure a Buildpack

Dokku uses an auto-detect function to identify which buildpack is best suited for your application type, however, Healthcare Blocks recommends explicitly configuring the buildpack to avoid any issues.

If you'd like to always use the latest version of the Ruby buildpack, use the following format:

dokku buildpacks:add my-app \

If you'd like to lock in a specific buildpack release, append the GitHub tag name to the end of the URL:

dokku buildpacks:add my-app \

Release tags can be found here, and the corresponding change log is here.


Deploy your App

On your local machine, ensure you've initialized your local git repository and committed all files that will be deployed to the server. Development logs and assets and temporary files should be excluded in your .gitignore file.

Define a local git remote that references the Healthcare Blocks server and the app you created above:

git remote add hcb \

Notice the "dokku" username. Even though you have a dedicated Linux user on the server, your SSH key is also associated with a dokku user that is used for handling deployments and remote commands.

To deploy the app:

git push hcb main

Main (or master in older git repositories) is the name of the branch you are pushing to on the server and should not be changed. To deploy a different local branch, for example, "integration":

git push hcb integration:main

Alternative Deployment Methods

Dokku is flexible and supports additional options besides buildpacks / git push:

Using Dockerfiles instead of Buildpacks

See Dockerfile Deployment.

Using External Docker Images

If you are already building a Docker image externally and want to use it as the basis for your Dokku app, see Initializing an app repository from a Docker image.

Other External Sources

Instead of using git push from a local machine, you can initialize/update a Dokku app using an archive file or external repository (including private ones).

Scaling Your Workers

By default, Dokku only starts up your Web processes. To scale any background workers defined in your Procfile:

dokku ps:scale my-app worker=1

Increasing File Upload Limit

The reverse proxy that sends traffic to your Rails app has a default file upload limit of 1 MB. To override this limit, create a new file, /home/dokku/my-app/nginx.conf.d/override.conf, with the following contents:

client_max_body_size 5m;

Then, restart your app:

dokku ps:restart my-app

Frequently Asked Questions

How do I automatically run database migrations during a release?
Add a release statement to your Procfile with the rake db:migrate command. See this page for details.

How do I install Redis for my background jobs processing?
On the server, install the Dokku Redis plugin and start an instance of Redis, linking it to your app.

Reference Application

The following Ruby on Rails app is compatible with Dokku: