Dokku

Dokku makes it a breeze to deploy and manage web applications on your own server. Now available as a 1-Click installation, it’s even easier to have your own private application platform in a matter of minutes.

Software Included

Creating an App using the Control Panel

Click the Deploy to DigitalOcean button to create a Droplet based on this 1-Click App. If you aren’t logged in, this link will prompt you to log in with your DigitalOcean account.

Creating an App using the API

In addition to creating a Droplet from the Dokku 1-Click App using the control panel, you can also use the DigitalOcean API. As an example, to create a 4GB Dokku Droplet in the SFO2 region, you can use the following curl command. You need to either save your API access token) to an environment variable or substitute it in the command below.

curl -X POST -H 'Content-Type: application/json' \
         -H 'Authorization: Bearer '$TOKEN'' -d \
        '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image": "dokku-20-04"}' \
        "https://api.digitalocean.com/v2/droplets"

Getting Started After Deploying Dokku

Note: Please disable IPv6. There are known issues with IPv6. If you would like to run Dokku on an IPv6 DigitalOcean Droplet, please consult this guide.

In addition to the package installation, the One-Click also:

• Enables the UFW firewall to allow only SSH (port 22, rate limited), HTTP (port 80), HTTPS (port 443), and 2375/2376 for unencrypted/encrypted traffic to the Docker daemon, respectively.

Quickstart

After creating a Dokku Droplet 1-Click, you need to SSH into the Droplet and configure Dokku SSH keys, domains and virtual hosts. You can learn more about this by looking at Deploying sample application section

Deploying sample application

Once you have configured Dokku, you can deploy applications using git push:

# from your local machine
# SSH access to github must be enabled on this host
git clone https://github.com/heroku/ruby-getting-started`

Create the app

SSH into the Dokku host and create the application as follows:

# on the Dokku host
dokku apps:create ruby-getting-started

Create the backing services

The Getting Started app requires a PostgreSQL service, so install the plugin and create the related service as follows:

# on the Dokku host
# install the postgres plugin
# plugin installation requires root, hence the user change
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git

# create a postgres service with the name railsdatabase
dokku postgres:create railsdatabase

Each service may take a few moments to create.

Linking backing services to applications

Once the services have been created, you then set the DATABASE_URL environment variable by linking the service, as follows:

# on the Dokku host
# each official datastore offers a `link` method to link a service to any application
dokku postgres:link railsdatabase ruby-getting-started

Dokku supports linking a single service to multiple applications as well as linking only one service per application.

Deploy the app

To be able to deploy to your Dokku server, you need to add your public SSH keys to the Dokku key list. You can create a new file on your Dokku host and copy your public SSH key or use commands like scp.

Now you can add your newly created public SSH key to the Dokku key list:

$ on the Dokku host
dokku ssh-keys:add KEY_NAME path/to/your/public_key.pub

KEY_NAME is the name you want to use to refer to this particular key. Including the word admin in the name will grant the user privileges to add additional keys remotely.

You can learn more about configuring SSH keys on the Dokku Official User Management page

Now you can deploy the ruby-getting-started app to your Dokku server. All you have to do is add a remote to name the app. Applications are created on-the-fly on the Dokku server.

# from your local machine
# the remote username *must* be dokku or pushes will fail
cd ruby-getting-started
git remote add dokku dokku@dokku.me:ruby-getting-started
git push dokku main:master

Note: If you are seeing a denied error make sure you are using the correct private key for git push. Your private key must match the public key you used during the previous step.

After running git push dokku main:master, you should have output similar to this in your terminal:

Counting objects: 231, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (162/162), done.
Writing objects: 100% (231/231), 36.96 KiB | 0 bytes/s, done.
Total 231 (delta 93), reused 147 (delta 53)
-----> Cleaning up...
-----> Building ruby-getting-started from herokuish...
-----> Adding BUILD_ENV to build environment...
-----> Ruby app detected
-----> Compiling Ruby/Rails
-----> Using Ruby version: ruby-2.2.1
-----> Installing dependencies using 1.9.7
       Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment
       Fetching gem metadata from https://rubygems.org/...........
       Fetching version metadata from https://rubygems.org/...
       Fetching dependency metadata from https://rubygems.org/..
       Using rake 10.4.2

...

=====> Application deployed:
       http://%SUBDOMAIN%.%DOMAIN%

Once the deployment is complete, the application’s web URL will be generated as above.

The SUBDOMAIN is inferred from the pushed application name, while the DOMAIN is set during the initial Dokku configuration. It can then be modified with dokku domains:add-global and dokku domains:remove-global. This value is used as a default domain for all applications on a host.

Check the official documentation to learn more about domain configuration.