Skip to content
Snippets Groups Projects
Commit 013d87ac authored by Craig Norris's avatar Craig Norris :speech_balloon: Committed by Achilleas Pipinellis
Browse files

Style and content edits for self-hosting docs 

Style and content edits for self-hosting docs
parent 538543c5
No related branches found
No related tags found
1 merge request!77689Style and content edits for self-hosting docs
This commit is part of merge request !77779. Comments created here will be created in the context of that merge request.
Hide whitespace changes
Inline Side-by-side
doc/administration/docs_self_host.md
+ 58
− 51
View file @ 013d87ac
......@@ -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.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment