Jump straight to the Setup Instructions section.
A few months ago I decided to migrate my Pelican site from Github to Gitlab. This was motivated largely by that fact that Gitlab has CI/CD built in by default. During this migration I also decided it was time to setup my own SSL certificate for unexpectedeof.net. Since this was new I looked around to see if there was any documentation readily available, and I found this wonderful tutorial from Fedora Magazine.
Between that and the Gitlab custom domain and ssl I was able to get up and running pretty quickly. I had accomplished my goals:
- migrate to Gitlab
- setup CI/CD of the Pelican site project
- setup ssl
Good to go, done in an afternoon with plenty of time to work on a new post. I thought.
About a week later I was on a different computer and instead of browing to https://unexpectedeof.net I went to https://www.unexpecteof.net and Firefox blocked my request citing an SSL certificate error. Wondering what I had done wrong I started tracing back through what I had done and realized that I had only setup SSL certificate for my primary domain. Luckily last year lets encrypt added support for wildcard certificates to certbot. Unfortunately that has not been included in a release so there's a couple steps that differ from the original Fedora article above.
Below are the steps to use certbot, gitlab pages and your domain management console to setup SSL for your subdomains. This assumes you are using a Debian based OS (I'm using Ubuntu 18.04) to install Certbot. If not swap out the certbot install steps for your OS and continue.
If you read the Fedora article linked above you do not need another key in
.well-known. Instead for your subdomain you will validate with certbot by a DNS record setup via your Domain Management Console.
sudo aptget install certbot
certbot certonly -a manual -d *.<yourdomainhere>.<topleveldomainhere> \ --config-dir ~/letsencrypt/config --work-dir ~/letsencrypt/work \ --logs-dir ~/letsencrypt/logs \ --server https://acme-v02.api.letsencrypt.org/directory
Follow the instructions entering your email, reviewing ToS, etc
You will then see this prompt:
Please deploy a DNS TXT record under the name _acme-challenge.unexpectedeof.net with the following value: <code>
Login to your domain management console and setup a txt record similar to:
|_acme-challenge||TXT||1800||your code from the terminal prompt above|
Once you have this setup it's a good idea to wait a couple minutes since this record will populate via DNS and then return to your console and hit enter.
Once certbot validates the
TXT record is available as part of your domain it will provide you the new location of your
privkey.pem files for use with Gitlab pages.
With these files ready to go browse to your Gitlab page settings and setup your subdomains as documented here and here.
I highly recommend reading the Gitlab documentation above, but to summarize:
- In your Gitlab pages project settings click add a new site
- Enter the url
- Add the data from your
privkey.pemfiles generated via certbot
- Copy the
gitlab-pages-verfication-code=section from the Gitlab validation record box
- Login to your domain management console
- Setup a new
TXTrecord for your subdomain:
- Setup a new
Arecord for Gitlab
- Return to your Gitlab Pages settings console and click the verify button.
With that you pages should show green and verified. If you browse to the different subdomains you setup then you should get through without any SSL problems.
One thing to note is that you will need to renew your certbot certificate every 90 days. This is done via the
certbot renew command. I've setup an Airflow dag to take care of this since I have Airflow managing various other things for me. You can see that here
Hopefully you find the above helpful. If you run into issues I recommend:
- Make sure you used the
*wildcard in the domain cert setup
- Setup your _acme-challenge record correctly in your domain management console and left it there
- Setup the right
Arecords for Gitlab