From db782d184010b14858e3de8400531f841ee474e7 Mon Sep 17 00:00:00 2001 From: Vladimir Shushlin Date: Wed, 17 Jul 2019 13:00:46 +0000 Subject: Add docs for Let's Encrypt integration * Add deprecation warning to old integration * Add user docs * Add admin docs --- app/views/projects/pages_domains/_form.html.haml | 2 +- .../pages/img/lets_encrypt_integration_v12_1.png | Bin 0 -> 98409 bytes doc/administration/pages/index.md | 17 ++++++ .../img/lets_encrypt_integration_v12_1.png | Bin 0 -> 35040 bytes .../custom_domains_ssl_tls_certification/index.md | 11 +++- .../lets_encrypt_integration.md | 68 +++++++++++++++++++++ doc/user/project/pages/index.md | 2 +- .../project/pages/lets_encrypt_for_gitlab_pages.md | 11 +++- 8 files changed, 105 insertions(+), 6 deletions(-) create mode 100644 doc/administration/pages/img/lets_encrypt_integration_v12_1.png create mode 100644 doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png create mode 100644 doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md diff --git a/app/views/projects/pages_domains/_form.html.haml b/app/views/projects/pages_domains/_form.html.haml index 0e5c65a2f72..4aa1e574d93 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/custom_domains_ssl_tls_certification/lets_encrypt_integration.md") - docs_link_start = "".html_safe % { docs_link_url: docs_link_url } - docs_link_end = "".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_integration_v12_1.png b/doc/administration/pages/img/lets_encrypt_integration_v12_1.png new file mode 100644 index 00000000000..5ab63074e12 Binary files /dev/null and b/doc/administration/pages/img/lets_encrypt_integration_v12_1.png differ diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 3cabe8eb16e..774e7056845 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -265,6 +265,23 @@ 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. + +[GitLab Pages' Let's Encrypt integration](../../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) +allows users to add Let's Encrypt SSL certificates for GitLab Pages +sites served under a custom domain. + +To enable it, you'll need to: + +1. Choose an email on which you will recieve notifications about expiring domains. +1. Navigate to your instance's **Admin Area > Settings > Preferences** and expand **Pages** settings. +1. Enter the email for receiving notifications and accept Let's Encrypt's Terms of Service as shown below. +1. Click **Save changes**. + +![Let's Encrypt settings](img/lets_encrypt_integration_v12_1.png) + ### Access control > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png new file mode 100644 index 00000000000..2e825e84d92 Binary files /dev/null and b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png 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 index 219e141d72e..54ecc42d2b9 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -204,6 +204,14 @@ can use the following setup: Read this document for an [overview on SSL/TLS certification](ssl_tls_concepts.md). +To secure your custom domain with GitLab Pages you can opt by: + +- Using the [Let's Encrypt integration with GitLab Pages](lets_encrypt_integration.md), + which automatically obtains and renews SSL certificates + for your Pages domains. +- Manually adding SSL/TLS certificates to GitLab Pages websites + by following the steps below. + ### Requirements - A GitLab Pages website up and running accessible via a custom domain. @@ -255,6 +263,7 @@ To enable this setting: 1. Navigate to your project's **Settings > Pages**. 1. Tick the checkbox **Force HTTPS (requires valid certificates)**. + \ No newline at end of file +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md new file mode 100644 index 00000000000..7675a5dd9d4 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -0,0 +1,68 @@ +--- +type: reference +description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." +--- + +# GitLab Pages integration with Let's Encrypt + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996) in GitLab 12.1. + +The GitLab Pages integration with Let's Encrypt (LE) allows you +to use LE certificates for your Pages website with custom domains +without the hassle of having to issue and update them yourself; +GitLab does it for you, out-of-the-box. + +[Let's Encrypt](https://letsencrypt.org) is a free, automated, and +open source Certificate Authority. + +## Requirements + +Before you can enable automatic provisioning of a SSL certificate for your domain, make sure you have: + +- Created a [project](../getting_started_part_two.md) in GitLab + containing your website's source code. +- Acquired a domain (`example.com`) and added a [DNS entry](index.md) + pointing it to your Pages website. +- [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) + and verified your ownership. +- Have your website up and running, accessible through your custom domain. + +NOTE: **Note:** +GitLab's Let's Encrypt integration is enabled and available on GitLab.com. +For **self-managed** GitLab instances, make sure your administrator has +[enabled it](../../../../administration/pages/index.md#lets-encrypt-integration). + +## Enabling Let's Encrypt integration for your custom domain + +Once you've met the requirements, to enable Let's Encrypt integration: + +1. Navigate to your project's **Settings > Pages**. +1. Find your domain and click **Details**. +1. Click **Edit** in the top-right corner. +1. Enable Let's Encrypt integration by switching **Automatic certificate management using Let's Encrypt**: + + ![Enable Let's Encrypt](img/lets_encrypt_integration_v12_1.png) + +1. Click **Save changes**. + +Once enabled, GitLab will obtain a LE certificate and add it to the +associated Pages domain. It will be also renewed automatically by GitLab. + +> **Notes:** +> +> - Issuing the certificate 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 be replaced by Let's Encrypt's certificate. + + diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index e9d2e9a0059..25944b029d7 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -143,8 +143,8 @@ To learn more about configuration options for GitLab Pages, read the following: | [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](custom_domains_ssl_tls_certification/index.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. | +| [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates automatically obtained and renewed by GitLab. | | [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 cc129f90b7a..1338c7e58f5 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,10 +1,15 @@ --- -description: "How to secure GitLab Pages websites with Let's Encrypt." +description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." type: howto -last_updated: 2019-06-04 +last_updated: 2019-07-15 --- -# Let's Encrypt for GitLab Pages +# Let's Encrypt for GitLab Pages (manual process, deprecated) + +CAUTION: **Warning:** +This method is still valid but was **deprecated** in favor of the +[Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) +introduced in GitLab 12.1. If you have a GitLab Pages website served under your own domain, you might want to secure it with a SSL/TSL certificate. -- cgit v1.2.1