1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
---
stage: Systems
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/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, 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](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 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:
```shell
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](../install/docker.md#install-gitlab-using-docker-compose),
add the following to your existing `docker-compose.yaml`:
```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:
```shell
docker-compose up -d
```
1. Visit `http://0.0.0.0:4000` to view the documentation website and verify that
it works.
1. [Redirect the help links to the new Docs site](#redirect-the-help-links-to-the-new-docs-site).
### 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 the way 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 blank project](../user/project/index.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:
```yaml
image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5
pages:
script:
- mkdir public
- cp -a /usr/share/nginx/html/* public/
artifacts:
paths:
- public
```
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) |
|-------------------------|----------------|---------------|
| [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 |
1. [Redirect the help links to the new Docs site](#redirect-the-help-links-to-the-new-docs-site).
### 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:
```plaintext
├── 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:
1. Create the container that holds the HTML files of the documentation website:
```shell
docker create -it --name gitlab_docs registry.gitlab.com/gitlab-org/gitlab-docs:14.5
```
1. Copy the website under `/srv/gitlab/`:
```shell
docker cp gitlab-docs:/usr/share/nginx/html /srv/gitlab/
```
You end up with a `/srv/gitlab/html/` directory that holds the documentation website.
1. Remove the container:
```shell
docker rm -f gitlab_docs
```
1. Point your web server to serve the contents of `/srv/gitlab/html/`.
1. [Redirect the help links to the new Docs site](#redirect-the-help-links-to-the-new-docs-site).
## Redirect the `/help` links to the new Docs 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, by using 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. 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, in GitLab, select a **Learn more** link. For example:
1. On the top bar, in the upper-right corner, select your avatar.
1. Select **Preferences**.
1. In the **Syntax highlighting theme** section, select **Learn more**.
## 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](#self-host-the-product-documentation-with-docker):
- If you use Docker:
1. Stop the running container:
```shell
sudo docker stop gitlab_docs
```
1. Remove the existing container:
```shell
sudo docker rm gitlab_docs
```
1. Pull the new image. For example, 14.6:
```shell
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:
1. Change the version in `docker-compose.yaml`, for example 14.6:
```yaml
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'
```
1. Pull the changes:
```shell
docker-compose up -d
```
### Upgrade using GitLab Pages
To upgrade to a later version [using GitLab Pages](#self-host-the-product-documentation-with-gitlab-pages):
1. Edit your existing `.gitlab-ci.yml` file, and replace the `image` version number:
```yaml
image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5
```
1. 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](#self-host-the-product-documentation-on-your-own-web-server):
1. Copy the HTML files of the Docs site:
```shell
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
```
1. Optional. Remove the old site:
```shell
rm -r /srv/gitlab/html/14.5/
```
## Known issues
If you self-host the product documentation:
- 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.
|