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.
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
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.
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.
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.
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 email@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
example.com will now serve your
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_EMAILfirstname.lastname@example.org
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.
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
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.
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
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.