Dokku is dev ops for dummies and a simple way to deploy websites on a barebones VPS. In this tutorial, I will describe how to use it to host a static site, and setup global assets caching with free Cloudflare CDN and SSL certificate.
I use jekyll for this blog and until recently I was hosting it on GitHub Pages. I’ve decided to move it to self-hosting with Dokku. Later in this post I will explain why in my particular case self-hosting is a better option.
Some of the steps in this tutorial are identical to my previous post about migrating Rails app from Heroku to Dokku.
First, you need to purchase a barebones VPS and add an SSH access to it. I will not elaborate on how to do it in this tutorial.
Let’s assume that your VPS has an IP address
126.96.36.199 and your static website will use
my-static-site.com as a domain.
SSH into your VPS:
Next, you need to specify your app’s name:
You can now exit your VPS. All the remaining commands can be executed locally.
To finish the Dokku setup you need to go to your IP
188.8.131.52 in a browser and input your public SSH keys there. To check out your SSH keys you can visit the following URL:
https://github.com/[YOUR GITHUB USERNAME].keys
Set Dokku Git remote target
To enable automatic deployments when doing a git push you need to add following lines to your
Check if your setup is correct by running:
If everything is correct you should see the name of your app:
Setup buildpack and static content source
We will use an official Dokku NGINX buildpack for our static website. To enable it you need to run the following commands:
Official docs recommend using a
NGINX_ROOT variable to set the static content folder, but I prefer to use a custom NGINX config. It gives you more control and flexibility.
To do it add a
app-nginx.conf.sigil file to the root of your repo with the following contents:
Let’s explain some of the options:
worker_processesshould be set to the number of CPU cores on your VPS.
worker_connectionsstands for the number of client connections which can be served at the same time. Remember that a single browser could open multiple connections to your server.
root /app/www/docshere is where you specify a folder from which static content will be served. In my case, it is
docsdirectory in my Dokku repo.
try_files $uri $uri.html $uri/ =404;specifies what files NGINX will try to serve based on a request path. In case it does not manage to match any it will display
404.htmlfile with 404 HTTP status code.
Be aware that by adding this file you overwrite a custom Dokku NGINX template. You can find a default version here.
Add SSL and global assets CDN using Cloudflare
Setup global CDN
You should use Cloudflare DNS for your domain. If you don’t know how to set it up you can check out my previous tutorial.
Enabling CDN is as simple as ticking a cloud icon next to DNS config for your website:
If you have trouble with an old DNS entry cache not refreshing you can use whatsmydns.net to check if it has already propagated in another region of the world.
Setup SSL certificate
Cloudflare offers a free end-to-end SSL certificate. You need to set SSL config to
full and download private and public keys from the dashboard. To install certificates on your Dokku NGINX run the following commands:
Now you just need to add some static assets to your
docs/ repo folder and deploy the app by typing:
Your app should be up and running on
Advantages over GitHub Pages
Although GitHub Pages are free, you need to use a GitHub repo for them. If you don’t want to open source your site you need to pay for private repos. Using Dokku you can setup multiple NGINX instances on a single VPS. Currently, I am paying $5/month for a Digital Ocean VPS with 1GB RAM. RAM usage for this blog is ~2MB so I could host tens of static websites on this single low-end VPS. Together with free global assets CDN caching each of the NGXIN instances is able to handle loads of traffic. I verified it using Siege load testing.
You can check memory usage of your docker containers by accessing your VPS and running:
Access to traffic logs
Although you can install Google Analytics on the website hosted by GitHub Pages I’ve noticed that traffic statistics reported by GA are much lower than what I see in unique visitor statistics displayed by Cloudflare. It looks like a lot of people are using tracking blockers.
You can display your NGINX access logs by typing:
Alternatively, you can find them on your VPS in
/var/log/nginx/ and export for further analysis.
Control over cache settings
GitHub Pages use a global assets CDN however you don’t have a way to customize its settings. I could not increase caching duration for my assets and it negatively affected my Google Page Speed Insights rating. I use digest tags for all my assets so I can cache them for a maximum duration of 8 days offered by Cloudflare CDN. Download my free jekyll SEO template to see how it can be implemented for static websites.
You can also check out my previous post for more info about ways to optimize speed rating of your website.
With Dokku you can easily host static websites on a simple VPS without much dev ops skills. I really think that it is a viable alternative to commercial services like GitHub Pages giving you more control over your content.