Host the GitLab product documentation

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab Self-Managed

{{< /details >}}

If you are not able to access the GitLab product documentation at docs.gitlab.com, you can host the documentation yourself instead.

[!note] The local help of your instance does not include all the docs (for example, it doesn't include docs for GitLab Runner or GitLab Operator), and it's not searchable or browsable. It's intended to only support direct links to specific pages from within your instance.

Container registry URL

The URL to the container image you want depends on the version of the GitLab Docs you need. See the following table as a guide for the URL to use in the following sections.

Documentation self-hosting options

To host the GitLab product documentation, you can use:

• A Docker container
• GitLab Pages
• Your own web server

The following examples use GitLab 17.8, but make sure to use the version that corresponds to your GitLab instance.

Self-host the product documentation with Docker

The documentation website is served under the port 4000 inside the container. In the following example, we expose this on the host under the same port.

Make sure you either:

• Allow port 4000 in your firewall.
• Use a different port. In following examples, replace the leftmost 4000 with a different port number.

To run the GitLab product documentation website in a Docker container:

1. On the server where you host GitLab, or on any other server that your GitLab instance can communicate with:

   • If you use plain Docker, run:

     shellCopy

     docker run --detach --name gitlab_docs -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
     

   • If you host your GitLab instance using Docker compose, add the following to your existing docker-compose.yaml:

     yamlCopy

     version: '3.6'
     services:
       gitlab_docs:
         image: registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
         hostname: 'docs.gitlab.example.com'
         ports:
           - '4000:4000'
     

     Then, pull the changes:

     shellCopy

     docker-compose up -d
     

2. Visit http://0.0.0.0:4000 to view the documentation website and verify that it works.

3. Redirect the help links to the new documentation site.

Self-host the product documentation with GitLab Pages

You can use GitLab Pages to host the GitLab product documentation.

Prerequisites:

• Ensure the Pages site URL does not use a subfolder. Because of the way the 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 blank project.

2. 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:

   yamlCopy

   pages:
     image: registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
     script:
       - mkdir public
       - cp -a /usr/share/nginx/html/* public/
     artifacts:
       paths:
       - public
   

3. 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	Custom domain
   Project website	Not supported	Supported
   User or group website	Supported	Supported

4. Redirect the help links to the new documentation site.

Self-host the product documentation on your own web server

[!note] The website you create must be hosted under a subdirectory that matches your installed GitLab version (for example, 17.8/). The Docker images use this version by default.

Because the product documentation site is static, you can take the contents of /usr/share/nginx/html from inside the container, and use your own web server to host the documentation wherever you want.

The html directory should be served as is and it has the following structure:

├── 17.8/
├── index.html

In this example:

• 17.8/ is the directory where the documentation is hosted.
• index.html is a simple HTML file that redirects to the directory containing the documentation. In this case, 17.8/.

To extract the HTML files of the documentation site:

1. Create the container that holds the HTML files of the documentation website:

   shellCopy

   docker create -it --name gitlab_docs registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
   

2. Copy the website under /srv/gitlab/:

   shellCopy

   docker cp gitlab-docs:/usr/share/nginx/html /srv/gitlab/
   

   You end up with a /srv/gitlab/html/ directory that holds the documentation website.

3. Remove the container:

   shellCopy

   docker rm -f gitlab_docs
   

4. Point your web server to serve the contents of /srv/gitlab/html/.

5. Redirect the help links to the new documentation site.

Redirect the /help links to the new Docs site

After your local product documentation site is running, redirect the help links in the GitLab application to your local site, by using the fully qualified domain name as the documentation URL. For example, if you used the Docker method, enter http://0.0.0.0:4000.

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 17.8:

• The GitLab documentation URL becomes http://0.0.0.0:4000/17.8/.
• The link in GitLab displays as <instance_url>/help/administration/settings/help_page#destination-requirements.
• When you select the link, you are redirected to http://0.0.0.0:4000/17.8/administration/settings/help_page/#destination-requirements.

To test the setting, in GitLab, select a Learn more link. For example:

1. In the upper-right corner, select your avatar.
2. Select Preferences.
3. In the Syntax highlighting theme section, select Learn more.

Upgrade the product documentation to a later version

Upgrading the documentation site to a later version requires downloading the newer Docker image tag.

Upgrade using Docker

To upgrade to a later version using Docker:

• If you use Docker:

  1. Stop the running container:

     shellCopy

     sudo docker stop gitlab_docs
     

  2. Remove the existing container:

     shellCopy

     sudo docker rm gitlab_docs
     

  3. Pull the new image. For example, 17.8:

     shellCopy

     docker run --detach --name gitlab_docs -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
     

• If you use Docker Compose:

  1. Change the version in docker-compose.yaml, for example 17.8:

     yamlCopy

     version: '3.6'
     services:
       gitlab_docs:
         image: registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
         hostname: 'docs.gitlab.example.com'
         ports:
           - '4000:4000'
     

  2. Pull the changes:

     shellCopy

     docker-compose up -d
     

Upgrade using GitLab Pages

To upgrade to a later version using GitLab Pages:

1. Edit your existing .gitlab-ci.yml file, and replace the image version number:

   yamlCopy

   image: registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
   

2. Commit the changes, push, and GitLab Pages pulls the new documentation site version.

Upgrade using your own web-server

To upgrade to a later version using your own web-server:

1. Copy the HTML files of the documentation site:

   shellCopy

   docker create -it --name gitlab_docs registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
   docker cp gitlab_docs:/usr/share/nginx/html /srv/gitlab/
   docker rm -f gitlab_docs
   

2. Optional. Remove the old site:

   shellCopy

   rm -r /srv/gitlab/html/17.8/
   

Troubleshooting

Search does not work

Local search is included in versions 15.6 and later. If you're using an earlier version, the search doesn't work.

For more information, read about the different types of searches GitLab Docs are using.

The Docker image is not found

If you get an error that the Docker image is not found, check if you're using the correct registry URL.

Docker-hosted documentation site fails to redirect

When previewing the GitLab documentation in Docker on macOS, you may encounter an issue preventing redirection to the documentation, yielding the message If you are not redirected automatically, click here.

To escape the redirect, you need to append the version number to the URL, such as http://127.0.0.1:4000/16.8/.