diff options
Diffstat (limited to 'doc/administration/docs_self_host.md')
| -rw-r--r-- | doc/administration/docs_self_host.md | 197 |
1 files changed, 165 insertions, 32 deletions
diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md index 8464c35c3bb..338601a054f 100644 --- a/doc/administration/docs_self_host.md +++ b/doc/administration/docs_self_host.md @@ -1,14 +1,19 @@ --- -stage: Enablement +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/engineering/ux/technical-writing/#assignments --- -# How to host the GitLab product documentation **(FREE SELF)** +# 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: @@ -30,28 +35,48 @@ The following examples use GitLab 14.5. ### Self-host the product documentation with Docker -You can run the GitLab product documentation website in a Docker container: +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: -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: + can communicate with: - ```shell - docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.5 - ``` + - If you use plain Docker, run: - If you host your GitLab instance using [Docker compose](../install/docker.md#install-gitlab-using-docker-compose), - add the following to `docker-compose.yaml`: + ```shell + docker run --detach --name gitlab_docs -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.5 + ``` - ```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 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 + 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 @@ -89,29 +114,59 @@ 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 | +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, from the container, you can take the contents -of `/usr/share/nginx/html` and use your own web server to host +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. -Run the following commands, replacing `<destination>` with the directory where the -documentation files will be copied to: +The `html` directory should be served as is and it has the following structure: -```shell -docker create -it --name gitlab-docs registry.gitlab.com/gitlab-org/gitlab-docs:14.5 -docker cp gitlab-docs:/usr/share/nginx/html <destination> -docker rm -f gitlab-docs +```plaintext +├── 14.5/ +├── index.html ``` -## Redirect the `/help` links to the new docs page +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 will 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. - -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`. +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 @@ -124,6 +179,84 @@ documentation URL requests as needed. For example, if your GitLab version is 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](#self-host-the-product-documentation-with-docker): + +- If you use plain 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`'s 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: |