1 — Firstly get setup with a new server. Specs indicate 1Gb is needed at the very minimum. More is better but 1Gb seems fine for dev / testing. A service like Amazon Lightsail (https://amazonlightsail.com) is great for this as the cost is minimal ($10 per month) and they have UK data centres.
2 — Once the server is setup you will be provided with a Lightsail Public / Private key in PEM format. Download this somewhere secure and set its permissions correctly wherever you’ve saved it locally…
chmod 600 [PEM filename]
…should do it if your on a Mac.
3 — Publishing a site to Dokku is via git. To access git — its protected by public / private key auth — you will need to use a key — but not the PEM file you have received from Amazon. This is a mistake I made and — i’ll not lie — took me a while to work out. You need to extract the public key from the PEM file. To do so go to the directory you’ve saved the PEM file in and run the following command..
ssh-keygen -y -f [name of your PEM file] > [filename of public key file]
For example…
ssh-keygen -y -f lightsaildefault.pem > lightsaildefault.pub
Thanks to https://stackoverflow.com/questions/1011572/convert-pem-key-to-ssh-rsa-format for the answer to this…
Once you’ve got this, keep it close you’ll need it in the closing stages of Dokku config
4 — Right now follow the setup on the Dokku website (http://dokku.viewdocs.io/dokku/) basically…
wget https://raw.githubusercontent.com/dokku/dokku/v0.10.3/bootstrap.sh
sudo DOKKU_TAG=v0.10.3 bash bootstrap.sh
5 — Let the installer run and do its thing.
6 — The last step when the installer has completed you’ll need to go to the IP address of the server and enter the public key you extracted from the Amazon Lightsail PEM above. You’ll also need to decide if you want virtual host naming — so websites can be created, for example, on <app>.mydomainname.co.uk
7 — At this point Dokku is running and ready to accept new sites. Create one by entering the command
sudo dokku apps:create <app>
8 — Creating a Postgres service you need to install a plugin. To do so enter the following command to install the plugin…
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres
9 — Once the plugin is installed you can now create new Postgres service using the command…
sudo dokku postgres:create <db>
To link the service to your app (and get the database url environment variable) you now need to enter…
sudo dokku postgres:link <db> <app>
10 — If you want to install Postgres with PostGIS don’t do step 9 yet. You’ve an additional step to install an image for the Postgres plugin to use with PostGIS. Firstly run the command…
sudo docker pull mdillon/postgis:latest
This will pull a Postgres image with PostGIS installed.
11 — Once the command in 11 is complete you now need to tell the system to use it instead of the default image for Postgres when creating a database. To do so you need to set a couple of environment variables…
export POSTGRES_IMAGE=”mdillon/postgis” export POSTGRES_IMAGE_VERSION=“latest”
I tripped up here and couldn’t get it to work. The reason being is that the statements above set the environment variable for your current user — not the sudo user you run the commands under. The way round this — at least in my environment — was to include the -E flag when running the command to create the database so it becomes…
sudo -E dokku postgres:create <db>
12 — You should now have an app, database (and you should have linked using
sudo dokku postgres:link <db> <app>).
You now need to get a git remote added on your local project to send to this new app.
To do this i created an entry in ~/.ssh/config file pointing to the new server and using the pem file as the IdentityFile value. This looks like…
Host lightsail-dokku
Hostname <ip or domain>
User dokku
Port 22
IdentifyFile <pem file>
This is added as a separate hyphenated entry to differentiate the user from my main ssh one.
13 — Now to add the remote to your git project. In the local repository directory add the new remote using the following command…
git remote add <name> dokku@<host>:<app>
So in a hypothetical example…
git remote production dokku@lightsail-dokku:production-app
14 — You should then be able to push the local code and watch the output as it builds. As dokku uses build packs and technology from Heroku you can use runtime.txt to — for example — change the version of python to use or use a .buildpacks file to dictate which packs (or multiples) to use when building. That’s it, everything should be running as expected…