diff options
Diffstat (limited to 'doc/administration/docs_self_host.md')
| -rw-r--r-- | doc/administration/docs_self_host.md | 109 |
1 files changed, 58 insertions, 51 deletions
diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md index 4e45fe3a1c8..007055b5de7 100644 --- a/doc/administration/docs_self_host.md +++ b/doc/administration/docs_self_host.md @@ -6,18 +6,37 @@ info: To determine the technical writer assigned to the Stage/Group associated w # How to self-host the docs site **(FREE SELF)** -The following guide describes how to use a local instance of the docs site with -a self-managed GitLab instance. +If you have a self-managed instance of GitLab, you may not be able to access the +product documentation as hosted on `docs.gitlab.com` from your GitLab instance. -## Run the docs site +Be aware of the following items if you self-host the product documentation: -The easiest way to run the docs site locally it to pick up one of the existing -Docker images that contain the HTML files. +- You must host the product documentation site under a subdirectory that matches + your installed GitLab version (for example, `14.5/`). The + [Docker images](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635) + hosted by the GitLab Docs team provide this by default. We use a + [script](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/2995d1378175803b22fb8806ba77adf63e79f32c/scripts/normalize-links.sh#L28-82) + to normalize the links and prefix them with the respective version. +- The version dropdown will display additional versions that don't exist, selecting + those versions will display a 404 Not Found page. +- Results when using the search box will display results from `docs.gitlab.com` + and not the local documentation. +- When you use the Docker images to serve the product documentation site, by + default the landing page redirects to the respective version (for example, `/14.5/`), + which causes the landing page <https://docs.gitlab.com> to not be displayed. + +## Documentation self-hosting options -Pick the version that matches your GitLab version and run it, in the following -examples 14.5. +You can self-host the GitLab product documentation locally using one of these +methods: -### Host the docs site using Docker +- Docker +- GitLab Pages +- From your own webserver + +The examples on this page are based on GitLab 14.5. + +### Self-host the product documentation with Docker The Docker images use a built-in webserver listening on port `4000`, so you need to expose that. @@ -42,9 +61,9 @@ services: - '4000:4000' ``` -### Host the docs site using GitLab Pages +### Self-host the product documentation with GitLab Pages -You can also host the docs site with GitLab Pages. +You use GitLab Pages to host the GitLab product documentation locally. Prerequisite: @@ -53,11 +72,11 @@ Prerequisite: main domain or subdomain. For example, URLs like `https://example.com/docs/` are not supported. -To host the docs site with GitLab Pages: +To host the product documentation site with GitLab Pages: 1. [Create a new blank project](../user/project/working_with_projects.md#create-a-blank-project). -1. Create a new or edit your existing `.gitlab-ci.yml` file and add the following - `pages` job. Make sure the version is the same as your GitLab installation: +1. Create a new or edit your existing `.gitlab-ci.yml` file, and add the following + `pages` job, while ensuring the version is the same as your GitLab installation: ```yaml image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5 @@ -70,20 +89,22 @@ To host the docs site with GitLab Pages: - public ``` -1. (Optional) Set the Pages domain name. Depending on the type of the Pages website, - you have two options: +1. Optional. Set the GitLab Pages domain name. Depending on the type of the + GitLab Pages website, you have two options: - | Type of website | [Default domain](../user/project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names) | [Custom domain](../user/project/pages/custom_domains_ssl_tls_certification/index.md) | - | --------------- | -------------- | ------------- | + | Type of website | [Default domain](../user/project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names) | [Custom domain](../user/project/pages/custom_domains_ssl_tls_certification/index.md) | + |-------------------------|----------------|---------------| | [Project website](../user/project/pages/getting_started_part_one.md#project-website-examples) | Not supported | Supported | | [User or group website](../user/project/pages/getting_started_part_one.md#user-and-group-website-examples) | Supported | Supported | -### Host the docs site on your own webserver +### Self-host the product documentation on your own webserver + +Because the product documentation site is static, you can grab the directory from +the container (in `/usr/share/nginx/html`) and use your own web server to host +it wherever you want. -Since the docs site is static, you can grab the directory from the container -(under `/usr/share/nginx/html`) and use your own web server to host -it wherever you want. Replace `<destination>` with the directory where the -docs will be copied to: +Use the following commands, and replace `<destination>` with the directory where the +documentation files will be copied to: ```shell docker create -it --name gitlab-docs registry.gitlab.com/gitlab-org/gitlab-docs:14.5 @@ -93,32 +114,18 @@ docker rm -f gitlab-docs ## Redirect the `/help` links to the new docs page -When the docs site is up and running: - -1. [Enable the help page redirects](../user/admin_area/settings/help_page.md#redirect-help-pages). - Use the Fully Qualified Domain Name as the docs URL. For example, if you - used the [Docker method](#host-the-docs-site-using-docker) , enter `http://0.0.0.0:4000`. - You don't need to append the version, it is detected automatically. -1. Test that everything works by selecting the **Learn more** link on the page - you're on. Your GitLab version is automatically detected and appended to the docs URL - you set in the admin area. In this example, if your GitLab version is 14.5, - `https://<instance_url>/` becomes `http://0.0.0.0:4000/14.5/`. - The link inside GitLab link shows as - `<instance_url>/help/user/admin_area/settings/help_page#destination-requirements`, - but when you select it, you are redirected to - `http://0.0.0.0:4000/14.5/ee/user/admin_area/settings/help_page/#destination-requirements`. - -## Caveats - -- You need to host the docs site under a subdirectory matching your GitLab version, - in the example of this guide `14.5/`. The - [Docker images](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635) - hosted by the Docs team provide this by default. We use a - [script](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/2995d1378175803b22fb8806ba77adf63e79f32c/scripts/normalize-links.sh#L28-82) - to normalize the links and prefix them with the respective version. -- The version dropdown will show more versions which do not exist and will lead - to 404 if selected. -- The search results point to `docs.gitlab.com` and not the local docs. -- When you use the Docker images to serve the docs site, the landing page redirects - by default to the respective version, for example `/14.5/`, so you don't - see the landing page as seen at <https://docs.gitlab.com>. +After your local product documentation site is running, [redirect the help +links](../user/admin_area/settings/help_page.md#redirect-help-pages) in the GitLab +application to your local site. + +Be sure to use the fully qualified domain name as the docs URL. For example, if you +used the [Docker method](#self-host-the-product-documentation-with-docker), enter `http://0.0.0.0:4000`. + +You don't need to append the version, as GitLab will detect it and append it to +any documentation URL requests, as needed. For example, if your GitLab version is +14.5, the GitLab Docs URL becomes `http://0.0.0.0:4000/14.5/`. The link +inside GitLab displays as `<instance_url>/help/user/admin_area/settings/help_page#destination-requirements`, +but when you select it, you are redirected to +`http://0.0.0.0:4000/14.5/ee/user/admin_area/settings/help_page/#destination-requirements`. + +To test the setting, select a **Learn more** link within the GitLab application. |