2019-02-15 15:39:39 +05:30
---
2021-01-29 00:20:46 +05:30
stage: Release
2021-02-22 17:27:13 +05:30
group: Release
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2019-09-30 21:07:59 +05:30
description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)."
2019-02-15 15:39:39 +05:30
---
2021-09-04 01:27:46 +05:30
# Let's Encrypt for GitLab Pages (manual process, deprecated) **(FREE)**
2019-09-30 21:07:59 +05:30
2021-02-22 17:27:13 +05:30
WARNING:
2019-09-30 21:07:59 +05:30
This method is still valid but was **deprecated** in favor of the
[Let's Encrypt integration ](custom_domains_ssl_tls_certification/lets_encrypt_integration.md )
introduced in GitLab 12.1.
2019-02-15 15:39:39 +05:30
If you have a GitLab Pages website served under your own domain,
2021-02-22 17:27:13 +05:30
you might want to secure it with a SSL/TLS certificate.
2019-02-15 15:39:39 +05:30
[Let's Encrypt ](https://letsencrypt.org ) is a free, automated, and
open source Certificate Authority.
## Requirements
To follow along with this tutorial, we assume you already have:
2019-12-26 22:10:19 +05:30
- [Created a project ](index.md#getting-started ) in GitLab
containing your website's source code.
2019-09-30 21:07:59 +05:30
- Acquired a domain (`example.com`) and added a [DNS entry ](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain )
2019-02-15 15:39:39 +05:30
pointing it to your Pages website.
2019-09-30 21:07:59 +05:30
- [Added your domain to your Pages project ](custom_domains_ssl_tls_certification/index.md#steps )
2019-02-15 15:39:39 +05:30
and verified your ownership.
- Cloned your project into your computer.
- Your website up and running, served under HTTP protocol at `http://example.com` .
## Obtaining a Let's Encrypt certificate
Once you have the requirements addressed, follow the instructions
below to learn how to obtain the certificate.
2021-01-03 14:25:43 +05:30
Note that these instructions were tested on macOS Mojave. For other operating systems the steps
might be slightly different. Follow the
2019-02-15 15:39:39 +05:30
[CertBot instructions ](https://certbot.eff.org/ ) according to your OS.
1. On your computer, open a terminal and navigate to your repository's
2019-09-30 21:07:59 +05:30
root directory:
2019-02-15 15:39:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
cd path/to/dir
```
2019-02-15 15:39:39 +05:30
1. Install CertBot (the tool Let's Encrypt uses to issue certificates):
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
brew install certbot
```
2019-02-15 15:39:39 +05:30
1. Request a certificate for your domain (`example.com`) and
2019-09-30 21:07:59 +05:30
provide an email account (`your@email.com`) to receive notifications:
2019-02-15 15:39:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
sudo certbot certonly -a manual -d example.com --email your@email.com
```
2019-02-15 15:39:39 +05:30
2019-09-30 21:07:59 +05:30
Alternatively, you can register without adding an e-mail account,
2021-03-08 18:12:59 +05:30
but you aren't notified about the certificate expiration's date:
2019-02-15 15:39:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
sudo certbot certonly -a manual -d example.com --register-unsafely-without-email
```
2019-02-15 15:39:39 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2019-09-30 21:07:59 +05:30
Read through CertBot's documentation on their
[command line options ](https://certbot.eff.org/docs/using.html#certbot-command-line-options ).
2019-02-15 15:39:39 +05:30
2021-03-08 18:12:59 +05:30
1. You're prompted with a message to agree with their terms.
2019-09-30 21:07:59 +05:30
Press `A` to agree and `Y` to let they log your IP.
2019-02-15 15:39:39 +05:30
2021-03-08 18:12:59 +05:30
CertBot then prompts you with the following message:
2019-02-15 15:39:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
Create a file containing just this data:
2019-02-15 15:39:39 +05:30
2019-09-30 21:07:59 +05:30
Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb
2019-02-15 15:39:39 +05:30
2019-09-30 21:07:59 +05:30
And make it available on your web server at this URL:
2019-02-15 15:39:39 +05:30
2019-09-30 21:07:59 +05:30
http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP
2019-02-15 15:39:39 +05:30
2019-09-30 21:07:59 +05:30
Press Enter to Continue
```
2019-02-15 15:39:39 +05:30
2021-03-08 18:12:59 +05:30
1. **Do not press Enter yet.** Let's Encrypt needs to verify your
2019-09-30 21:07:59 +05:30
domain ownership before issuing the certificate. To do so, create 3
consecutive directories under your website's root:
`/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/`
and add to the last folder an `index.html` file containing the content
referred on the previous prompt message:
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb
```
Note that this file needs to be accessed under
`http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP`
to allow Let's Encrypt to verify the ownership of your domain,
therefore, it needs to be part of the website content under the
2021-03-08 18:12:59 +05:30
repository's [`public` ](index.md#how-it-works ) folder.
2019-02-15 15:39:39 +05:30
2020-06-23 00:09:42 +05:30
1. Add, commit, and push the file into your repository in GitLab. Once the pipeline
2019-09-30 21:07:59 +05:30
passes, press **Enter** on your terminal to continue issuing your
2021-03-08 18:12:59 +05:30
certificate. CertBot then prompts you with the following message:
2019-09-30 21:07:59 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
Waiting for verification...
Cleaning up challenges
IMPORTANT NOTES:
- Congratulations! Your certificate and chain have been saved at:
/etc/letsencrypt/live/example.com/fullchain.pem
Your key file has been saved at:
/etc/letsencrypt/live/example.com/privkey.pem
Your cert will expire on 2019-03-12. To obtain a new or tweaked
version of this certificate in the future, simply run certbot
again. To non-interactively renew *all* of your certificates, run
"certbot renew"
- If you like Certbot, please consider supporting our work by:
Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate
Donating to EFF: https://eff.org/donate-le
```
2019-02-15 15:39:39 +05:30
## Add your certificate to GitLab Pages
Now that your certificate has been issued, let's add it to your Pages site:
1. Back at GitLab, navigate to your project's **Settings > Pages** ,
2019-09-30 21:07:59 +05:30
find your domain and click **Details** and **Edit** to add your certificate.
2019-02-15 15:39:39 +05:30
1. From your terminal, copy and paste the certificate into the first field
2019-09-30 21:07:59 +05:30
**Certificate (PEM)** :
2019-02-15 15:39:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy
```
2019-02-15 15:39:39 +05:30
2019-07-31 22:56:46 +05:30
1. Copy and paste the private key into the second field **Key (PEM)** :
2019-02-15 15:39:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy
```
2019-02-15 15:39:39 +05:30
1. Click **Save changes** to apply them to your website.
2019-07-31 22:56:46 +05:30
1. Wait a few minutes for the configuration changes to take effect.
2019-02-15 15:39:39 +05:30
1. Visit your website at `https://example.com` .
To force `https` connections on your site, navigate to your
2019-09-04 21:01:54 +05:30
project's **Settings > Pages** and check **Force HTTPS (requires
valid certificates)**.
2019-02-15 15:39:39 +05:30
## Renewal
2021-03-08 18:12:59 +05:30
Let's Encrypt certificates expire every 90 days and you must
2019-02-15 15:39:39 +05:30
renew them periodically. To renew all your certificates at once, run:
2020-03-13 15:44:24 +05:30
```shell
2019-02-15 15:39:39 +05:30
sudo certbot renew
```