Dokku uses an open source Ruby buildpack to compile and run your application. Follow these steps to configure and deploy your app.

Creating an Application

Connect to the server and create your app(s):

dokku apps:create my-app-name

Preparing Your Application for Deployment

Perform the following tasks on your local development machine:

1. Specify the Ruby version in your Gemfile and add the rails_12factor gem under the "production" Gemfile group.

ruby '2.5.0'

group :production do
  gem 'rails_12factor'

The Ruby buildpack supports stable versions of Ruby only. For the current list, you can look at Heroku's Ruby page.

2. Include a "production" section in your database.yml with a DATABASE_URL set to your database connection string, as described in the official Ruby on Rails Guides. Example URL's are also shown in the Dokku Getting Started guide.

  url: <%= ENV["DATABASE_URL"] %>

3. Add a Procfile at the root of your source code project. Your application should have the appropriate config file under config/.

Puma (recommended):

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


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

If you need to enable any background processes, add the process command (Delayed Job example):

worker: bundle exec rake jobs:work

4. If you'd like to automatically run database migrations during deployments, add an app.json to the root of your git project with the following structure:

  "scripts": {
    "dokku": {
      "predeploy": "bundle exec rake db:migrate"

5. On the server, define any environment variables, especially addresses for external services, using the dokku config command before deploying your application. Additional details can be found in the Getting Started Guide.

Using Docker Natively

If you prefer to use your own Dockerfile instead of the Ruby buildpack, please refer to the official Dokku Dockerfile deployment instructions.

Deploy your App

See Deploying via Git topic

Scaling Your Workers

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

dokku ps:scale my-app-name worker=1

Increasing File Upload Limit

To extend Nginx's file upload limit of 1 MB, create a new file, /home/dokku/my-app-name/nginx.conf.d/custom.conf, with the following contents:

client_max_body_size 5m;

Then, run this command:

service nginx reload

If your application handles large uploads, it can tie up the number of available request handlers. For apps with heavy traffic, ensure you have enough capacity. There are also alternate techniques, involving uploading directly to an Amazon S3 bucket (which we can provide), as described in this external Heroku article.

Optional Steps for Rails Applications Using React.js

If you are compiling any assets using Bower (e.g. React.js), do the following:

a. Add a .buildpacks file to the root of your project with the following contents:

b. Add a package.json to your root of your project with the following contents (use the version of Bower appropriate for your app):

  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "bower": "~1.7"
  "scripts": {
    "postinstall": "./node_modules/bower/bin/bower install"

Additional Documentation

More help topics can be found in the Dokku Getting Started guide.