Glenn Jones

Letsencrypt free HTTPS for custom domain on gitlab pages with middleman

Edit: I used to have to do this manually every 3 months, taking a few minutes. These days Gitlab has automated it 👏. See gitlab letsencrypt docs

As of mid Dec 2015, Gitlab CE allows you to host static sites for free. Mid Feb 2016 they added support for custom domains. Fortunately, letsencrypt has been giving out free SSL-certs since Dec 2015 too, meaning it’s now possible to encrypt static websites that are:

The only caveat at this time is that a LetsEncrypt cert is valid for 3 months.

However, setting up and “refreshing” up an TLS-secured static custom domain is very easy. Gitlab has described that very well in the post securing your gitlab pages with tls and letsencrypt.


While following that tutorial, the script at some point asks you:

Make sure your web server displays the following content at
before continuing:

The gitlab tutorial uses jekyl, I will now how that’s done in Middleman:

In your config.rb, add a line:

proxy "/.well-known/acme-challenge/XK44QuuEjE9G2PhsigrGYgW9qbA8N7eEuXVg7hiVQmE", "/static/letsencrypt_https.html", :layout => false

This means: “expose /static/letsencrypt_https.html through the path /.well-known/acme-challenge/XK44QuuEjE9G2PhsigrGYgW9qbA8N7eEuXVg7hiVQmE”.

Next, in your middleman project dir, create the directory source/static and add to it the file letsencrypt_https.html.

In it, add only the full string as indicated by the letsencrypt-auto script. So the file should only contain one string, no tags, no nothing.

Now push to your git repo, let it build, deploy etc. Make sure that the url shows the right string (as required by the script) and then press enter in the letsencrypt-auto console. It will validate that the url shows the right output and provide you with a couple of files.

Now, you will need these two files to finalise your TLS cert installation. Go to your gitlab project, click settings -> pages. Add a new domain (such as or and copy the contents of the letsencrypt/live/ to the certificate PEM field and the contents of letsencrypt/live/ to the key PEM field. Create domain and you should be good to go.

A note: you’ll have to do this process separately for the non-www ánd www versions of your website.


Previous article: Import your production data from dokku-postgres
Next article: A no-nonsense, sane and safe password management strategy
comments powered by Disqus