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

Solution 1

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

Solution 2

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.

Solution 3

I have no idea if the installation differs on a Raspberry Pi. Let's Encrypt installation process does some magic I don't know anything about.

Prepare Gitlab

Type grep 'external_url' /etc/gitlab/gitlab.rb to check the website name. As an example https://gitlab.example.com:50000

If your external URL does not start with https, change it to begin with https

The part in bold will be your <your domain name>

Generate the certificates

Follow the Let's Encrypt install instructions on this link: https://letsencrypt.org/howitworks/

I'm not copying the instructions since they may change (as the program is in open beta right now). What you have to run depends on whether you also have websites running on Apache you want to generate Let's Encrypt certs for.

Once you have generated your Let's Encrypt certificates, they are located in /etc/letsencrypt/live/<your domain name>/

Copy the certificates

Gitlab expects two files located in /etc/gitlab/ssl/

There's something I'm not sure about, you may have to convert the .pem certificates using the answer at this location: Convert .pem to .crt and .key

Copy the certificate from /etc/letsencrypt/live/<your domain name>/cert.pem to /etc/gitlab/ssl/<your domain name>.crt

Copy the private key from /etc/letsencrypt/live/<your domain name>/privkey.pem to /etc/gitlab/ssl/<your domain name>.key

Reconfigure

Run gitlab-ctl reconfigure

Solution 4

You need to install the generated certificates manually in /etc/gitlab/ssl and set the external url to https in /etc/gitlab/gitlab.rb as described in: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/nginx.md

Solution 5

In case it's helpful to anybody else, I wrote up the process I used here: http://kelan.io/2016/using-lets-encrypt-to-add-ssl-to-gitlab/

I had set up GitLab previous (via install from source), and was just trying to add SSL, using Let's Encrypt.

The key points are:

• Use the standalone mode of letsencrypt
• Make a copy of the certs readable by gitlab-shell

View more solutions

Comments

[chabad360]

One thing, and then i'll be able to mark your answer and "the answer", where is the gitlab webroot?

[Hay]

I was unable to identify a webroot. In my case I have been using Apache to generate my certificates, and I believe --standalone should be used in this case (as per letsencrypt.org/howitworks ) if one does not use Apache. It might require shutting down gitlab temporaily though, I'm not sure.

[el.severo]

@Hay or chabad360 : have you managed to integrate the generated ssl certificate? the certificate is in the pem format but the nginx requires the *.cert format. How did you've handled that?

[Hay]

I'm starting to have doubts regarding my answer. Maybe stackoverflow.com/questions/13732826/convert-pem-to-crt-and-‌​key is a necessary step. To be honest my answer worked for me, but under special circumstances the content of my files might be completely ignored (but they need to exist in the filesystem).

[Mike H-R]

I had previously setup letsencrypt by stopping gitlab and then running it. Using the custom_gitlab_server_config allows me to put in a simple cron job to renew my certificate, without messing about with stopping gitlab first. Have you got any idea whether gitlab-ctl reconfigure would be needed when the .pem keys are rotated?

[rkallensee]

@MikeH-R Good question - I would say a gitlab-ctl reconfigure is not necessary since the configuration itself doesn't change, but to make nginx (and probably other components) pick up the new certificate a gitlab-ctl restart should be done. Probably a gitlab-ctl restart nginx is enough.

[chabad360]

do you know if its possible to keep my instance accessible from the local network, even if its over http and not https?

[waspinator]

you can use /opt/gitlab/embedded/service/gitlab-rails/public as the webroot directory for an omibus installation

[rkallensee]

@waspinator Also a good idea, although I think it's a bit more elegant to not let the Let's Encrypt authenticator write directly into GitLab directories but its own.

[waspinator]

you can similarly use nginx['custom_gitlab_mattermost_server_config'] to add letsencrypt to an omnibus mattermost install

[mcfedr]

You can now also add registry_nginx['custom_gitlab_server_config'] = "location ^~ /.well-known {\n alias /var/www/letsencrypt/.well-known;\n}\n" to the list

[mcfedr]

Note: there is currently a bug in the register config that prevents letsencrypt from working, you need to manually remove the extra : from the registry config - gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/789

[Jakob Lenfers]

@rkallensee and @waspinator, there is a typo in your mattermost config, the correct variable name is mattermost_nginx['custom_gitlab_mattermost_server_config']

[rkallensee]

@JakobLenfers Thanks, I changed the answer!