8.7 KiB
stage | group | info |
---|---|---|
Enablement | Distribution | 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 |
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.
Prerequisites:
- The version of the product documentation site must be the same as the version of your GitLab installation.
Documentation self-hosting options
To host the GitLab product documentation, you can use:
- A Docker container
- GitLab Pages
- 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.
NOTE:
The website you create must be hosted under a subdirectory that matches
your installed GitLab version (for example, 14.5/
). The
Docker images
use this version by default.
The following examples use GitLab 14.5.
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 the port different port.
To run the GitLab product documentation website in a Docker container:
-
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:
docker run --detach --name gitlab_docs -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.5
-
If you host your GitLab instance using Docker compose, add the following to your existing
docker-compose.yaml
:version: '3.6' services: gitlab_docs: image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5 hostname: 'https://docs.gitlab.example.com:4000' ports: - '4000:4000'
Then, pull the changes:
docker-compose up -d
-
-
Visit
http://0.0.0.0:4000
to view the documentation website and verify it works.
Self-host the product documentation with GitLab Pages
You can use GitLab Pages to host the GitLab product documentation.
Prerequisite:
- 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:
-
Create a new or edit your existing
.gitlab-ci.yml
file, and add the followingpages
job, while ensuring the version is the same as your GitLab installation:image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5 pages: script: - mkdir public - cp -a /usr/share/nginx/html/* public/ artifacts: paths: - public
-
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
Self-host the product documentation on your own web server
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 docs wherever you want.
The html
directory should be served as is and it has the following structure:
├── 14.5/
├── index.html
In this example:
14.5/
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,14.5/
.
To extract the HTML files of the Docs site:
-
Create the container that holds the HTML files of the documentation website:
docker create -it --name gitlab_docs registry.gitlab.com/gitlab-org/gitlab-docs:14.5
-
Copy the website under
/srv/gitlab/
:docker cp gitlab-docs:/usr/share/nginx/html /srv/gitlab/
You will end up with a
/srv/gitlab/html/
directory that holds the documentation website. -
Remove the container:
docker rm -f gitlab_docs
-
Point your web server to serve the contents of
/srv/gitlab/html/
.
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 docs 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 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.
Upgrade the product documentation to a later version
Upgrading the Docs 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 plain Docker:
-
Stop the running container:
sudo docker stop gitlab_docs
-
Remove the existing container:
sudo docker rm gitlab_docs
-
Pull the new image. For example, 14.6:
docker run --detach --name gitlab_docs -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.6
-
-
If you use Docker compose:
-
Change the version in
docker-compose.yaml
, for example 14.6:version: '3.6' services: gitlab_docs: image: registry.gitlab.com/gitlab-org/gitlab-docs:14.6 hostname: 'https://docs.gitlab.example.com:4000' ports: - '4000:4000'
-
Pull the changes:
docker-compose up -d
-
Upgrade using GitLab Pages
To upgrade to a later version using GitLab Pages:
-
Edit your existing
.gitlab-ci.yml
file, and replace theimage
's version number:image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5
-
Commit the changes, push, and GitLab Pages pulls the new Docs site version.
Upgrade using your own web-server
To upgrade to a later version using your own web-server:
-
Copy the HTML files of the Docs site:
docker create -it --name gitlab_docs registry.gitlab.com/gitlab-org/gitlab-docs:14.6 docker cp gitlab_docs:/usr/share/nginx/html /srv/gitlab/ docker rm -f gitlab_docs
-
Optional. Remove the old site:
rm -r /srv/gitlab/html/14.5/
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.