diff options
Diffstat (limited to 'doc/administration/docs_self_host.md')
| -rw-r--r-- | doc/administration/docs_self_host.md | 124 |
1 files changed, 64 insertions, 60 deletions
diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md index 007055b5de7..3a4511e5aa4 100644 --- a/doc/administration/docs_self_host.md +++ b/doc/administration/docs_self_host.md @@ -4,77 +4,69 @@ group: Distribution 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 --- -# How to self-host the docs site **(FREE SELF)** - -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. - -Be aware of the following items if you self-host the product documentation: - -- 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. +# How to host the GitLab product documentation **(FREE SELF)** + +If you are not able to access the GitLab product documentation at `docs.gitlab.com`, +you can host the documentation yourself instead. ## Documentation self-hosting options -You can self-host the GitLab product documentation locally using one of these -methods: +To host the GitLab product documentation, you can use: -- Docker +- A Docker container - GitLab Pages -- From your own webserver +- Your own web server + +After you create a website by using one of these methods, you redirect the UI links +in the product to point to your website. -The examples on this page are based on GitLab 14.5. +NOTE: +The website you create must be hosted 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) +use this version by default. + +The following examples use 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. +You can run the GitLab product documentation website in a Docker container: -In the server that you host GitLab, or any other server that your GitLab instance -can talk to, you can use Docker to pull the docs site: +1. Expose port `4000`. The Docker image uses this port for the web server. +1. On the server where you host GitLab, or on any other server that your GitLab instance + can communicate with, pull the docs site: -```shell -docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.5 -``` + ```shell + docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.5 + ``` -If you use [Docker compose](../install/docker.md#install-gitlab-using-docker-compose) -to host your GitLab instance, add the following to `docker-compose.yaml`: - -```yaml -version: '3.6' -services: - docs: - image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5 - hostname: 'https://gitlab.example.com' - ports: - - '4000:4000' -``` + If you host your GitLab instance using [Docker compose](../install/docker.md#install-gitlab-using-docker-compose), + add the following to `docker-compose.yaml`: + + ```yaml + version: '3.6' + services: + docs: + image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5 + hostname: 'https://gitlab.example.com' + ports: + - '4000:4000' + ``` ### Self-host the product documentation with GitLab Pages -You use GitLab Pages to host the GitLab product documentation locally. +You can use GitLab Pages to host the GitLab product documentation. Prerequisite: -- The Pages site URL must not use a subfolder. Due to the nature of how the docs +- Ensure the Pages site URL does not use a subfolder. Because of how the docs site is pre-compiled, the CSS and JavaScript files are relative to the main domain or subdomain. For example, URLs like `https://example.com/docs/` are not supported. 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 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, while ensuring the version is the same as your GitLab installation: @@ -97,13 +89,13 @@ To host the product documentation site with GitLab Pages: | [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 | -### Self-host the product documentation on your own webserver +### Self-host the product documentation on your own web server -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. +Because the product documentation site is static, from the container, you can take the contents +of `/usr/share/nginx/html` and use your own web server to host +the docs wherever you want. -Use the following commands, and replace `<destination>` with the directory where the +Run the following commands, replacing `<destination>` with the directory where the documentation files will be copied to: ```shell @@ -114,18 +106,30 @@ docker rm -f gitlab-docs ## Redirect the `/help` links to the new docs page -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. +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 +You don't need to append the version. GitLab detects it and appends it to +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 in GitLab displays as `<instance_url>/help/user/admin_area/settings/help_page#destination-requirements`. +- When you select the link, 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. + +## Known issues + +If you self-host the product documentation: + +- The version dropdown displays additional versions that don't exist. Selecting + these versions displays a `404 Not Found` page. +- The search displays results from `docs.gitlab.com` and not the local site. +- By default, the landing page redirects to the + respective version (for example, `/14.5/`). This causes the landing page <https://docs.gitlab.com> to not be displayed. |