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
-
There's a nice article here for anyone who wants to set this up with GitLab's free hosted service: about.gitlab.com/2016/04/11/…– igneosaurApr 23, 2016 at 15:35
-
You can also have a look at step by step instructions here : mkkhedawat.com/Enabling-HTTPS-for-Gitlab-pages-using-Certbot– mkkhedawatMar 14, 2018 at 12:45
7 Answers
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 aswebroot-path
for Let's Encrypt Change the following config values in
/etc/gitlab/gitlab.rb
and rungitlab-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
tohttps://...
and again rungitlab-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.
-
2@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 agitlab-ctl restart
should be done. Probably agitlab-ctl restart nginx
is enough. Jan 7, 2016 at 13:36 -
1@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. Apr 1, 2016 at 13:22
-
1you can similarly use nginx['custom_gitlab_mattermost_server_config'] to add letsencrypt to an omnibus mattermost install Apr 27, 2016 at 19:30
-
1@rkallensee and @waspinator, there is a typo in your mattermost config, the correct variable name is
mattermost_nginx['custom_gitlab_mattermost_server_config']
Jul 17, 2016 at 16:31 -
1
There are 2 ways depending on your infrastructure setup (Raspi, big Cloud server or something in between):
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.
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 likegitlab.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
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
-
One thing, and then i'll be able to mark your answer and "the answer", where is the gitlab webroot? Dec 13, 2015 at 21:42
-
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.– HayDec 14, 2015 at 15:39
-
@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? Dec 15, 2015 at 11:40
-
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).– HayDec 16, 2015 at 0:05
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
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 ofletsencrypt
- Make a copy of the certs readable by
gitlab-shell
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
I prefer to use symlinks, so you dont need to copy the certificates. enter link description here
If your Gitlab instance is not internet accessible then you can't use Gitlab's built-in LetsEncrypt mechanism because it uses HTTP challenge/response on your Gitlab's URL. You can use DNS challenge/response without exposing your Gitlab to the internet and you can fully automate it.
This answer is written assuming a Gitlab Omnibus install.
If you don't want to or can't use the HTTP challenge/response method and you want to use the DNS method instead then you have to do it outside Gitlab. One way to do this is to use acme.sh instead of the built-in LetsEncrypt support offered by Gitlab.
You need a DNS provider with a supported API. If your DNS does not have an API then you can use a DNS Alias and another DNS that does have a supported API. I used LuaDNS which is free of cost for light usage such as this.
Without rewriting the documentation, it goes like this :
do whatever you need to do to register on your chosen API DNS and enable its API. On LuaDNS the API has to be explicitly enabled and you must validate your email address before the API will work. Note the API token.
create a subdomain, say
acme.example.com
on your API DNS. Note its nameservers.create
NS
records on yourexample.com
DNS foracme.example.com
pointing to each of those those nameservers, like this (note the trailing dot):acme.example.com NS ns1.myapidns.com.
set up a CNAME at your
example.com
DNS to point to your API DNS, like this (note the trailing dot):_acme-challenge.gitlab.example.com CNAME _acme-challenge.acme.example.com.
configure Gitlab to use SSL: add to
/etc/gitlab/gitlab.rb
:external_url "https://gitlab.example.com" letsencrypt['enable'] = false registry_external_url 'https://gitlab.example.com.:5050'
(the 3rd line can be omitted if you do not want to enable Gitlab Container Registry)
install prerequisites (if not already installed)
# apt install cron sudo
create an unprivileged user account for the
acme
process# useradd -U -m acme
Allow the
acme
user to reconfigure Gitlab so it can update certificates:# echo "acme ALL=(ALL) NOPASSWD: /usr/bin/gitlab-ctl reconfigure" >> /etc/sudoers
Make the directory where Gitlab expects to find the SSL certificate and key and grant
acme
write access:# mkdir /etc/gitlab/ssl # chgrp acme /etc/gitlab/ssl # chmod 775 /etc/gitlab/ssl
Install
acme.sh
asacme
user# su - acme $ curl -s https://get.acme.sh | sh -s [email protected]
obtain certificate (example for LuaDNS, others are similar - see documentation)
$ export LUA_Key="<my api-key>" $ export LUA_Email="<my email>" $ ~/.acme.sh/acme.sh --issue --dns dns_lua -d gitlab.example.com \ --challenge-alias acme.example.com
(this also sets up a crontab entry to renew the certificate automatically every 60 days)
install certificate
$ ~/.acme.sh/acme.sh --install-cert -d gitlab.example.com \ --key-file /etc/gitlab/ssl/gitlab.example.com.key \ --fullchain-file /etc/gitlab/ssl/gitlab.example.com.crt \ --reloadcmd "sudo gitlab-ctl reconfigure"
Note that the filenames under /etc/gitlab/ssl
must be named the same as your gitlab url and must use the key
extension for the key and crt
for the certificate. Note also that the certificate contains the full certificate chain. These things are expected by Gitlab.
If you have Gitlab Runners, you will need to re-register them using the new https://gitlab.example.com endpoint.