Add documentation for Let's Encrypt integrationdocs-letsencrypt

7 files changed, 47 insertions, 3 deletions

diff --git a/app/views/projects/pages_domains/_form.html.haml b/app/views/projects/pages_domains/_form.html.haml
index 5b657966909..50eadf8021d 100644
--- a/app/views/projects/pages_domains/_form.html.haml
+++ b/app/views/projects/pages_domains/_form.html.haml
@@ -33,7 +33,7 @@
             = sprite_icon("status_success_borderless", size: 16, css_class: "toggle-icon-svg toggle-status-checked")
             = sprite_icon("status_failed_borderless", size: 16, css_class: "toggle-icon-svg toggle-status-unchecked")
         %p.text-secondary.mt-3
-          - docs_link_url = help_page_path("user/project/pages/lets_encrypt_for_gitlab_pages.md", anchor: "lets-encrypt-for-gitlab-pages")
+          - docs_link_url = help_page_path("user/project/pages/getting_started_part_three.md", anchor: "using-certificates-provided-by-lets-encrypt")
           - docs_link_start = "<a href=\"%{docs_link_url}\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"text-nowrap\">".html_safe % { docs_link_url: docs_link_url }
           - docs_link_end = "</a>".html_safe
           = _("Let's Encrypt is a free, automated, and open certificate authority (CA) that gives digital certificates in order to enable HTTPS (SSL/TLS) for websites. Learn more about Let's Encrypt configuration by following the %{docs_link_start}documentation on GitLab Pages%{docs_link_end}.").html_safe % { docs_link_url: docs_link_url, docs_link_start: docs_link_start, docs_link_end: docs_link_end }
diff --git a/doc/administration/pages/img/lets_encrypt.png b/doc/administration/pages/img/lets_encrypt.png
new file mode 100644
index 00000000000..5ab63074e12
--- /dev/null
+++ b/doc/administration/pages/img/lets_encrypt.png
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md
index b5b8f124274..fb713cf69cd 100644
--- a/doc/administration/pages/index.md
+++ b/doc/administration/pages/index.md
@@ -265,6 +265,22 @@ verification requirement. Navigate to `Admin area ➔ Settings` and uncheck
 **Require users to prove ownership of custom domains** in the Pages section.
 This setting is enabled by default.
 
+### Let's Encrypt integration
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996) in GitLab 12.1.
+
+To allow users to
+[use SSL certificates provided by Let's Encrypt](../../user/project/pages/getting_started_part_three.md#using-certificates-provided-by-lets-encrypt)
+you need to enable integration.
+
+You need to:
+1. Choose an email on which you will recieve notifications about expiring domains.
+2. Visit [admin page](/admin/application_settings/preferences),
+3. Expand "Pages" settings group, enter email and accept Let's Encrypt's Terms of Service as shonw below.
+4. Click "Save changes".
+
+![Let's Encrypt settings](img/lets_encrypt.png)
+
 ### Access control
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5.
diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md
index bc9a11504cd..0cb86218783 100644
--- a/doc/user/project/pages/getting_started_part_three.md
+++ b/doc/user/project/pages/getting_started_part_three.md
@@ -244,11 +244,38 @@ with a certain security level. A static personal website will
 not require the same security level as an online banking web app,
 for instance.
 
+### Using certificates provided by Let's Encrypt
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996) in GitLab 12.1.
+
 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. See our tutorial on [how to secure your GitLab Pages website with Let's Encrypt](lets_encrypt_for_gitlab_pages.md).
+source, and free to use.
+
+#### Requirements
+
+Befor you can enable automatic provisioning of SSL certificate for you domain, we you should 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.
+- If you use **self-hosted** GitLab instance, you also need to ask you administrator to [enable integration with Let's Encrypt](../../../administration/pages/index.md#lets-encrypt-integration).
+
+If you've already done all that you can enable Let's Encrypt integration on domain settings page:
+
+![Enable Let's Encrypt](img/lets_encrypt.png)
+
+Note that issuance of cerficate and updating pages configuration **can take up to an hour**.
+
+If you already have SSL certificate in domain settings it will continue to work until it will replaced
+by Let's Encrypt's certificate.
+
+### Using certificates provided by CloudFlare
 
 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/).
diff --git a/doc/user/project/pages/img/lets_encrypt.png b/doc/user/project/pages/img/lets_encrypt.png
new file mode 100644
index 00000000000..2e825e84d92
--- /dev/null
+++ b/doc/user/project/pages/img/lets_encrypt.png
diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md
index 64b1e259292..47eddde7e3f 100644
--- a/doc/user/project/pages/index.md
+++ b/doc/user/project/pages/index.md
@@ -144,7 +144,6 @@ To learn more about configuration options for GitLab Pages, read the following:
 |---+---|
 | [Custom domains and SSL/TLS Certificates](getting_started_part_three.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. |
 | [CloudFlare certificates](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. |
-| [Let's Encrypt certificates](lets_encrypt_for_gitlab_pages.md) | Secure your Pages site with Let's Encrypt certificates. |
 |---+---|
 | [Static vs dynamic websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | A conceptual overview on static versus dynamic sites. |
 | [Modern static site generators](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) | A conceptual overview on SSGs. |
diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md
index 91a660c0f7a..a04f0c553a8 100644
--- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md
+++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md
@@ -6,6 +6,8 @@ last_updated: 2019-06-04
 
 # Let's Encrypt for GitLab Pages
 
+**This tutorial is DEPRECATED** in favor of [seemless integration](using-certificates-provided-by-lets-encrypt).
+
 If you have a GitLab Pages website served under your own domain,
 you might want to secure it with a SSL/TSL certificate.