diff options
author | Marcia Ramos <marcia@gitlab.com> | 2018-12-15 01:24:30 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axil@gitlab.com> | 2018-12-15 01:24:30 +0300 |
commit | 0d3a63aab2175232c8fc82b48a663cc3b05c2cf0 (patch) | |
tree | ad4c54c2503f6c520eade99d645c7cf6e323d2ae /doc/user | |
parent | b694788f7cb46df3d16edd5ca3251e53c20caa9c (diff) |
Docs: Let's Encrypt certificate for GitLab Pages
Diffstat (limited to 'doc/user')
-rw-r--r-- | doc/user/project/pages/getting_started_part_three.md | 27 | ||||
-rw-r--r-- | doc/user/project/pages/index.md | 2 | ||||
-rw-r--r-- | doc/user/project/pages/lets_encrypt_for_gitlab_pages.md | 158 |
3 files changed, 172 insertions, 15 deletions
diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 247e8d2a6a0..cea9628966d 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -234,26 +234,25 @@ reiterating the importance of HTTPS. ## Issuing Certificates -GitLab Pages accepts [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) certificates issued by -[Certificate Authorities (CA)](https://en.wikipedia.org/wiki/Certificate_authority) -and self-signed certificates. Of course, -[you'd rather issue a certificate than generate a self-signed](https://en.wikipedia.org/wiki/Self-signed_certificate), -for security reasons and for having browsers trusting your -site's certificate. - -There are several different kinds of certificates, each one -with certain security level. A static personal website will +GitLab Pages accepts certificates provided in the [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) format, issued by +[Certificate Authorities (CAs)](https://en.wikipedia.org/wiki/Certificate_authority) or as +[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/) +for public websites for security reasons and to ensure that browsers trust your site's certificate. + +There are various kinds of certificates, each one +with a certain security level. A static personal website will 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 to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/), which issues certificates trusted by most of browsers, it's open -source, and free to use. Please read through this tutorial to -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/). +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). -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/). -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/). ### Adding certificates to your project diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 7de9ae0caea..ce4fccdaff3 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -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: - [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 diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md new file mode 100644 index 00000000000..f639188684b --- /dev/null +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -0,0 +1,158 @@ +--- +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 +``` |