How do I use let’s encrypt with gitlab?

Question

I started to look in to ssl certificates when I stumbled upon let's encrypt, and I wanted to use it with gitlab, however being that it is running on a raspberry pi 2 and its running quite perfectly now (so I dont want to mess anything up), he would I go about installing a lets encrypt ssl certificate properly? PS: My installation is omnibus

Answer 1

The by far best solution I was able to find for now is described in this blog post. I won't recite everything, but the key points are:

• Use the webroot authenticator for Let's Encrypt
• Create the folder /var/www/letsencrypt and use this directory as webroot-path for Let's Encrypt

• Change the following config values in /etc/gitlab/gitlab.rb and run gitlab-ctl reconfigure after that:

  nginx['redirect_http_to_https'] = true nginx['ssl_certificate']= "/etc/letsencrypt/live/gitlab.yourdomain.com/fullchain.pem" nginx['ssl_certificate_key'] = "/etc/letsencrypt/live/gitlab.yourdomain.com/privkey.pem" nginx['custom_gitlab_server_config']="location ^~ /.well-known {\n alias /var/www/letsencrypt/.well-known;\n}\n" 

• If you are using Mattermost which is shipped with the Omnibus package then you can additionally set these options in /etc/gitlab/gitlab.rb:

  mattermost_nginx['redirect_http_to_https'] = true mattermost_nginx['ssl_certificate']= "/etc/letsencrypt/live/gitlab.yourdomain.com/fullchain.pem" mattermost_nginx['ssl_certificate_key'] = "/etc/letsencrypt/live/gitlab.yourdomain.com/privkey.pem" mattermost_nginx['custom_gitlab_mattermost_server_config']="location ^~ /.well-known {\n alias /var/www/letsencrypt/.well-known;\n}\n" 

• After requesting your first certificate remember to change the external_url to https://... and again run gitlab-ctl reconfigure

This method is very elegant since it just mounts the directory /var/www/letsencrypt/.well-known used by the Let's Encrypt authenticator into the Gitlab web-root via a custom Nginx configuration and authentication is always possible when Gitlab is running. This means that you can automatically renew the Let's Encrypt certificates.

Answer 2

There are 2 ways depending on your infrastructure setup (Raspi, big Cloud server or something in between):

1. If you have an externally accessible Server (means your Gitlab host is callable from the Let´s Encrypt servers, which is needed for Let´s Encrypt´s automatic mechanism of verifying that you "own" a certain domain like gitlab.yoursite.com and the corresponding and DNS resolved server/host) the only thing needed (from Gitlab version 10.7 on) is to add an s to the http in your Gitlab URL configuration in /etc/gitlab/gitlab.rb (as marcolz already mentioned):

   external_url 'https://gitlab.yoursite.com'

From the docs in https://docs.gitlab.com/omnibus/settings/ssl.html#let-39-s-encrypt-integration:

Omnibus-gitlab can automatically fetch and renew certificates from Let's Encrypt for you.

2. If your Gitlab host is not externally accessible by the Let´s Encrypt servers, the whole process is much harder! You´ll then leave the nice automatic way of letting Gitlab Omnibus do the heavy lifting for you. You definitely need to fetch the Let´s Encrypt certificates on your own now! There are some ways to fetch Let´s Encrypt certificates without the need for an externally accessible server.

   The one I choose and would recommend is to use the alternative Let´s Encrypt client dehydrated together with the dns-lexicon to fully automate the process of obtaining the certificates together with the Let´s Encrypt dns-challenge, which was introduced somewhere in 2016. This is the only way, where you don´t need an externally accessible server - but you again need to "own" a certain domain like gitlab.yoursite.com AND you need API access to the DNS provider, which hosts your domain (here´s a list of supported DNS providers in that case).

   As the whole process is quite complex I created a fully comprehensible Ansible playbook prepare-gitlab.yml where every step of the Gitlab installation with Omnibus is handled for you (full GitHub sources are available here: https://github.com/jonashackt/gitlab-ci-stack).

   If you only want to create the Let´s Encrypt certificates, have a look into obtain-letsencrypt-certs-dehydrated-lexicon.yml - even if you don´t want to use Ansible, you can also manually reproduce every step on the console or use another automation tool like Chef or Saltstack (although I can´t recommend that personally). Another way would be to have a look onto this great blogpost from the lexicon guys: https://blog.thesparktree.com/generating-intranet-and-private-network-ssl, from those described steps I basically developed the playbook from.

   Either way you choose, don´t forget to copy the manually (or automatically) fetched Let´s Encrypt certificates from

   /srv/dehydrated/certs/{{ gitlab_domain }}/fullchain.pem

   to

   /etc/gitlab/ssl/{{ gitlab_domain }}.crt

   and

   /srv/dehydrated/certs/{{ gitlab_domain }}/privkey.pem

   to

   /etc/gitlab/ssl/{{ gitlab_domain }}.key

   Gitlab will pick them up from there automatically for you, as the docs state in the way to manually configure HTTPS