Blissful Personal Project Deployment: Dokku + Let's Encrypt = 😁
Update: I no longer use Dokku and the Let's Encrypt plugin is no longer maintained or working. Please look for a new solution!
If you are like me, you have a ton of personal programming projects lying around from weekend experiments sparked by your latest idea. At the end of a project, you'll want to show it off to others so you want to give your project a home on the internet. In the case of any web application, this means time spent configuring your server for each of the small apps.
The time for tedious configuration and troubleshooting is over! I'm here to present you an elegant, free, open source and self-hosted way for deploying your small projects based on the Dokku self-hosted PaaS with git push-style deploys. All you need is a (virtual) server you have root access to and a domain name (something you can get from ~5$ a month by now).
In this article, I'll show you the workflow of deploying a simple web application using Dokku and setting up free and automatically renewed HTTPS certificates using dokku-letsencrypt. Here, we'll use a simple Express.js project for demonstration purposes but Dokku supports all frameworks that have a Heroku buildpack available.
While deploying on Dokku wont't scale to multiple servers if your personal project should take off, you will still be able to easily move hosting of your app to its own Heroku dyno or set up your own Deis cluster since you have everything cleanly packaged as a 12-factor app already.
A Demo App
Let's start by making a quick Express.js app:
For the Heroku node.js buildpack, the default behaviour is to start the project using npm start so we configure our package.json to run node index to start our application. If you want to change the defaults, you can also use a Heroku-style Procfile
The PORT environment variable will be set by Dokku, telling us what port the app should listen on. For local testing, we fall back to port 3000 if the environment variable is not set.
Automatic git push Deploy
Time to deploy! I initialize git on my project and push my project to the magic dokku remote.
Dokku will accept the folder name as a new subdomain name, auto-detect which buildpack to use and compile and deploy the project.
The next time that you push to the dokku remote, Dokku will rebuild and start your app in a background container and only switch over HTTP requests from the old, running version of the app once the new version of the app is running successfully, giving you zero-downtime deploys for free.
You can add a CHECKS file to the root of the git repository to make Dokku check for certain strings to determine whether your app was built successfully and to fine-tune the waiting time between checking attempts, resulting in faster deploys.
Bonus: Adding Databases, Services, etc.
For any real-world project, you probably will want to have ways of storing your data. Dokku solves this by plugins that you can install and official plugins for Postgresql, MariaDB, Redis, etc. are available. Alternatively, you can use docker volume mounts to access folders on the container host system.
Bonus: Deploying from Dockerfiles
If your project has grown more complicated than what would be covered by one or more buildpacks, you can also deploy a Docker container by uploading a Dockerfile to Dokku. See Dockerfile deployment on the Dokku docs.
Automatic free HTTPS with dokku-letsencrypt
Why not add some free HTTPS? Setting up HTTPS will improve our search engine ranking and make our site load quicker once HTTP/2 is supported. Plus, with the dokku-letsencrypt plugin that I've previously talked about, it's very easy to do so:
Setting this up yourself
If you are interested after this demonstration, great! See the Dokku docs on how to begin setting up your virtual server to host Dokku apps. After a successful install, check out the official plugins list. For this demo, I was only using the dokku-letsencrypt plugin.
If you're still in need of a virtual server to try it on, good cheap solutions are available e.g. from DigitalOcean or OVH - Note: the DigitalOcean link is a referral link that will give you 10$ in credit upon signup (and 25$ to me) - enough to try Dokku for free for two months. If you prefer to sign up yourself, you can use this link instead (and there is discount codes for 10$ of free credit if you google for a bit).
Automatic Certificate Renewal
Finally, to make sure that these certificates don't run out, dokku-letsencrypt provides a letsencrypt:auto-renew command that will keep all certificates up to date although you will have to set up a cronjob for the server to make the command run. See my guide on how to do so.