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

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

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'

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.

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.

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.

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'

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

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.

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.

app/views/projects/pages_domains/_helper_text.html.haml

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

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

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.
 

doc/pages/getting_started_part_three.md

 ---
-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).

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)

doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md

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

doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md

+---
+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/).

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.

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

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

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) }