summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAchilleas Pipinellis <axil@gitlab.com>2019-07-15 08:02:34 +0000
committerAchilleas Pipinellis <axil@gitlab.com>2019-07-15 08:02:34 +0000
commit39544c7383a2c619074565518f2445ff10b568c5 (patch)
tree963d017b31f962abb49c044f3bc343d70d976e71
parent72261f209f5a77179c6b50d52183136e8b267f2e (diff)
parente6aa6ec165b364dd7615ba912fb1e4aded5008bc (diff)
downloadgitlab-ce-39544c7383a2c619074565518f2445ff10b568c5.tar.gz
Merge branch 'pages-refactor-ssl-documentation' into 'master'
Docs: Pages - refactor "Custom domain / SSL" documentation Closes #47585, #60612, #44606, and #63753 See merge request gitlab-org/gitlab-ce!30363
-rw-r--r--app/views/admin/application_settings/_pages.html.haml2
-rw-r--r--app/views/notify/pages_domain_disabled_email.html.haml2
-rw-r--r--app/views/notify/pages_domain_disabled_email.text.haml2
-rw-r--r--app/views/notify/pages_domain_enabled_email.html.haml2
-rw-r--r--app/views/notify/pages_domain_enabled_email.text.haml2
-rw-r--r--app/views/notify/pages_domain_verification_failed_email.html.haml2
-rw-r--r--app/views/notify/pages_domain_verification_failed_email.text.haml2
-rw-r--r--app/views/notify/pages_domain_verification_succeeded_email.html.haml2
-rw-r--r--app/views/notify/pages_domain_verification_succeeded_email.text.haml2
-rw-r--r--app/views/projects/pages_domains/_helper_text.html.haml2
-rw-r--r--app/views/projects/pages_domains/show.html.haml2
-rw-r--r--doc/administration/pages/index.md2
-rw-r--r--doc/pages/getting_started_part_three.md4
-rw-r--r--doc/raketasks/backup_restore.md2
-rw-r--r--doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md95
-rw-r--r--doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png (renamed from doc/user/project/pages/img/add_certificate_to_pages.png)bin14608 -> 14608 bytes
-rw-r--r--doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_add_new_a_record_example_updated_2018.png (renamed from doc/user/project/pages/img/dns_add_new_a_record_example_updated_2018.png)bin3701 -> 3701 bytes
-rw-r--r--doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_cname_record_example.png (renamed from doc/user/project/pages/img/dns_cname_record_example.png)bin4983 -> 4983 bytes
-rw-r--r--doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.pngbin0 -> 194433 bytes
-rw-r--r--doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.pngbin0 -> 191712 bytes
-rw-r--r--doc/user/project/pages/custom_domains_ssl_tls_certification/index.md257
-rw-r--r--doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md75
-rw-r--r--doc/user/project/pages/getting_started_part_three.md315
-rw-r--r--doc/user/project/pages/getting_started_part_two.md4
-rw-r--r--doc/user/project/pages/img/pages_project_templates_v11_8.png (renamed from doc/user/project/pages/img/pages_project_templates_11-8.png)bin69702 -> 69702 bytes
-rw-r--r--doc/user/project/pages/img/verify_your_domain.pngbin12082 -> 0 bytes
-rw-r--r--doc/user/project/pages/index.md8
-rw-r--r--doc/user/project/pages/lets_encrypt_for_gitlab_pages.md4
-rw-r--r--spec/mailers/emails/pages_domains_spec.rb6
29 files changed, 456 insertions, 338 deletions
diff --git a/app/views/admin/application_settings/_pages.html.haml b/app/views/admin/application_settings/_pages.html.haml
index 5b8c1e4d54f..1282a032f52 100644
--- a/app/views/admin/application_settings/_pages.html.haml
+++ b/app/views/admin/application_settings/_pages.html.haml
@@ -14,7 +14,7 @@
= _("Require users to prove ownership of custom domains")
.form-text.text-muted
= _("Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled")
- = link_to icon('question-circle'), help_page_path('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record')
+ = link_to icon('question-circle'), help_page_path('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: '4-verify-the-domains-ownership')
%h5
= _("Configure Let's Encrypt")
%p
diff --git a/app/views/notify/pages_domain_disabled_email.html.haml b/app/views/notify/pages_domain_disabled_email.html.haml
index 224b79bfde8..44f85df97b9 100644
--- a/app/views/notify/pages_domain_disabled_email.html.haml
+++ b/app/views/notify/pages_domain_disabled_email.html.haml
@@ -8,6 +8,6 @@
Domain: #{link_to @domain.domain, project_pages_domain_url(@project, @domain)}
%p
If this domain has been disabled in error, please follow
- = link_to 'these instructions', help_page_url('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record')
+ = link_to 'these instructions', help_page_url('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: '4-verify-the-domains-ownership')
to verify and re-enable your domain.
= render 'removal_notification'
diff --git a/app/views/notify/pages_domain_disabled_email.text.haml b/app/views/notify/pages_domain_disabled_email.text.haml
index 4e81b054b1f..5a0fcab72d4 100644
--- a/app/views/notify/pages_domain_disabled_email.text.haml
+++ b/app/views/notify/pages_domain_disabled_email.text.haml
@@ -7,7 +7,7 @@ Domain: #{@domain.domain} (#{project_pages_domain_url(@project, @domain)})
If this domain has been disabled in error, please follow these instructions
to verify and re-enable your domain:
-= help_page_url('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record')
+= help_page_url('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: 'steps')
If you no longer wish to use this domain with GitLab Pages, please remove it
from your GitLab project and delete any related DNS records.
diff --git a/app/views/notify/pages_domain_enabled_email.html.haml b/app/views/notify/pages_domain_enabled_email.html.haml
index db09e503f65..103b17a87df 100644
--- a/app/views/notify/pages_domain_enabled_email.html.haml
+++ b/app/views/notify/pages_domain_enabled_email.html.haml
@@ -7,5 +7,5 @@
Domain: #{link_to @domain.domain, project_pages_domain_url(@project, @domain)}
%p
Please visit
- = link_to 'these instructions', help_page_url('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record')
+ = link_to 'these instructions', help_page_url('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: 'steps')
for more information about custom domain verification.
diff --git a/app/views/notify/pages_domain_enabled_email.text.haml b/app/views/notify/pages_domain_enabled_email.text.haml
index 1ed1dbb8315..bf8d2ac767a 100644
--- a/app/views/notify/pages_domain_enabled_email.text.haml
+++ b/app/views/notify/pages_domain_enabled_email.text.haml
@@ -5,5 +5,5 @@ Project: #{@project.human_name} (#{project_url(@project)})
Domain: #{@domain.domain} (#{project_pages_domain_url(@project, @domain)})
Please visit
-= help_page_url('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record')
+= help_page_url('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: 'steps')
for more information about custom domain verification.
diff --git a/app/views/notify/pages_domain_verification_failed_email.html.haml b/app/views/notify/pages_domain_verification_failed_email.html.haml
index 03b298f8e7c..a819b66f18e 100644
--- a/app/views/notify/pages_domain_verification_failed_email.html.haml
+++ b/app/views/notify/pages_domain_verification_failed_email.html.haml
@@ -10,6 +10,6 @@
Until then, you can view your content at #{link_to @domain.url, @domain.url}
%p
Please visit
- = link_to 'these instructions', help_page_url('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record')
+ = link_to 'these instructions', help_page_url('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: 'steps')
for more information about custom domain verification.
= render 'removal_notification'
diff --git a/app/views/notify/pages_domain_verification_failed_email.text.haml b/app/views/notify/pages_domain_verification_failed_email.text.haml
index c14e0e0c24d..85aa2d7a503 100644
--- a/app/views/notify/pages_domain_verification_failed_email.text.haml
+++ b/app/views/notify/pages_domain_verification_failed_email.text.haml
@@ -7,7 +7,7 @@ Unless you take action, it will be disabled on *#{@domain.enabled_until.strftime
Until then, you can view your content at #{@domain.url}
Please visit
-= help_page_url('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record')
+= help_page_url('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: 'steps')
for more information about custom domain verification.
If you no longer wish to use this domain with GitLab Pages, please remove it
diff --git a/app/views/notify/pages_domain_verification_succeeded_email.html.haml b/app/views/notify/pages_domain_verification_succeeded_email.html.haml
index 2ead3187b10..808b12948f9 100644
--- a/app/views/notify/pages_domain_verification_succeeded_email.html.haml
+++ b/app/views/notify/pages_domain_verification_succeeded_email.html.haml
@@ -9,5 +9,5 @@
content at #{link_to @domain.url, @domain.url}
%p
Please visit
- = link_to 'these instructions', help_page_url('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record')
+ = link_to 'these instructions', help_page_url('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: 'steps')
for more information about custom domain verification.
diff --git a/app/views/notify/pages_domain_verification_succeeded_email.text.haml b/app/views/notify/pages_domain_verification_succeeded_email.text.haml
index e7cdbdee420..8d0694ef613 100644
--- a/app/views/notify/pages_domain_verification_succeeded_email.text.haml
+++ b/app/views/notify/pages_domain_verification_succeeded_email.text.haml
@@ -6,5 +6,5 @@ Domain: #{@domain.domain} (#{project_pages_domain_url(@project, @domain)})
No action is required on your part. You can view your content at #{@domain.url}
Please visit
-= help_page_url('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record')
+= help_page_url('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: 'steps')
for more information about custom domain verification.
diff --git a/app/views/projects/pages_domains/_helper_text.html.haml b/app/views/projects/pages_domains/_helper_text.html.haml
index 4e3daa597e0..f29cb0609e6 100644
--- a/app/views/projects/pages_domains/_helper_text.html.haml
+++ b/app/views/projects/pages_domains/_helper_text.html.haml
@@ -1,4 +1,4 @@
-- docs_link_url = help_page_path("user/project/pages/getting_started_part_three.md", anchor: "adding-certificates-to-your-project")
+- docs_link_url = help_page_path("user/project/pages/custom_domains_ssl_tls_certification/index.md", anchor: "adding-an-ssltls-certificate-to-pages")
- 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
diff --git a/app/views/projects/pages_domains/show.html.haml b/app/views/projects/pages_domains/show.html.haml
index 82147568981..e9019175219 100644
--- a/app/views/projects/pages_domains/show.html.haml
+++ b/app/views/projects/pages_domains/show.html.haml
@@ -53,7 +53,7 @@
.input-group-append
= clipboard_button(target: '#domain_verification', class: 'btn-default d-none d-sm-block')
%p.form-text.text-muted
- - link_to_help = link_to(_('verify ownership'), help_page_path('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record'))
+ - link_to_help = link_to(_('verify ownership'), help_page_path('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: '4-verify-the-domains-ownership'))
= _("To %{link_to_help} of your domain, add the above key to a TXT record within to your DNS configuration.").html_safe % { link_to_help: link_to_help }
%tr
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md
index b5b8f124274..3cabe8eb16e 100644
--- a/doc/administration/pages/index.md
+++ b/doc/administration/pages/index.md
@@ -256,7 +256,7 @@ world. Custom domains and TLS are supported.
### Custom domain verification
To prevent malicious users from hijacking domains that don't belong to them,
-GitLab supports [custom domain verification](../../user/project/pages/getting_started_part_three.md#dns-txt-record).
+GitLab supports [custom domain verification](../../user/project/pages/custom_domains_ssl_tls_certification/index.md#steps).
When adding a custom domain, users will be required to prove they own it by
adding a GitLab-controlled verification code to the DNS records for that domain.
diff --git a/doc/pages/getting_started_part_three.md b/doc/pages/getting_started_part_three.md
index b65247ff7b7..31a01a6c83b 100644
--- a/doc/pages/getting_started_part_three.md
+++ b/doc/pages/getting_started_part_three.md
@@ -1,5 +1,5 @@
---
-redirect_to: '../user/project/pages/getting_started_part_three.md'
+redirect_to: '../user/project/pages/custom_domains_ssl_tls_certification/index.md'
---
-This document was moved to [another location](../user/project/pages/getting_started_part_three.md).
+This document was moved to [another location](../user/project/pages/custom_domains_ssl_tls_certification/index.md).
diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md
index e02e2c1057e..0d86df04367 100644
--- a/doc/raketasks/backup_restore.md
+++ b/doc/raketasks/backup_restore.md
@@ -834,7 +834,7 @@ including (but not restricted to):
- [CI/CD variables](../ci/variables/README.md)
- [Kubernetes / GCP integration](../user/project/clusters/index.md)
-- [Custom Pages domains](../user/project/pages/getting_started_part_three.md)
+- [Custom Pages domains](../user/project/pages/custom_domains_ssl_tls_certification/index.md)
- [Project error tracking](../user/project/operations/error_tracking.md)
- [Runner authentication](../ci/runners/README.md)
- [Project mirroring](../workflow/repository_mirroring.md)
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md
new file mode 100644
index 00000000000..3b80370d4a9
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md
@@ -0,0 +1,95 @@
+---
+type: concepts
+---
+
+# DNS records overview
+
+_Read this document for a brief overview of DNS records in the scope
+of GitLab Pages, for beginners in web development._
+
+A Domain Name System (DNS) web service routes visitors to websites
+by translating domain names (such as `www.example.com`) into the
+numeric IP addresses (such as `192.0.2.1`) that computers use to
+connect to each other.
+
+A DNS record is created to point a (sub)domain to a certain location,
+which can be an IP address or another domain. In case you want to use
+GitLab Pages with your own (sub)domain, you need to access your domain's
+registrar control panel to add a DNS record pointing it back to your
+GitLab Pages site.
+
+Note that **how to** add DNS records depends on which server your domain
+is hosted on. Every control panel has its own place to do it. If you are
+not an admin of your domain, and don't have access to your registrar,
+you'll need to ask for the technical support of your hosting service
+to do it for you.
+
+To help you out, we've gathered some instructions on how to do that
+for the most popular hosting services:
+
+- [Amazon](http://docs.aws.amazon.com/gettingstarted/latest/swh/getting-started-configure-route53.html)
+- [Bluehost](https://my.bluehost.com/cgi/help/559)
+- [CloudFlare](https://support.cloudflare.com/hc/en-us/articles/200169096-How-do-I-add-A-records-)
+- [cPanel](https://documentation.cpanel.net/display/ALD/Edit+DNS+Zone)
+- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-)
+- [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238)
+- [Hostgator](http://support.hostgator.com/articles/changing-dns-records)
+- [Inmotion hosting](https://my.bluehost.com/cgi/help/559)
+- [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain)
+- [Microsoft](https://msdn.microsoft.com/en-us/library/bb727018.aspx)
+
+If your hosting service is not listed above, you can just try to
+search the web for `how to add dns record on <my hosting service>`.
+
+## `A` record
+
+A DNS A record maps a host to an IPv4 IP address.
+It points a root domain as `example.com` to the host's IP address as
+`192.192.192.192`.
+
+Example:
+
+- `example.com` => `A` => `192.192.192.192`
+
+## CNAME record
+
+CNAME records define an alias for canonical name for your server (one defined
+by an A record). It points a subdomain to another domain.
+
+Example:
+
+- `www` => `CNAME` => `example.com`
+
+This way, visitors visiting `www.example.com` will be redirected to
+`example.com`.
+
+## MX record
+
+MX records are used to define the mail exchanges that are used for the domain.
+This helps email messages arrive at your mail server correctly.
+
+Example:
+
+- `MX` => `mail.example.com`
+
+Then you can register emails for `users@mail.example.com`.
+
+## TXT record
+
+A `TXT` record can associate arbitrary text with a host or other name. A common
+use is for site verification.
+
+Example:
+
+- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"`
+
+This way, you can verify the ownership for that domain name.
+
+## All combined
+
+You can have one DNS record or more than one combined:
+
+- `example.com` => `A` => `192.192.192.192`
+- `www` => `CNAME` => `example.com`
+- `MX` => `mail.example.com`
+- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"` \ No newline at end of file
diff --git a/doc/user/project/pages/img/add_certificate_to_pages.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png
index d92a981dc60..d92a981dc60 100644
--- a/doc/user/project/pages/img/add_certificate_to_pages.png
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png
Binary files differ
diff --git a/doc/user/project/pages/img/dns_add_new_a_record_example_updated_2018.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_add_new_a_record_example_updated_2018.png
index 0150329d4b2..0150329d4b2 100644
--- a/doc/user/project/pages/img/dns_add_new_a_record_example_updated_2018.png
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_add_new_a_record_example_updated_2018.png
Binary files differ
diff --git a/doc/user/project/pages/img/dns_cname_record_example.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_cname_record_example.png
index 43d1a838544..43d1a838544 100644
--- a/doc/user/project/pages/img/dns_cname_record_example.png
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_cname_record_example.png
Binary files differ
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png
new file mode 100644
index 00000000000..b4dcdc9bb60
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png
Binary files differ
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png
new file mode 100644
index 00000000000..db8f25bc6c3
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png
Binary files differ
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md
new file mode 100644
index 00000000000..6c0d3e9e9d3
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md
@@ -0,0 +1,257 @@
+---
+last_updated: 2019-07-04
+type: reference, howto
+redirect_from: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html'
+---
+
+# Custom domains and SSL/TLS Certificates
+
+Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages.
+
+To use one or more custom domain names with your Pages site, you can:
+
+- Add a [custom **root domain** or a **subdomain**](#set-up-pages-with-a-custom-domain).
+- Add [SSL/TLS certification](#adding-an-ssltls-certificate-to-pages).
+
+## Set up Pages with a custom domain
+
+To set up Pages with a custom domain name, read the requirements
+and steps below.
+
+### Requirements
+
+- A GitLab Pages website up and running, served under the default Pages domain
+ (`*.gitlab.io`, for GitLab.com).
+- A custom domain name `example.com` or subdomain `subdomain.example.com`.
+- Access to your domain's server control panel to set up DNS records:
+ - A DNS A or CNAME record poiting your domain to GitLab Pages server.
+ - A DNS TXT record to verify your domain's ownership.
+
+### Steps
+
+Follow the steps below to add your custom domain to Pages. See also
+this document for an [overview on DNS records](dns_concepts.md).
+
+#### 1. Add a custom domain to Pages
+
+Navigate to your project's **Setting > Pages** and click **+ New domain**
+to add your custom domain to GitLab Pages. You can choose whether to:
+
+- Add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages).
+- Leave it blank (it can be added later).
+
+Click **Create New Domain**.
+
+![Add new domain](img/add_certificate_to_pages.png)
+
+#### 2. Get the verification code
+
+Once you have added a new domain to Pages, the verification code will be prompted to you. Copy the values from GitLab and paste them in your domain's control panel as a TXT record on the next step.
+
+![Get the verification code](img/get_domain_verification_code_v12_0.png)
+
+#### 3. Set up DNS records for Pages
+
+Read this document for an [overview of DNS records for Pages](dns_concepts.md).
+If you're familiar with the subject, follow the instructions below
+according to the type of domain you want to use with your Pages site:
+
+- [For root domains](#for-root-domains), `example.com`.
+- [For subdomains](#for-subdomains), `subdomain.example.com`.
+- [For both](#for-both-root-and-subdomains).
+
+##### For root domains
+
+Root domains (`example.com`) require:
+
+- A [DNS A record](dns_concepts.md#a-record) pointing your domain to the Pages server.
+- A [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership.
+
+| From | DNS Record | To |
+| ---- | ---------- | -- |
+| example.com | A | 35.185.44.232 |
+| _gitlab-pages-verification-code.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
+
+For projects on GitLab.com, this IP is `35.185.44.232`.
+For projects living in other GitLab instances (CE or EE), please contact
+your sysadmin asking for this information (which IP address is Pages
+server running on your instance).
+
+![DNS A record pointing to GitLab.com Pages server](img/dns_add_new_a_record_example_updated_2018.png)
+
+CAUTION: **Caution:**
+Note that if you use your root domain for your GitLab Pages website
+**only**, and if your domain registrar supports this feature, you can
+add a DNS apex `CNAME` record instead of an `A` record. The main
+advantage of doing so is that when GitLab Pages IP on GitLab.com
+changes for whatever reason, you don't need to update your `A` record.
+There may be a few exceptions, but **this method is not recommended**
+as it most likely won't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain.
+
+##### For subdomains
+
+Subdomains (`subdomain.example.com`) require:
+
+- A DNS [CNAME record](dns_concepts.md#cname-record) record pointing your subdomain to the Pages server.
+- A DNS [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership.
+
+| From | DNS Record | To |
+| ---- | ---------- | -- |
+| subdomain.example.com | CNAME | namespace.gitlab.io |
+| _gitlab-pages-verification-code.subdomain.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
+
+Note that, whether it's a user or a project website, the `CNAME`
+should point to your Pages domain (`namespace.gitlab.io`),
+without any `/project-name`.
+
+![DNS CNAME record pointing to GitLab.com project](img/dns_cname_record_example.png)
+
+##### For both root and subdomains
+
+There are a few cases where you need point both subdomain and root
+domain to the same website, for instance, `example.com` and `www.example.com`.
+
+They require:
+
+- A DNS A record for the domain.
+- A DNS CNAME record for the subdomain.
+- A DNS TXT record for each.
+
+| From | DNS Record | To |
+| ---- | ---------- | -- |
+| example.com | A | 35.185.44.232 |
+| _gitlab-pages-verification-code.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
+|---+---|
+| www.example.com | CNAME | namespace.gitlab.io |
+| _gitlab-pages-verification-code.www.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
+
+If you're using CloudFlare, check
+[Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirecting-wwwdomaincom-to-domaincom-with-cloudflare).
+
+> **Notes**:
+>
+> - **Do not** use a CNAME record if you want to point your
+ `domain.com` to your GitLab Pages site. Use an `A` record instead.
+> - **Do not** add any special chars after the default Pages
+ domain. E.g., don't point `subdomain.domain.com` to
+ or `namespace.gitlab.io/`. Some domain hosting providers may request a trailling dot (`namespace.gitlab.io.`), though.
+> - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017.
+> - GitLab Pages IP on GitLab.com [has changed](https://about.gitlab.com/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains)
+ from `52.167.214.135` to `35.185.44.232` in 2018.
+
+#### 4. Verify the domain's ownership
+
+Once you have added all the DNS records:
+
+1. Go back at your project's **Settings > Pages**.
+1. Locate your domain name and click **Details**.
+1. Click the **Retry verification** button to activate your new domain.
+
+![Verify your domain](img/retry_domain_verification_v12_0.png)
+
+As soon as your domain becomes active, your website will be available
+through your domain name.
+
+CAUTION: **Caution:**
+Considering GitLab instances with domain verification enabled,
+if the domain cannot be verified for 7 days, it will be removed
+from the GitLab project.
+
+> **Notes:**
+>
+> - Domain verification is **required for GitLab.com users**;
+ for GitLab self-managed instances, your GitLab administrator has the option
+ to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification).
+> - [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes),
+ although it's usually a matter of minutes to complete. Until it does, verification
+ will fail and attempts to visit your domain will respond with a 404.
+> - Once your domain has been verified, leave the verification record
+ in place: your domain will be periodically reverified, and may be
+ disabled if the record is removed.
+
+### Adding more domain aliases
+
+You can add more than one alias (custom domains and subdomains) to the same project.
+An alias can be understood as having many doors leading to the same room.
+
+All the aliases you've set to your site will be listed on **Setting > Pages**.
+From that page, you can view, add, and remove them.
+
+### Redirecting `www.domain.com` to `domain.com` with Cloudflare
+
+If you use Cloudflare, you can redirect `www` to `domain.com` without adding both
+`www.domain.com` and `domain.com` to GitLab. This happens due to a [Cloudflare feature that creates
+a 301 redirect as a "page rule"](https://gitlab.com/gitlab-org/gitlab-ce/issues/48848#note_87314849) for redirecting `www.domain.com` to `domain.com`. In this case,
+you can use the following setup:
+
+1. In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232`.
+1. In GitLab, add the domain to GitLab Pages.
+1. In Cloudflare, create a DNS `TXT` record to verify your domain.
+1. In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com`.
+
+## Adding an SSL/TLS certificate to Pages
+
+Read this document for an [overview on SSL/TLS certification](ssl_tls_concepts.md).
+
+### Requirements
+
+- A GitLab Pages website up and running accessible via a custom domain.
+- **A PEM certificate**: it is the certificate generated by the CA,
+ which needs to be added to the field **Certificate (PEM)**.
+- **An [intermediate certificate](https://en.wikipedia.org/wiki/Intermediate_certificate_authority)**: (aka "root certificate"), it is
+ the part of the encryption keychain that identifies the CA.
+ Usually it's combined with the PEM certificate, but there are
+ some cases in which you need to add them manually.
+ [CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/)
+ are one of these cases.
+- **A private key**, it's an encrypted key which validates
+ your PEM against your domain.
+
+### Steps
+
+- To add the certificate at the time you add a new domain, go to your
+ project's **Settings > Pages > New Domain**, add the domain name and the certificate.
+- To add the certificate to a domain previously added, go to your
+ project's **Settings > Pages**, locate your domain name, click **Details** and **Edit** to add the certificate.
+
+![Pages project - adding certificates](img/add_certificate_to_pages.png)
+
+1. Add the PEM certificate to its corresponding field.
+1. If your certificate is missing its intermediate, copy
+ and paste the root certificate (usually available from your CA website)
+ and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/),
+ just jumping a line between them.
+1. Copy your private key and paste it in the last field.
+
+NOTE: **Note:**
+**Do not** open certificates or encryption keys in
+regular text editors. Always use code editors (such as
+Sublime Text, Atom, Dreamweaver, Brackets, etc).
+
+## Force HTTPS for GitLab Pages websites
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28857) in GitLab 10.7.
+
+To make your website's visitors even more secure, you can choose to
+force HTTPS for GitLab Pages. By doing so, all attempts to visit your
+website via HTTP will be automatically redirected to HTTPS via 301.
+
+It works with both GitLab's default domain and with your custom
+domain (as long as you've set a valid certificate for it).
+
+To enable this setting:
+
+1. Navigate to your project's **Settings > Pages**.
+1. Tick the checkbox **Force HTTPS (requires valid certificates)**.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. --> \ No newline at end of file
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md
new file mode 100644
index 00000000000..2470e78819f
--- /dev/null
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md
@@ -0,0 +1,75 @@
+---
+type: concepts
+---
+
+# SSL/TLS Certificates
+
+_Read this document for a brief overview of SSL/TLS certificates in
+the scope of GitLab Pages, for beginners in web development._
+
+Every GitLab Pages project on GitLab.com will be available under
+HTTPS for the default Pages domain (`*.gitlab.io`). Once you set
+up your Pages project with your custom (sub)domain, if you want
+it secured by HTTPS, you will have to issue a certificate for that
+(sub)domain and install it on your project.
+
+NOTE: **Note:**
+Certificates are NOT required to add to your custom
+(sub)domain on your GitLab Pages project, though they are
+highly recommendable.
+
+Let's start with an introduction to the importance of HTTPS.
+
+## Why should I care about HTTPS?
+
+This might be your first question. If our sites are hosted by GitLab Pages,
+they are static, hence we are not dealing with server-side scripts
+nor credit card transactions, then why do we need secure connections?
+
+Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special"
+security measure, necessary just for big companies, like banks and shoppings sites
+with financial transactions.
+Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group):
+
+> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._
+
+Therefore, the reason why certificates are so important is that they encrypt
+the connection between the **client** (you, me, your visitors)
+and the **server** (where you site lives), through a keychain of
+authentications and validations.
+
+How about taking Josh's advice and protecting our sites too? We will be
+well supported, and we'll contribute to a safer internet.
+
+## Organizations supporting HTTPS
+
+There is a huge movement in favor of securing all the web. W3C fully
+[supports the cause](https://w3ctag.github.io/web-https/) and explains very well
+the reasons for that. Richard Barnes, a writer for Mozilla Security Blog,
+suggested that [Firefox would deprecate HTTP](https://blog.mozilla.org/security/2015/04/30/deprecating-non-secure-http/),
+and would no longer accept unsecured connections. Recently, Mozilla published a
+[communication](https://blog.mozilla.org/security/2016/03/29/march-2016-ca-communication/)
+reiterating the importance of HTTPS.
+
+## Issuing Certificates
+
+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 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).
+
+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. 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/).
diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md
index bc9a11504cd..9bc9fe97fd3 100644
--- a/doc/user/project/pages/getting_started_part_three.md
+++ b/doc/user/project/pages/getting_started_part_three.md
@@ -1,314 +1 @@
----
-last_updated: 2019-06-25
-type: concepts, reference, howto
----
-
-# GitLab Pages custom domains and SSL/TLS Certificates
-
-Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages.
-
-These steps assume you've already [set your site up](getting_started_part_two.md) and it's served under the default Pages domain `namespace.gitlab.io`, or `namespace.gitlab.io/project-name`.
-
-## Adding your custom domain to GitLab Pages
-
-To use one or more custom domain with your Pages site, there are two things
-you should consider first, which we'll cover in this guide:
-
-1. Either if you're adding a **root domain** or a **subdomain**, for which
- you'll need to set up [DNS records](#dns-records)
-1. Whether you want to add an [SSL/TLS certificate](#ssltls-certificates) or not
-
-To finish the association, you need to [add your domain to your project's Pages settings](#add-your-custom-domain-to-gitlab-pages-settings).
-
-Let's start from the beginning with [DNS records](#dns-records).
-If you already know how they work and want to skip the introduction to DNS,
-you may be interested in skipping it until the [TL;DR](#tldr) section below.
-
-### DNS Records
-
-A Domain Name System (DNS) web service routes visitors to websites
-by translating domain names (such as `www.example.com`) into the
-numeric IP addresses (such as `192.0.2.1`) that computers use to
-connect to each other.
-
-A DNS record is created to point a (sub)domain to a certain location,
-which can be an IP address or another domain. In case you want to use
-GitLab Pages with your own (sub)domain, you need to access your domain's
-registrar control panel to add a DNS record pointing it back to your
-GitLab Pages site.
-
-Note that **how to** add DNS records depends on which server your domain
-is hosted on. Every control panel has its own place to do it. If you are
-not an admin of your domain, and don't have access to your registrar,
-you'll need to ask for the technical support of your hosting service
-to do it for you.
-
-To help you out, we've gathered some instructions on how to do that
-for the most popular hosting services:
-
-- [Amazon](http://docs.aws.amazon.com/gettingstarted/latest/swh/getting-started-configure-route53.html)
-- [Bluehost](https://my.bluehost.com/cgi/help/559)
-- [CloudFlare](https://support.cloudflare.com/hc/en-us/articles/200169096-How-do-I-add-A-records-)
-- [cPanel](https://documentation.cpanel.net/display/ALD/Edit+DNS+Zone)
-- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-)
-- [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238)
-- [Hostgator](http://support.hostgator.com/articles/changing-dns-records)
-- [Inmotion hosting](https://my.bluehost.com/cgi/help/559)
-- [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain)
-- [Microsoft](https://msdn.microsoft.com/en-us/library/bb727018.aspx)
-
-If your hosting service is not listed above, you can just try to
-search the web for `how to add dns record on <my hosting service>`.
-
-#### DNS A record
-
-In case you want to point a root domain (`example.com`) to your
-GitLab Pages site, deployed to `namespace.gitlab.io`, you need to
-log into your domain's admin control panel and add a DNS `A` record
-pointing your domain to Pages' server IP address. For projects on
-GitLab.com, this IP is `35.185.44.232`. For projects living in
-other GitLab instances (CE or EE), please contact your sysadmin
-asking for this information (which IP address is Pages server
-running on your instance).
-
-**Practical Example:**
-
-![DNS A record pointing to GitLab.com Pages server](img/dns_add_new_a_record_example_updated_2018.png)
-
-CAUTION: **Caution:**
-Note that if you use your root domain for your GitLab Pages website
-**only**, and if your domain registrar supports this feature, you can
-add a DNS apex `CNAME` record instead of an `A` record. The main
-advantage of doing so is that when GitLab Pages IP on GitLab.com
-changes for whatever reason, you don't need to update your `A` record.
-There may be a few exceptions, but **this method is not recommended**
-as it most likely won't work if you set an `MX` record for your root domain.
-
-#### DNS CNAME record
-
-In case you want to point a subdomain (`hello-world.example.com`)
-to your GitLab Pages site initially deployed to `namespace.gitlab.io`,
-you need to log into your domain's admin control panel and add a DNS
-`CNAME` record pointing your subdomain to your website URL
-(`namespace.gitlab.io`) address.
-
-Note that, whether it's a user or a project website, the `CNAME`
-should point to your Pages domain (`namespace.gitlab.io`),
-without any `/project-name`.
-
-**Practical Example:**
-
-![DNS CNAME record pointing to GitLab.com project](img/dns_cname_record_example.png)
-
-#### DNS TXT record
-
-Unless your GitLab administrator has [disabled custom domain verification](../../../administration/pages/index.md#custom-domain-verification),
-you'll have to prove that you own the domain by creating a `TXT` record
-containing a verification code. The code will be displayed after you
-[add your custom domain to GitLab Pages settings](#add-your-custom-domain-to-gitlab-pages-settings).
-
-If using a [DNS A record](#dns-a-record), you can place the TXT record directly
-under the domain. If using a [DNS CNAME record](#dns-cname-record), the two record types won't
-co-exist, so you need to place the TXT record in a special subdomain of its own.
-
-If the domain cannot be verified for 7 days, it will be removed from the GitLab project.
-
-#### TL;DR
-
-For root domains (`domain.com`), set a DNS `A` record and verify your
-domain's ownership with a TXT record:
-
-| From | DNS Record | To |
-| ---- | ---------- | -- |
-| domain.com | A | 35.185.44.232 |
-| domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
-
-For subdomains (`subdomain.domain.com`), set a DNS `CNAME` record and
-verify your domain's ownership with a TXT record:
-
-| From | DNS Record | To |
-| ---- | ---------- | -- |
-| subdomain.domain.com | CNAME | namespace.gitlab.io |
-| _gitlab-pages-verification-code.subdomain.domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff |
-
-> **Notes**:
->
-> - **Do not** use a CNAME record if you want to point your
- `domain.com` to your GitLab Pages site. Use an `A` record instead.
-> - **Do not** add any special chars after the default Pages
- domain. E.g., **do not** point your `subdomain.domain.com` to
- `namespace.gitlab.io.` or `namespace.gitlab.io/`.
-> - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017.
-> - GitLab Pages IP on GitLab.com [has been changed](https://about.gitlab.com/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains)
- from `52.167.214.135` to `35.185.44.232` in 2018.
-
-### Add your custom domain to GitLab Pages settings
-
-Once you've set the DNS record, you'll need navigate to your project's
-**Setting > Pages** and click **+ New domain** to add your custom domain to
-GitLab Pages. You can choose whether to add an [SSL/TLS certificate](#ssltls-certificates)
-to make your website accessible under HTTPS or leave it blank. If you don't add a certificate,
-your site will be accessible only via HTTP:
-
-![Add new domain](img/add_certificate_to_pages.png)
-
-Once you have added a new domain, you will need to **verify your ownership**
-(unless the GitLab administrator has disabled this feature). A verification code
-will be shown to you; add it as a [DNS TXT record](#dns-txt-record), then press
-the "Verify ownership" button to activate your new domain:
-
-![Verify your domain](img/verify_your_domain.png)
-
-Once your domain has been verified, leave the verification record in place -
-your domain will be periodically reverified, and may be disabled if the record
-is removed.
-
-You can add more than one alias (custom domains and subdomains) to the same project.
-An alias can be understood as having many doors leading to the same room.
-
-All the aliases you've set to your site will be listed on **Setting > Pages**.
-From that page, you can view, add, and remove them.
-
-Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes),
-although it's usually a matter of minutes to complete. Until it does, verification
-will fail and attempts to visit your domain will respond with a 404.
-
-### Redirecting `www.domain.com` to `domain.com` with Cloudflare
-
-If you use Cloudflare, you can redirect `www` to `domain.com` without the need of adding both
-`www.domain.com` and `domain.com` to GitLab. This happens due to a [Cloudflare feature that creates
-a 301 redirect as a "page rule"](https://gitlab.com/gitlab-org/gitlab-ce/issues/48848#note_87314849) for redirecting `www.domain.com` to `domain.com`. In this case,
-you can use the following setup:
-
-- In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232`
-- In GitLab, add the domain to GitLab Pages
-- In Cloudflare, create a DNS `TXT` record to verify your domain
-- In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com`
-
-## SSL/TLS Certificates
-
-Every GitLab Pages project on GitLab.com will be available under
-HTTPS for the default Pages domain (`*.gitlab.io`). Once you set
-up your Pages project with your custom (sub)domain, if you want
-it secured by HTTPS, you will have to issue a certificate for that
-(sub)domain and install it on your project.
-
->**Note:**
-Certificates are NOT required to add to your custom
-(sub)domain on your GitLab Pages project, though they are
-highly recommendable.
-
-Let's start with an introduction to the importance of HTTPS.
-Alternatively, jump ahead to [adding certificates to your project](#adding-certificates-to-pages).
-
-### Why should I care about HTTPS?
-
-This might be your first question. If our sites are hosted by GitLab Pages,
-they are static, hence we are not dealing with server-side scripts
-nor credit card transactions, then why do we need secure connections?
-
-Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special"
-security measure, necessary just for big companies, like banks and shoppings sites
-with financial transactions.
-Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group):
-
-> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._
-
-Therefore, the reason why certificates are so important is that they encrypt
-the connection between the **client** (you, me, your visitors)
-and the **server** (where you site lives), through a keychain of
-authentications and validations.
-
-How about taking Josh's advice and protecting our sites too? We will be
-well supported, and we'll contribute to a safer internet.
-
-### Organizations supporting HTTPS
-
-There is a huge movement in favor of securing all the web. W3C fully
-[supports the cause](https://w3ctag.github.io/web-https/) and explains very well
-the reasons for that. Richard Barnes, a writer for Mozilla Security Blog,
-suggested that [Firefox would deprecate HTTP](https://blog.mozilla.org/security/2015/04/30/deprecating-non-secure-http/),
-and would no longer accept unsecured connections. Recently, Mozilla published a
-[communication](https://blog.mozilla.org/security/2016/03/29/march-2016-ca-communication/)
-reiterating the importance of HTTPS.
-
-## Issuing Certificates
-
-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 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).
-
-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. 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 Pages
-
-Regardless the CA you choose, the steps to add your certificate to
-your Pages project are the same.
-
-#### Requirements
-
-1. A PEM certificate
-1. An intermediate certificate
-1. A private key
-
-![Pages project - adding certificates](img/add_certificate_to_pages.png)
-
-These fields are found under your **Project**'s **Settings** > **Pages** > **New Domain**.
-
-#### Certificate types
-
-- A PEM certificate is the certificate generated by the CA,
- which needs to be added to the field **Certificate (PEM)**.
-- An [intermediate certificate](https://en.wikipedia.org/wiki/Intermediate_certificate_authority) (aka "root certificate") is
- the part of the encryption keychain that identifies the CA.
- Usually it's combined with the PEM certificate, but there are
- some cases in which you need to add them manually.
- [CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/)
- are one of these cases.
-- A private key is an encrypted key which validates
- your PEM against your domain.
-
-#### Add the certificate to your project
-
-Once you've met the requirements:
-
-- Your PEM certificate needs to be added to the first field.
-- If your certificate is missing its intermediate, copy
- and paste the root certificate (usually available from your CA website)
- and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/),
- just jumping a line between them.
-- Copy your private key and paste it in the last field.
-
-NOTE: **Note:**
-**Do not** open certificates or encryption keys in
-regular text editors. Always use code editors (such as
-Sublime Text, Atom, Dreamweaver, Brackets, etc).
-
-## Force HTTPS for GitLab Pages websites
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28857) in GitLab 10.7.
-
-To make your website's visitors even more secure, you can choose to
-force HTTPS for GitLab Pages. By doing so, all attempts to visit your
-website via HTTP will be automatically redirected to HTTPS via 301.
-
-It works with both GitLab's default domain and with your custom
-domain (as long as you've set a valid certificate for it).
-
-To enable this setting, navigate to your project's **Settings > Pages**
-and tick the checkbox **Force HTTPS (requires valid certificates)**.
+This document was moved to [another location](custom_domains_ssl_tls_certification/index.md).
diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md
index fe92d19567d..743c360f075 100644
--- a/doc/user/project/pages/getting_started_part_two.md
+++ b/doc/user/project/pages/getting_started_part_two.md
@@ -22,7 +22,7 @@ Optional Features:
1. **Optional**: an SSL/TLS certificate so your custom
domain is accessible under HTTPS.
-The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [Part 3](getting_started_part_three.md)).
+The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md)).
## Project
@@ -169,4 +169,4 @@ baseurl: ""
## Custom Domains
GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS.
-See [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md) for more information.
+See [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) for more information.
diff --git a/doc/user/project/pages/img/pages_project_templates_11-8.png b/doc/user/project/pages/img/pages_project_templates_v11_8.png
index a645d28260b..a645d28260b 100644
--- a/doc/user/project/pages/img/pages_project_templates_11-8.png
+++ b/doc/user/project/pages/img/pages_project_templates_v11_8.png
Binary files differ
diff --git a/doc/user/project/pages/img/verify_your_domain.png b/doc/user/project/pages/img/verify_your_domain.png
deleted file mode 100644
index d870f9e6505..00000000000
--- a/doc/user/project/pages/img/verify_your_domain.png
+++ /dev/null
Binary files differ
diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md
index 64b1e259292..e9d2e9a0059 100644
--- a/doc/user/project/pages/index.md
+++ b/doc/user/project/pages/index.md
@@ -101,7 +101,7 @@ To get started with GitLab Pages, you can either:
1. Select **Create from Template**.
1. Choose one of the templates starting with **Pages**:
- ![Project templates for Pages](img/pages_project_templates_11-8.png)
+ ![Project templates for Pages](img/pages_project_templates_v11_8.png)
1. From the left sidebar, navigate to your project's **CI/CD > Pipelines**
and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your
@@ -115,8 +115,8 @@ will run a new pipeline to publish your changes to the server.
_Advanced options:_
-- [Use a custom domain](getting_started_part_three.md#adding-your-custom-domain-to-gitlab-pages)
-- Apply [SSL/TLS certification](getting_started_part_three.md#ssltls-certificates) to your custom domain
+- [Use a custom domain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain)
+- Apply [SSL/TLS certification](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages) to your custom domain
## Availability
@@ -142,7 +142,7 @@ To learn more about configuration options for GitLab Pages, read the following:
| [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Understand how to create your own `.gitlab-ci.yml` for your site. |
| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, Access Control, custom 404 pages, limitations, FAQ. |
|---+---|
-| [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. |
+| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.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. |
|---+---|
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 a5f671a0ebb..cc129f90b7a 100644
--- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md
+++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md
@@ -18,9 +18,9 @@ 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)
+- Acquired a domain (`example.com`) and added a [DNS entry](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain)
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)
+- [Added your domain to your Pages project](custom_domains_ssl_tls_certification/index.md#steps)
and verified your ownership.
- Cloned your project into your computer.
- Your website up and running, served under HTTP protocol at `http://example.com`.
diff --git a/spec/mailers/emails/pages_domains_spec.rb b/spec/mailers/emails/pages_domains_spec.rb
index eae83cd64d3..c52e3c2191d 100644
--- a/spec/mailers/emails/pages_domains_spec.rb
+++ b/spec/mailers/emails/pages_domains_spec.rb
@@ -23,7 +23,7 @@ describe Emails::PagesDomains do
is_expected.to have_body_text(domain.domain)
is_expected.to have_body_text domain.url
is_expected.to have_body_text project_pages_domain_url(project, domain)
- is_expected.to have_body_text help_page_url('user/project/pages/getting_started_part_three.md', anchor: 'dns-txt-record')
+ is_expected.to have_body_text help_page_url('user/project/pages/custom_domains_ssl_tls_certification/index.md', anchor: link_anchor)
end
end
end
@@ -50,6 +50,7 @@ describe Emails::PagesDomains do
describe '#pages_domain_enabled_email' do
let(:email_subject) { "#{project.path} | GitLab Pages domain '#{domain.domain}' has been enabled" }
+ let(:link_anchor) { 'steps' }
subject { Notify.pages_domain_enabled_email(domain, user) }
@@ -60,6 +61,7 @@ describe Emails::PagesDomains do
describe '#pages_domain_disabled_email' do
let(:email_subject) { "#{project.path} | GitLab Pages domain '#{domain.domain}' has been disabled" }
+ let(:link_anchor) { '4-verify-the-domains-ownership' }
subject { Notify.pages_domain_disabled_email(domain, user) }
@@ -72,6 +74,7 @@ describe Emails::PagesDomains do
describe '#pages_domain_verification_succeeded_email' do
let(:email_subject) { "#{project.path} | Verification succeeded for GitLab Pages domain '#{domain.domain}'" }
+ let(:link_anchor) { 'steps' }
subject { Notify.pages_domain_verification_succeeded_email(domain, user) }
@@ -82,6 +85,7 @@ describe Emails::PagesDomains do
describe '#pages_domain_verification_failed_email' do
let(:email_subject) { "#{project.path} | ACTION REQUIRED: Verification failed for GitLab Pages domain '#{domain.domain}'" }
+ let(:link_anchor) { 'steps' }
subject { Notify.pages_domain_verification_failed_email(domain, user) }