Running Dokku Locally

by Alexis Hope, 05 Jul 2021

Dokku is this great PaaS (platform as a service) tool to deploy applications. Its very easy to deploy to a linux box with a simple wget command you can run a script that sets up all the necessary tooling. All thats left is to enable a SSH key login. It sets up a remote git server which you can push to giving you a Heroku like experience. Once the SSH key access is configured you can set a new remote from a git project. Upon push Dokku will kick off a build process, wait for a health check and seamlessly swap out the previous instance (zero down time deploys). You get so much for free form this open source tool. The only downside is it operates on a single box so you can only scale up. But you can deploy multiple applications to a single box, and scale up running instances on that box. And given the size of machines these days scaling up can take my startup green field application quite far before having to consider horizontal scaling. A Linode box can be rented for $5 a month thats capable of running a Rails app, and if you need scale Linode can upgrade your system resources up to 192GB, 32 Cores, 3840GB SSD easily supporting multiple instances of your app. If you need scale beyond this Kubernetes with K8s or K3s are probably your next container orchestrations tool.

There are a few ways to configure the build process and the steps involved. But I stick with Dockerfiles for containerization. This keeps the application fairly platform agnostic. If down the track you find a single box scale up strategy isn’t going to work you can spin up Kubernetes on GCP and run these containers as pods or push to EC2 instances on AWS.

Running locally

There is a handy image already deployed to DockerHub which has a Dokku server installed find it here.

The documentation has a good command outlined to run the container with ports configured. But some of the other steps required to get an app set up are missing. Here is what you’ll need to do.

  1. Pull that Dokku image from DockerHub.
  docker pull dokku/dokku:latest
  1. Run that image with the command provided to run Dokku.
docker run \
  --env DOKKU_HOSTNAME=dokku.me \
  --name dokku \
  --publish 3022:22 \
  --publish 8080:80 \
  --publish 8443:443 \
  --volume /var/lib/dokku:/mnt/dokku \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  dokku/dokku:latest

The command uses a HOSTNAME of dokku.me with an SSH port of 3302. There are a few things we need to do to trick your local machine to push to this pretend domain.

  1. Edit your hosts file which bypasses dns look ups. Here we can point the domain dokku.me back to localhost (a loopback). We need admin privileges for this so we need to prefix with sudo here.
sudo vim /etc/hosts
# this is for mac and linux. Windows has a seperate location
# c:\windows\system32\drivers\etc\hosts

Add the following line which maps the IP to the domain. This file is checked first before doing a dns lookup which is handy for local development.

127.0.0.1 dokku.me
  1. Now the domain is configured the port is an issue.

Open up SSH config

vim ~/.ssh/config

And add the following

Host dokku.me
  AddKeysToAgent yes
  IdentityFile ~/.ssh/id_rsa # change to which ever identiy file you choose to use
  Port 3022
  User Dokku
  1. Copy your ssh key
cat ~/.ssh/id_rsa.pub | pbcopy # use copy for linux
  1. Jump into the running Dokku server and add your key
paste | dokku ssh-keys:add devmachine # now we're in a linux box so pbpaste isn't nessasary
  1. Create your app
dokku apps:create nim-test
  1. Finally add your remote
git remote add dokkudev dokku@127.0.0.1:3022:ruby-getting-started