Commit 9403faf2 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'docs-le-for-pages' into 'master'

Docs: Let's Encrypt certificate for GitLab Pages

Closes #51979

See merge request gitlab-org/gitlab-ce!23777
parents b694788f 0d3a63aa
...@@ -234,26 +234,25 @@ reiterating the importance of HTTPS. ...@@ -234,26 +234,25 @@ reiterating the importance of HTTPS.
## Issuing Certificates ## Issuing Certificates
GitLab Pages accepts [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) certificates issued by GitLab Pages accepts certificates provided in the [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) format, issued by
[Certificate Authorities (CA)](https://en.wikipedia.org/wiki/Certificate_authority) [Certificate Authorities (CAs)](https://en.wikipedia.org/wiki/Certificate_authority) or as
and self-signed certificates. Of course, [self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://securingtomorrow.mcafee.com/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/)
[you'd rather issue a certificate than generate a self-signed](https://en.wikipedia.org/wiki/Self-signed_certificate), for public websites for security reasons and to ensure that browsers trust your site's certificate.
for security reasons and for having browsers trusting your
site's certificate. There are various kinds of certificates, each one
with a certain security level. A static personal website will
There are several different kinds of certificates, each one
with certain security level. A static personal website will
not require the same security level as an online banking web app, not require the same security level as an online banking web app,
for instance. There are a couple Certificate Authorities that for instance.
There are some certificate authorities that
offer free certificates, aiming to make the internet more secure offer free certificates, aiming to make the internet more secure
to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/), to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/),
which issues certificates trusted by most of browsers, it's open which issues certificates trusted by most of browsers, it's open
source, and free to use. Please read through this tutorial to source, and free to use. See our tutorial on [how to secure your GitLab Pages website with Let's Encrypt](lets_encrypt_for_gitlab_pages.md).
understand [how to secure your GitLab Pages website with Let's Encrypt](https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/).
With the same popularity, there are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/), Similarly popular are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/),
which also offers a [free CDN service](https://blog.cloudflare.com/cloudflares-free-cdn-and-you/). which also offers a [free CDN service](https://blog.cloudflare.com/cloudflares-free-cdn-and-you/).
Their certs are valid up to 15 years. Read through the tutorial on Their certs are valid up to 15 years. See the tutorial on
[how to add a CloudFlare Certificate to your GitLab Pages website](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/). [how to add a CloudFlare Certificate to your GitLab Pages website](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/).
### Adding certificates to your project ### Adding certificates to your project
......
...@@ -170,7 +170,7 @@ optionally secure it with SSL/TLS certificates. You can read the following ...@@ -170,7 +170,7 @@ optionally secure it with SSL/TLS certificates. You can read the following
tutorials to learn how to use these third-party certificates with GitLab Pages: tutorials to learn how to use these third-party certificates with GitLab Pages:
- [CloudFlare](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) - [CloudFlare](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/)
- [Let's Encrypt](https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/) (mind that although this article is out-of-date, it can still be useful to guide you through the basic steps) - [Let's Encrypt](lets_encrypt_for_gitlab_pages.md)
## Advanced use ## Advanced use
......
---
description: "How to secure GitLab Pages websites with Let's Encrypt."
---
# Let's Encrypt for GitLab Pages
If you have a GitLab Pages website served under your own domain,
you might want to secure it with a SSL/TSL certificate.
[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:
- Created a [project](getting_started_part_two.md) in GitLab which
contains your website's source code.
- Acquired a domain (`example.com`) and added a [DNS entry](getting_started_part_three.md#dns-records)
pointing it to your Pages website.
- [Added your domain to your Pages project](getting_started_part_three.md#add-your-custom-domain-to-gitlab-pages-settings)
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.
NOTE: **Note:**
The instructions below were tested on macOS Mojave. For other
operating systems the steps might be slightly different. Follow the
[CertBot instructions](https://certbot.eff.org/) according to your OS.
1. On your computer, open a terminal and navigate to your repository's
root directory:
```bash
cd path/to/dir
```
1. Install CertBot (the tool Let's Encrypt uses to issue certificates):
```bash
brew install certbot
```
1. Request a certificate for your domain (`example.com`) and
provide an email account (`your@email.com`) to receive notifications:
```bash
sudo certbot certonly -a manual -d example.com --email your@email.com
```
Alternatively, you can register without adding an e-mail account,
but you won't be notified about the certificate expiration's date:
```bash
sudo certbot certonly -a manual -d example.com --register-unsafely-without-email
```
TIP: **Tip:**
Read through CertBot's documentation on their
[command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options).
1. You'll be prompted with a message to agree with their terms.
Press `A` to agree and `Y` to let they log your IP.
CertBot will then prompt you with the following message:
```bash
Create a file containing just this data:
Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb
And make it available on your web server at this URL:
http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP
Press Enter to Continue
```
1. **Do not press Enter yet.** Let's Encrypt will need to verify your
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:
```bash
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
repo's [`public`](index.md#how-it-works) folder.
1. Add, commit, and push the file into your repo in GitLab. Once the pipeline
passes, press **Enter** on your terminal to continue issuing your
certificate. CertBot will then prompt you with the following message:
```bash
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
```
## 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**,
find your domain and click **Details** and **Edit** to add your certificate.
1. From your terminal, copy and paste the certificate into the first field
**Certificate (PEM)**:
```bash
sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy
```
1. Copy and paste the public key into the second field **Key (PEM)**:
```bash
sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy
```
1. Click **Save changes** to apply them to your website.
1. Wait a few minutes for DNS propagation.
1. Visit your website at `https://example.com`.
To force `https` connections on your site, navigate to your
project's **Settings > Pages** and check **Force domains with SSL
certificates to use HTTPS**.
## Renewal
Let's Encrypt certificates expire every 90 days and you'll have to
renew them periodically. To renew all your certificates at once, run:
```bash
sudo certbot renew
```
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment