diff options
Diffstat (limited to 'doc/user/project/pages')
8 files changed, 244 insertions, 22 deletions
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 2c668e2c409..03f8ecac77f 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 @@ -7,17 +7,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Custom domains and SSL/TLS certificates **(FREE)** -Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4, you can use verified domains to [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). -To use one or more custom domain names with your Pages site, you can: +You can use custom domains: -- Add a [custom **root domain** or a **subdomain**](#set-up-pages-with-a-custom-domain). +- With GitLab Pages. +- To [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). + When using custom domains this way, you use the GitLab Pages feature but can skip the [requirements](#requirements). + +To use one or more custom domain names: + +- Add a [custom **root domain** or a **subdomain**](#set-up-a-custom-domain). - Add [SSL/TLS certification](#adding-an-ssltls-certificate-to-pages). -## Set up Pages with a custom domain +## Set up a custom domain -To set up Pages with a custom domain name, read the requirements -and steps below. +To set up Pages with a custom domain name, read the requirements and steps below. ### Requirements @@ -45,7 +50,7 @@ and steps below. 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 +#### 1. Add a custom domain Navigate to your project's **Setting > Pages** and select **+ New domain** to add your custom domain to GitLab Pages. You can choose whether to: @@ -64,7 +69,7 @@ and paste them in your domain's control panel as a `TXT` record on the next step  -#### 3. Set up DNS records for Pages +#### 3. Set up DNS records 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 @@ -144,7 +149,7 @@ They require: | `_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). +[Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirect-wwwdomaincom-to-domaincom-with-cloudflare). > **Notes**: > @@ -186,7 +191,7 @@ from the GitLab project. in place. Your domain is periodically reverified, and may be disabled if the record is removed. -##### Troubleshooting Pages domain verification +##### Troubleshoot domain verification To manually verify that you have properly configured the domain verification `TXT` DNS entry, you can run the following command in your terminal: @@ -218,7 +223,7 @@ For a subdomain: | `www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | | `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -### Adding more domain aliases +### Add 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. @@ -226,7 +231,7 @@ An alias can be understood as having many doors leading to the same room. All the aliases you've set to your site are listed on **Setting > Pages**. From that page, you can view, add, and remove them. -### Redirecting `www.domain.com` to `domain.com` with Cloudflare +### Redirect `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. 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 index 0cc6cb808d1..b5487f7a465 100644 --- 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 @@ -30,7 +30,7 @@ Before you can enable automatic provisioning of an SSL certificate for your doma - Acquired a domain (`example.com`) and added a [DNS entry](index.md) pointing it to your Pages website. The top-level domain (`.com`) must be a [public suffix](https://publicsuffix.org/). -- [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) +- [Added your domain to your Pages project](index.md#1-add-a-custom-domain) and verified your ownership. - Verified your website is up and running, accessible through your custom domain. @@ -76,7 +76,7 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. 1. Make sure your domain **doesn't have** an `AAAA` DNS record. 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). - 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain-to-pages). + 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain). 1. Go to step 1. ### Message "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later." hangs for more than an hour @@ -85,7 +85,7 @@ If you've enabled Let's Encrypt integration, but a certificate is absent after a 1. Go to your project's **Settings > Pages**. 1. Select **Remove** on your domain. -1. [Add the domain again and verify it](index.md#1-add-a-custom-domain-to-pages). +1. [Add the domain again and verify it](index.md#1-add-a-custom-domain). 1. [Enable Let's Encrypt integration for your domain](#enabling-lets-encrypt-integration-for-your-custom-domain). 1. If you still see the same message after some time: 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 510f9332e7b..58e15104815 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -16,7 +16,7 @@ Use a `.gitlab-ci.yml` template when you have an existing project that you want Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete these steps, you may have to do additional configuration for the Pages site to generate properly. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select the project's name. 1. From the **Add** (**{plus}**) dropdown, select **New file**. 1. From the **Select a template type** dropdown, select `.gitlab-ci.yml`. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 68a2a6a80ad..1c3d5d722cb 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -266,6 +266,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production ``` Now add another job to the CI file, telling it to @@ -289,6 +290,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production test: stage: test @@ -342,6 +344,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production test: stage: test @@ -386,6 +389,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production test: stage: test @@ -420,7 +424,7 @@ Now GitLab CI/CD not only builds the website, but also: For more information, see the following blog posts. -- Use GitLab CI/CD `environments` to +- Use GitLab CI/CD `environments` to [deploy your web app to staging and production](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). - Learn how to run jobs [sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md new file mode 100644 index 00000000000..7e618fbaec8 --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -0,0 +1,58 @@ +--- +stage: Create +group: Incubation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Tutorial: Use the GitLab UI to deploy your static site **(FREE)** + +This tutorial assumes you have a project that either: + +- Generates static sites or a client-rendered single-page application (SPA), + such as [Eleventy](https://www.11ty.dev), [Astro](https://astro.build), or [Jekyll](https://jekyllrb.com). +- Contains a framework configured for static output, such as [Next.js](https://nextjs.org), + [Nuxt.js](https://nuxtjs.org), or [SvelteKit](https://kit.svelte.dev). + +## Update your app to output files to the `public` folder + +GitLab Pages requires all files intended to be part of the published website to +be in a root-level folder called `public`. If you create this folder during the build +pipeline, committing it to Git is not required. + +For detailed instructions, read [Configure the public files folder](../public_folder.md). + +## Set up the `.gitlab-ci.yml` file + +GitLab helps you write the `.gitlab-ci.yml` needed to create your first GitLab Pages +deployment pipeline. Rather than building the file from scratch, it asks you to +provide the build commands, and creates the necessary boilerplate for you. + +To build your YAML file from the GitLab UI: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages** to display the friendly + interface **Get Started With Pages**. +1. If your framework's build process does not need one of the provided build + commands, you can either: + - Skip the step by selecting **Next**. + - Enter `:` (the bash "do nothing" command) if you still want to incorporate that + step's boilerplate into your `.gitlab-ci.yml` file. +1. Optional. Edit and adjust the generated `.gitlab-ci.yml` file as needed. +1. Commit your `.gitlab-ci.yml` to your repository. This commit triggers your first + GitLab Pages deployment. + +## Troubleshooting + +### If you can't see the "Get Started with Pages" interface + +GitLab doesn't show this interface if you have either: + +- Deployed a GitLab Pages site before. +- Committed a `.gitlab-ci.yml` through this interface at least once. + +To fix this problem: + +- If you see the message **Waiting for the Pages Pipeline to complete**, select + **Start over** to start the wizard again. +- If your project has previously deployed GitLab Pages successfully, + [manually update](pages_from_scratch.md) your `.gitlab-ci.yml`. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index af49522efe2..1f3628b74ec 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -38,12 +38,13 @@ Learn more about To create a GitLab Pages website: -| Document | Description | -|----------|-------------| +| Document | Description | +|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------| +| [Use the GitLab UI to create a simple `.gitlab-ci.yml`](getting_started/pages_ui.md) | Add a Pages site to an existing project. Use the UI to set up a simple `.gitlab-ci.yml`. | | [Create a `.gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | -| [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | -| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | -| [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. | +| [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | +| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | +| [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. | To update a GitLab Pages website: diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 3bd16a17f23..da024881ed6 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -314,6 +314,7 @@ pages: artifacts: paths: - public + environment: production ``` The `FF_USE_FASTZIP` variable enables the [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) which is needed for [`ARTIFACT_COMPRESSION_LEVEL`](../../../ci/runners/configure_runners.md#artifact-and-cache-settings). diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md new file mode 100644 index 00000000000..f9c80875cc9 --- /dev/null +++ b/doc/user/project/pages/public_folder.md @@ -0,0 +1,153 @@ +--- +description: 'Learn how to configure the build output folder for the most +common static site generators' +stage: Create +group: Incubation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Configure the public files folder **(FREE)** + +GitLab Pages requires all files you intend to be available in the published website to +be in a root-level folder called `public`. This page describe how +to set this up for some common static site generators. + +## Guide by framework + +### Eleventy + +For Eleventy, you should either: + +1. Add the `--output=public` flag in Eleventy's build commands, for example: + + `npx @11ty/eleventy --input=path/to/sourcefiles --output=public` + +1. Add the following to your `.eleventy.js` file: + + ```javascript + // .eleventy.js + module.exports = function(eleventyConfig) { + return { + dir: { + output: "public" + } + } + }; + ``` + +### Astro + +By default, Astro uses the `public` folder to store static assets. For GitLab Pages, +rename that folder to a collision-free alternative first: + +1. In your project directory, run: + + ```shell + mv public static + ``` + +1. Add the following to your `astro.config.mjs`. This code informs Astro about + our folder name remapping: + + ```javascript + // astro.config.mjs + export default { + // GitLab Pages requires exposed files to be located in a folder called "public". + // So we're instructing Astro to put the static build output in a folder of that name. + dist: 'public', + + // The folder name Astro uses for static files (`public`) is already reserved + // for the build output. So in deviation from the defaults we're using a folder + // called `static` instead. + public: 'static', + }; + ``` + +### SvelteKit + +NOTE: +GitLab Pages supports only static sites. For SvelteKit, +we recommend using [`adapter-static`](https://kit.svelte.dev/docs/adapters#supported-environments-static-sites). + +When using `adapter-static`, add the following to your `svelte.config.js`: + +```javascript +// svelte.config.js +import adapter from '@sveltejs/adapter-static'; + +export default { + kit: { + adapter: adapter({ + pages: 'public' + }) + } +}; +``` + +### Next.js + +NOTE: +GitLab Pages supports only static sites. For Next.js, we +recommend using Next's [Static HTML export functionality](https://nextjs.org/docs/advanced-features/static-html-export) + +Use the `-o public` flag after `next export` as the build command, for +example: + +```shell +next export -o public +``` + +### Nuxt.js + +NOTE: +GitLab Pages supports only static sites. + +1. Add the following to your `nuxt.config.js`: + + ```javascript + export default { + target: 'static', + generate: { + dir: 'public' + } + } + ``` + +1. Configure your Nuxt.js application for + [Static Site Generation](https://nuxtjs.org/docs/features/deployment-targets#static-hosting). + +### Vite + +Update your `vite.config.js` to include the following: + +```javascript +// vite.config.js +export default { + build: { + outDir: 'public' + } +} +``` + +### Webpack + +Update your `webpack.config.js` to include the following: + +```javascript +// webpack.config.js +module.exports = { + output: { + path: __dirname + '/public' + } +}; +``` + +## Should you commit the `public` folder? + +Not necessarily. However, when the GitLab Pages deploy pipeline runs, it looks +for an [artifact](../../../ci/pipelines/job_artifacts.md) of that name. So +If you set up a job that creates the `public` folder before deploy, such as by +running `npm run build`, committing the folder isn't required. + +If you prefer to build your site locally, you can commit the `public` folder and +omit the build step during the job, instead. |