Having the freedom of cloud infrastructure can be liberating but sometimes you just want a simple and easy solution to develop and deploy web applications. Dokku is an extensible, open source Platform-as-a-Service that can run on any single server of your choosing. With Dokku Ubuntu you can easily setup your very own PaaS in a very small implementation that is not hungry for server resources. Powered by Docker, Dokku can help you build and manage your application lifecycle in the cloud.

Dokku Ubuntu logo

This guide will help you get Dokku Ubuntu installed, configured, and tested, along with tips on getting the most out of your personal cloud platform. The instructions in this guide are intended for Ubuntu 14.04 or newer, but Dokku is also available on other Debian-based distributions as well as on CentOS.

Installing Dokku

Dokku runs on almost any hardware and is well at home in the cloud. To run Dokku, your server should have at least 1GB of RAM which makes the preconfigured 1CPU/1GB host an ideal starting point for testing your own PaaS.

Start by deploying a server with at least the minimum requirements.

If you have a domain name available, set the server hostname to a subdomain such as dokku.example.com. You should configure your DNS provider to point the subdomain including a wildcard to the public IP of your Dokku server. This will allow you to personalise the platform from the get-go.

We also recommend including your SSH keys to your server at deployment to make logging in more secure but also to make configuring Dokku easier later on. If you have not already added your public SSH keys at your UpCloud Control Panel, here is a quick introduction to Managing Your SSH Keys.

Once you have deployed your new Dokku server, download the installation bootstrap script and run it with a matching version number using the commands below.

wget https://raw.githubusercontent.com/dokku/dokku/v0.8.0/bootstrap.sh ~/
sudo DOKKU_TAG=v0.8.0 bash ~/bootstrap.sh

The installation takes only a couple of minutes and works the best on a freshly deployed system. The script will automatically install all the required dependencies including Docker Engine and Herokuish along with Dokku Ubuntu itself.

If you get an error saying your hostname could not be resolved or you do not have a domain name available you can use the default reverse DNS name of your UpCloud server for testing. It can be found at your UpCloud Control Panel in Server settings under IP Addresses tab. To change the hostname after deployment, set the system domain name in the /etc/hostname file on your server then restart the host.

Configuring the basic settings

When the installation is complete, you will need to perform a basic configuration available at a temporary web page on your Dokku server. Browse to your server domain name or IP address to finalise the installation.

Note: To secure your Dokku host, it is important to complete the web setup process.

Dokku setup web page

If you already included an SSH key at the server deployment it should show in the Public Key list for Admin Access. The keys in this list will be added to the dokku user account that is used to manage the application. Set at least one SSH key or include multiples each starting on their own line.

The Hostname field should show your domain name set when deploying the server. If you do not have a domain name available, you can use the default reverse DNS name again here.

Lastly, if you have a domain name set and configured at your DNS provider, you may wish to enable the virtual host naming for apps. The option tells Dokku to make installed services accessible through <app-name>.dokku.example.com subdomains. Make sure to configure a wildcard A record for your domain to allow access to the application subdomains.

A   *.dokku.example.com   <publi IP address>

When you have made the changes and selections you wish, click the Finish Setup button at the bottom of the page to apply the settings. Finalising the settings will close the setup page preventing unauthorised access to adding public keys to your host.

Your Dokku Ubuntu platform should now be installed and ready to deploy applications. Continue below with testing the platform with a simple example app.

Testing the platform

Dokku integrates well with GitHub and its tools. Deploying applications can be done through git commands from your local machine allowing Heroku-compatible applications to be easily pushed onto a server. The applications are build with Heroku build packs and run isolated in their own containers creating a single-host cloud Heroku setup.

To get the most out of Dokku, you will need a GitHub account. Sign up if you have not already and add an SSH key to your account for secure authentication from your local system. Make sure to add keys to your local SSH agent for both the GitHub and your Dokku server.

Start by creating a new application on your Dokku server using the command below.

# On your Dokku server
dokku apps:create ruby-rails-sample

The app will require a Postgres plugin which can be installed with the following command.

# Install Postgres plugin your Dokku server
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git

Then create a new database for the sample app.

# Create a database on your Dokku server
dokku postgres:create rails-database

The official datastore offers a method to link the database service to an application. Use the command underneath to enable the sample app to access the database reserved for it.

# Link the database to the application on your Dokku server
dokku postgres:link rails-database ruby-rails-sample

With the Dokku server ready to receive the application, continue by downloading the sample app from GitHub on your local computer. In case you do not already have Git installed, you can find quick installation instructions for many different operating systems over at the git download page. The commands below are intended to be run on a Linux system.

# On your local system
git clone [email protected]:heroku/ruby-rails-sample.git ~/ruby-rails-sample

Then change into the downloaded repository directory and add a new remote location for git that points to your Dokku server with the application name added to the end of the domain name as shown in the example command below. Replace the <dokku.example.com> with your domain name.

# On your local system
cd ~/ruby-rails-sample
git remote add dokku [email protected]<dokku.example.com>:ruby-rails-sample

You can now deploy the application onto your Dokku server with the following command.

# On your local system
git push dokku master

Once the deployment finishes, the application should be available on your Dokku server at the URL show at the end of the output ruby-rails-sample.<dokku.example.com> for example. Click the link in your terminal or browse to the address to test the application.

Ruby Rails sample page

Congratulations, when you get a hello page similar to the example above, you have successfully deployed your first app on Dokku.

Conclusions

Deploying a single host scalable Platform-as-a-Service in the cloud could not be much easier than with Dokku. One of the strengths of Dokku is the extent of already available plugins, but also that Dokku is making it possible to write your own in any language. Sharing your plugins online and extending those already available will help the platform to grow. Dokku’s simple core is intended to be easy to hack and expand upon with features you need.