Commit 038bc23b authored by Suzanne Selhorn's avatar Suzanne Selhorn Committed by Achilleas Pipinellis

A few edits to help set the context

I had a little trouble understanding this page so
I made a few edits to try to clarify.
I also removed the list of known issues to the bottom.
parent d80d61d3
......@@ -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.
Markdown is supported
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