Dokku

Installation

If the distribution is Debian based, you can install Dokku using the following command:

# Install Dokku using the provided script.
# For debian systems, installs Dokku via apt-get
wget https://raw.githubusercontent.com/dokku/dokku/v0.28.1/bootstrap.sh
sudo DOKKU_TAG=v0.28.1 bash bootstrap.sh

otherwise, you may need to follow the advanced installation guide.

Configuration

Some optional global configurations include adding a domain name to make connecting with the server easier or enabling the letsencrypt plugin to automatically generate and renew TLS certificates. An admin user can be added to provide commands to the dokku deamon using ssh.

# [OPTIONAL]
# Add a domain name to your server
sudo dokku domains:set-global "<domain name>"
# Add an SSH key to allow ssh access using the Dokku admin account
cat "<~/.ssh/authorized_keys or /path/to/the/public/key>" | sudo dokku ssh-keys:add admin

To protect against misconfigurations and human errors it is better to include the Dokku acl plugin. This way each app can have an account associated with it, and only the account can alter the state of the app.

# Add the ACL plugin
sudo dokku plugin:install https://github.com/dokku-community/dokku-acl.git acl

By default, each user can push and create repositories.
To limit the permissions of non-admin users, you can use the ACL plugin settings, by adding the desired lines to the /home/dokku/.dokkurc/acl file:

# ~dokku/.dokkurc/acl

# Add the admin user This also limits the permissions of the other users
export DOKKU_SUPER_USER=admin
# Commands that can be executed by any user
export DOKKU_ACL_USER_COMMANDS="help version"
# Commands that can be executed by an user with access to the application
export DOKKU_ACL_PER_APP_COMMANDS="logs urls ps:rebuild ps:restart ps:stop ps:start ps:scale git-upload-pack git-upload-archive git-receive-pack git-hook"

Create an app

To create an app, you can use the dokku apps:create command.

# Create an app
dokku apps:create "<app name>"

It would be ideal to give each application its own account, so it can be used in the CI/CD pipeline with minimal risk. If the application is ever deleted, the account can be deleted as well without.

# Generate the pk-sk pair for the ssh login used to deploy the application
ssh-keygen -t rsa -b 2048 -C "<user name>"
# Add the public key to the authorized_keys file
cat "/path/to/the/public/key" | sudo dokku ssh-keys:add "<user name>"
# Use the ACL plugin to add the user to the application
sudo dokku acl:add "<application name>" "<user name>"
# Add the ACL permissions to the app
dokku acl:add "<app name>" "<user name>"

By default, each app will be created with a web process. If you only need a worker process, o need more than one instance of the process you can set the configuration accordingly.

# Set the number of the web and worker instance for the application
dokku ps:scale "<app name>" web=0 worker=1

Github action

To integrate Dokku with Github actions, you can use the official github action. You will need to provide the following secrets:

• DOKKU_GIT_REMOTE_URL: The host of the Dokku server, reachable through ssh.
  • ssh://dokku@<domain name or ip>:22/<app name>
  • ssh://dokku@dokku.me:22/appname
• DOKKU_SSH_PRIVATE_KEY: The private key of the user who has the permissions to deploy the application.
  • -----BEGIN RSA PRIVATE KEY-----\n<private key>\n-----END RSA PRIVATE KEY-----

Example

# .github/workflows/deploy.yml
name: "Deploy Github action"

on:
  push:
    branches:
      - master

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Test
        run: echo "Test"

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Cloning repo
        uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - name: Push to dokku
        uses: dokku/github-action@master
        with:
          git_remote_url: ${{ secrets.DOKKU_GIT_REMOTE_URL }}
          ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }}