This is part 1 of a 3 part tutorial:

• Part 1 – dokku: a mini-Heroku on your VPS (this post)
• Part 2 – Heroku-like WordPress deployments with git and dokku
• Part 3 – Advanced WordPress configuration on dokku (coming soon)

As a developer, I love git based deployments. They take the fuss out of pushing code updates to the server, only require that we update what’s changed, and are easy for anyone on our engineering team to implement, because all of us already work in git every day.

For deployment on a VPS, Dokku is an excellent little project that allows us to use the same configuration and build packs as Heroku, but on the scale of a single VPS. This gives us all the advantages of a container based setup powered by docker, but on a small scale. You can easily use this to host a test server with a number of sites, or a number of personal projects, all running different languages and requirements, if needed.

Let’s get dokku up and running

1. Spin up a VPS

My favorite VPS provider is DigitalOcean. They have a clean administration interface and wide selection of base images and pre-installed applications. In this case, we can select Dokku preinstalled on Ubuntu 14.04.

You can also install dokku manually on your Debian-based Linux distribution (dokku depends on apt-get). If you don’t have another preference, start with a bare Ubuntu box.

2. Setup a domain

dokku works best with a domain name that points to your server. This way, each separate application exists at a subdomain of the primary domain for the server. (Ex: myapp.dokku.me) So change your domain’s DNS settings to point to the IP address of your dokku server.

3. Finish dokku setup

If using Digital Ocean, this is easy for you. Visit your server in a web browser at the domain you setup in step 2 and enter the ssh key you’d like to use for your docker user and enter your domain as the hostname. You can see more details on this page https://www.digitalocean.com/community/tutorials/how-to-use-the-dokku-one-click-install-image-to-deploy-your-app#step-two-––-access-the-droplet-to-complete-configuration

For other VPS servers, you can install dokku manually. The automated install script didn’t work for me, so here’s the manual process (also described in the dokku docs).

a. From within your VPS, clone the git repo and run make install

$ git clone https://github.com/progrium/dokku.git
$ cd dokku
$ sudo make install

b. Make sure /home/dokku/VHOST is set to the domain of the server

myserver.com

c. Add your ssh key for the dokku user. From your local machine:

$ cat ~/.ssh/id_rsa.pub | ssh myserver.com “sudo sshcommand acl-add dokku $USER”

 4. Call dokku from your local machine:

# This should give you a list of dokku commands you can run on the remote server
$ ssh -t dokku@myserver.com help

Usage: dokku COMMAND <app> [command-specific-options]

  apps:create <app>                               Create a new app
  apps:destroy <app>                              Permanently destroy an app
  apps                                            List your apps
  backup:export [file]                            Export dokku configuration files
  backup:import [file]                            Import dokku configuration files
  config <app>                                    Display the config vars for an app
  config:get <app> KEY                            Display a config value for an app
  config:set <app> KEY1=VALUE1 [KEY2=VALUE2 …]    Set one or more config vars
  config:unset <app> KEY1 [KEY2 …]                Unset one or more config vars
  domains:add <app> DOMAIN                        Add a custom domain to app
  domains <app>                                   List custom domains for app
  domains:clear <app>                             Clear all custom domains for app
  domains:remove <app> DOMAIN                     Remove a custom domain from app
  help                                            Print the list of commands
  logs <app> [-t]                                 Show the last logs for an application (-t follows)
  nginx:build-config <app>                        (Re)builds nginx config for given app
  nginx:import-ssl <app>                          Imports a tarball from stdin; should contain server.crt and server.key
  plugins-install                                 Install active plugins
  plugins                                         Print active plugins
  plugins-update                                  Update active plugins
  run <app> <cmd>                                 Run a command in the environment of an application
  url <app>                                       Show the first URL for an application (compatibility)
  urls <app>                                      Show all URLs for an application
  version                                         Print dokku’s version

5. Create a sample application:

git clone git@github.com:heroku/node-js-sample.git node-app
$ cd node-app
$ git remote add dokku dokku@myserver.com:node-app
$ git push dokku master
Counting objects: 296, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (254/254), done.
Writing objects: 100% (296/296), 193.59 KiB, done.
Total 296 (delta 25), reused 276 (delta 13)
——> Building node-app …
       Node.js app detected
——> Resolving engine versions

… blah blah blah …

——> Application deployed:
       http://node-app.myserver.com

 

Boom… your own mini-Heroku with easy git push deployments