Docs: Let's Encrypt certificate for GitLab Pages

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
+```