Quick Links

Dokku is a Platform-as-a-Service (PaaS) implementation, which you can self-host on your own hardware. Dokku uses Docker to automatically deploy your code when you git push from your terminal.

Setting up a Dokku server lets you quickly deploy new applications using the familiar Git workflow. Hosting costs can be much lower than commercial PaaS solutions and managed Kubernetes offerings. Once your Dokku server's up and running, launching a new application should only take a few moments.

Getting Started

Dokku supports several installation methods. When installing onto bare-metal hardware, use the official bootstrap script to download the latest version. 

wget https://raw.githubusercontent.com/dokku/dokku/v0.24.7/bootstrap.sh
    
    

            sudo DOKKU_TAG=v0.24.7 bash bootstrap.sh

The bootstrap script will transform a fresh Linux install into a functioning Dokku server. Software dependencies, including Docker, will be downloaded and installed automatically. The process could take up to 10 minutes, depending on your internet connection.

You can run Dokku as a Docker container. This is ideal when you're using an environment where Docker is already available. 

docker run 
    
    

             --env DOKKU_HOSTNAME=example.com 
    
    

             --name doku
    
    

             -p 3022:22 
    
    

             -p 8080:80 
    
    

             -p 8443:443 
    
    

             -v /var/lib/dokku:/mnt/dokku 
    
    

             -v /var/run/docker.sock:/var/run/docker.sock 
    
    

             dokku/dokku:0.24.7

Replace example.com with the hostname that you'll use to access your server. Using this example, ports 80 and 443 will be bound to your host ports 8080 and 8443, respectively. Port 3022 on your host will map to port 22 within the container. This port is used for Git+SSH connections.

A volume is created at /mnt/dokku. Dokku application data will be stored here. The host's Docker socket is also mounted into the container so that Dokku can interact with the Docker daemon to create new containers.

Configuring Dokku

After installation completes, visit your host's IP address in your browser. If you assigned Dokku a hostname, you can also use that here. The web installer will appear to guide you through the rest of the setup.

Copy and paste an SSH key into the "Public Key" field. Dokku will accept any SSH connections made with this key. You can add other keys later using the Dokku CLI.

Screenshot of Dokku web installer

You also need to configure your Dokku installation's hostname if it hasn't been set up. If you've got a domain mapped to your machine, enter that here. Otherwise, you can use localhost or an IP address.

When a hostname has been set up, Dokku can automatically serve your apps using individual subdomains. If you don't have a domain available, untick the "Use virtualhost naming" checkbox. Dokku will serve each of your apps on a dedicated port instead.

If you installed Dokku with Docker, web setup isn't supported. You can add a hostname when creating the container by setting the DOKKU_HOSTNAME environment variable. To add SSH keys, you'll need to connect to the container and use the Dokku CLI: 

docker exec -it dokku dokku ssh-keys add my-key < /path/to/key

Once you've set a hostname and added an SSH key, Dokku should be ready to use. No further administration is possible using the web UI. You interact with Dokku via Git commands and the CLI.

Deploying Applications

Now, you're ready to launch your first app! Dokku deployments start with a git push. Dokku uses buildpacks (either Cloud Native or Herokuish) to detect your app's programming language and automatically create a build.

Dokku also supports running docker build directly if your project contains a Dockerfile. This functionality can only be used when the buildpack-based builders are unavailable for your project. You can get more information on direct Docker builds in the Dokku documentation.

The use of buildpacks means that Dokku places few restrictions on how your project is created. If you're using a popular language and framework, you should be able to git push to create your deployment. Here's an example for a basic React app: 

mkdir my-app
    
    

            cd my-app
    
    

            npx create-react-app .
    
    

            git remote add dokku dokku@example.com:my-app
    
    

            git push dokku master

The last two lines are the most important. Your Dokku server is added as a Git remote so that you can push code to it. Replace example.com with the IP or hostname of your installation. The part after the colon indicates the Dokku project to push to. You don't need to create it manually.

After the remote has been set up, you're ready to push code to it. The example command pushes the master branch up to Dokku. Dokku will take your project, autodetect an appropriate buildpack, create a Docker image, and deploy your app.

Attaching App Domains

Dokku deploys your app to a subdomain of your hostname. You can attach a custom domain using the Dokku CLI. Make sure that you've set up appropriate DNS records first. 

dokku domains:add my-app example.com

Visiting example.com will now serve your my-app deployment.

Adding SSL

Dokku makes it easy to enable SSL for your apps. You can add a plugin that integrates Dokku with Let's Encrypt. Once the plugin has been installed, you can acquire SSL certificates with a single command.

First, install the plugin: 

dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

Next, configure the Let's Encrypt plugin with your email address. Let's Encrypt will use this address to send you any alerts relating to your certificates. 

dokku config:set --global no-restart DOKKU_LETSENCRYPT_EMAIL=me@example.com

You should add the Let's Encrypt cron job to make sure that Dokku can renew your certificates automatically: 

dokku letsencrypt:cron-job --add

Finally, enable Let's Encrypt for your application: 

dokku letsencrypt my-app

The Let's Encrypt plugin will acquire a certificate to cover the domains connected to your app. The certificate will be automatically renewed before it's due to expire.

Updating Your App

Dokku builds upon the Git workflow. You can update your app by making codebase changes, creating Git commits, and then pushing your branch to Dokku.

When Dokku receives a new push, it uses its buildpacks to construct an updated Docker container. The currently running container will be replaced with the new one after the build completes. Updates are downtime-less and fully automated.

The duration of the build process will vary depending on the size of your app and the technologies that it uses. Dokku waits a further 10 seconds after the build completes before traffic is directed to new containers. This gives any bootstrap scripts a chance to complete.

Dokku can easily be integrated into continuous integration (CI) systems. The final stage in a CI pipeline could be a git push dokku to update your live deployment.

Managing Branches

Dokku usually deploys changes made to the master branch. You can choose to use a different branch using a global or per-app setting: 

dokku git:set --global deploy-branch dokku-deploy
    
    

            dokku git:set my-app deploy-branch production

With this configuration, Dokku will default to deploying from the dokku-deploy branch. Deployments for the my-app app will be made from production instead.

Adding Extra Functionality

There's much more to Dokku than the basic deployment we've focused on here. The default distribution is intentionally streamlined. Official and community plugins can be used to provide services, such as databases and authentication. This allows you to use Dokku for stateful backends as well as for your static frontends.

Setting up a service is generally a two-step process. You create an instance of the service and then link it into your apps. Multiple apps can be connected to each service instance.

Here's how you can add a MySQL database to an app: 

dokku plugin:install https://github.com/dokku/dokku-mysql.git
    
    

            dokku mysql:create demo-db
    
    

            dokku mysql:link demo-db my-app

Dokku will set the DATABASE_URL environment variable inside your app container. You can access this variable to retrieve the MySQL connection string. Using Dokku plugins for databases removes the need to manage another external database server.

Conclusion

Docker is a PaaS solution that lets you host your own application platform. Once Dokku is up and running, launching a new app is as simple as a git push.

Dokku compares favorably with services such as Heroku, Amazon Elastic Beanstalk, and Google Firebase. It supports a large number of development technologies and means that you're not tied into a particular cloud provider. You can run Dokku on a cheap cloud-based VM or keep it on your own physical hardware.