Getting Started with Dokku

We can install Dokku, an open source PaaS, to your servers. Dokku provides the ability to run more than one container on a single server, allocating resources as needed.

Dokku Commands

For a list of your Dokku server's available commands, use ssh -t to connect to your Dokku user at your server:

$ ssh -t dokku@abcde.example.cloud
Examples in this guide will use abcde.speedy.cloud as a sample Dokku server.

Run commands on your Dokku server using ssh -t dokku@abcde.example.cloud and a command:

$ ssh -t dokku@abcde.example.cloud <command>

For example, to check the version of Dokku running on your server, use the version command:

$ ssh -t dokku@abcde.example.cloud version

For detailed information about a command, use the :help option.

$ ssh -t dokku@abcde.example.cloud <command>:help

Dokku Plugins

Dokku supports plugins that extend the functionality of your Dokku platform.
We manage plugin installation and can add plugins to your Dokku server by request.

We install plugins for MySQL and Let's Encrypt by default.

You can find a list of current Dokku plugins in the Dokku Community Documentation.

Deploying a Rails Application With Dokku

To configure Dokku to work with a Rails application, you must create a container for the application, create its database container, configure the application for the database, and link the database to your application.

In this example we will use the mysql2 gem as the database adapter and Puma as the web server.
  1. Create an application container for your application:
    $ ssh -t dokku@abcde.example.cloud apps:create your-app-name
  1. Add a database container using a database plugin:
    $ ssh -t dokku@abcde.example.cloud mysql:create your-app-name-db
  1. To link your Rails application to your database, set the database scheme on your application using the config:set command:

     $ ssh -t dokku@abcde.example.cloud config:set your-app-name MYSQL_DATABASE_SCHEME=mysql2
  2. Link the database container to your application container:

     $ ssh -t dokku@abcde.example.cloud mysql:link your-app-name-db your-app-name
  3. Add your Dokku application container as a git remote:

    $ git remote add dokku dokku@abcde.example.cloud:your-app-name
  1. In your application's /config/database.yml, add the URL for the Dokku database container to your production environment:

     url: <%= ENV["mysql2://mysql:aaa111bbb222cc33@dokku-mysql-your-app-name-db:3306/your-app-name-db"] %>
  2. Create a Procfile and set the application server:

     web: bundle exec puma -C config/puma.rb
  3. In your application's Gemfile, add your application's Ruby version, rails_12factor to your production group, and your database gem:

     ruby '2.2.3' # Or your application's ruby version
     gem 'rails_12factor', group: :production
     gem 'mysql2'

Dokku uses the rails_12factor gem to send logs to stdout and serve assets in production.

  1. Push your application up to your Dokku server with git:
    $ git push dokku master
  1. Use your browser to view your Dokku server to verify the deploy.
Dokku only supports deploying from its master branch. To deploy a different local branch use: git push dokku :master

Adding a custom domain to your Dokku application

After deploying your application, you can use a custom domain to point to your Dokku server:

  1. Log in to your domain host and create DNS records to point to your Dokku server. For example, you can create an A record pointing to your application IP or a CNAME record pointing to abcde.example.cloud.

  2. Using the command line, assign your application the domain:

     $ ssh -t dokku@abcde.example.cloud domains your-app-name yourdomain.com

Adding a SSL Certificate to your Dokku Application

We automatically install Dokku's Let's Encrypt plugin to allow you to add SSL certificates to secure your application.

To add SSL certification to your application:

  1. Add a valid email address to your application's Dokku configuration:

     $ ssh -t dokku@abcde.example.cloud config:set --no-restart your-app-name DOKKU_LETSENCRYPT_EMAIL=yourname@email.com
  2. Use the Let's Encrypt plugin to add your SSL certificate:

     $ ssh -t dokku@abcde.example.cloud letsencrypt your-app-name

Certificate Expiry and Revocation

Let's Encrypt SSL certificates are valid for 90 days, and are due for renewal after 60 days.

To check your certificate expiry status for all applications on your Dokku server, use the letsencrypt:ls command:

    $ ssh -t dokku@abcde.example.cloud letsencrypt:ls

To automatically renew the SSL certificates on your Dokku server during the renewal period, use the letsencrypt:auto-renew command:

    $ ssh -t dokku@abcde.example.cloud letsencrypt:auto-renew

To revoke your application's SSL certificate, use the letsencrypt:revoke command:

    $ ssh -t dokku@abcde.example.cloud letsencrypt:revoke your-app-name

Viewing Application Logs

Dokku provides logs to view activity on your Dokku server using the logs command:

  $ ssh -t dokku@abcde.example.cloud logs

To view a continuous stream of your application logs, use the -t modifier:

  $ ssh -t dokku@abcde.example.cloud logs -t
To stop viewing the continuous log stream, press Control-C.

Backing up Dokku Servers and Databases

Full Server Backups

To back up your entire Dokku server, use the Cloud control panel to create a server backup.

Database Backups

Most Dokku database plugins allow you to backup your application database to an Amazon S3 account using Dokku commands. To backup your database you must first authorize the Dokku plugin to use your S3 account with your credentials before creating a backup.

The following guides use the MySQL plugin as an example database plugin. However, most database plugins for Dokku use the same commands to authorize, backup, and schedule backups. For information about a specific plugin, use the plugin's :help function for more information.

To backup your database to S3 using the MySQL plugin:

  1. Get an AWS access key ID and AWS secret access key from your AWS S3 account.
  2. Use the terminal to authorize the plugin to use your S3 credentials:

     $ ssh -t dokku@abcde.example.cloud mysql:backup-auth your-app-name AWS_ACCESS_KEY AWS_SECRET_KEY
  3. Backup the application database using the backup command:

     $ ssh -t dokku@abcde.example.cloud mysql:backup your-app-name AWS_BUCKET_NAME

After authorizing the database plugin to backup to an S3 bucket, you can also schedule regular backups using the MySQL plugin using the backup-schedule command.

To schedule a backup of your application database:

    $ ssh -t dokku@abcde.example.cloud mysql:backup-schedule your-app-name CRON_SCHEDULE AWS_BUCKET_NAME

The backup-schedule command uses crontab expressions to set a schedule. For example, to schedule a backup every day at 4:30 AM:

   $ ssh -t dokku@abcde.example.cloud mysql:backup-schedule your-app-name "30 4 * * *" AWS_BUCKET_NAME