GitLab 製品ドキュメントのホスト

docs.gitlab.com 、GitLab製品ドキュメントにアクセスできない場合、代わりに自分でドキュメントをホストすることができます。

前提条件：

  • 製品ドキュメントサイトのバージョンは、GitLabインストールのバージョンと同じである必要があります。

ドキュメントのセルフホスティングオプション

GitLab製品ドキュメントをホストするには、以下の方法があります：

  • Dockerコンテナ
  • GitLab Pages
  • 自分のウェブサーバ

これらの方法のいずれかを使用してウェブサイトを作成した後、製品内のUIリンクをあなたのウェブサイトを指すようにリダイレクトします。

note
作成したウェブサイトは、インストールしたGitLabのバージョンと同じサブディレクトリ（例えば、14.5/ ）でホストする必要があります。Dockerイメージはデフォルトでこのバージョンを使用します。

以下の例では、GitLab 14.5を使用しています。

Dockerを使った製品ドキュメントのセルフホスト

ドキュメントのウェブサイトは、コンテナ内部のポート4000 で提供されます。以下の例では、同じポートでホスト上に公開しています。

どちらかを確認してください：

  • ファイアウォールでポート4000 を許可してください。
  • 別のポートを使用してください。以下の例では、左端の4000 を別のポート番号に置き換えてください。

GitLab 製品ドキュメントのウェブサイトを Docker コンテナで実行するには：

  1. GitLabをホストしているサーバー、またはGitLabインスタンスが通信できる他のサーバー：

    • 普通のDockerを使う場合は、以下を実行します：

       docker run --detach --name gitlab_docs -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.5

    • GitLab インスタンスをDocker composerを使ってホストしている場合は、既存の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'

      そして、変更をプルします：

       docker-compose up -d
  2. http://0.0.0.0:4000 にアクセスして、ドキュメントのウェブサイトを表示し、動作することを確認してください。
  3. ヘルプリンクを新しいドキュメントサイトにリダイレクトします。

GitLab Pages を使って製品ドキュメントをセルフホストします。

GitLab Pagesを使ってGitLab製品ドキュメントをホストすることができます。

前提条件

  • Pages サイトの URL がサブフォルダを使用していないことを確認してください。サイトが事前にコンパイルされているため、CSSとJavaScriptファイルはメインドメインまたはサブドメインからの相対パスとなります。例えば、https://example.com/docs/ のようなURLはサポートされていません。

GitLab Pagesで製品ドキュメントサイトをホストするには：

  1. 空白のプロジェクトを作成します。

  2. 新しく作成するか、既存の.gitlab-ci.yml ファイルを編集して、次のpages ジョブを追加します。バージョンが GitLab のインストールと同じであることを確認してください：

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

  3. オプション。GitLab Pagesドメイン名を設定します。GitLab Pagesウェブサイトのタイプによって、2つのオプションがあります：

    ウェブサイトの種類デフォルトドメインカスタムドメイン
    プロジェクトウェブサイト未対応対応
    ユーザーまたはグループのウェブサイト対応対応
  4. ヘルプリンクを新しいドキュメントサイトにリダイレクトします。

ご自身のウェブサーバーで製品ドキュメントをセルフホストしてください。

製品ドキュメントのサイトは静的なので、/usr/share/nginx/html のコンテンツをコンテナ内部から取得し、自分のウェブサーバーを使って好きな場所でドキュメントをホストすることができます。

html ディレクトリは、次のような構造になっています：

├── 14.5/
├── index.html

この例では:

  • 14.5/ はドキュメントが置かれているディレクトリです。
  • index.html は、ドキュメントを含むディレクトリにリダイレクトするシンプルな HTML ファイルです。この場合、14.5/.

ドキュメント・サイトのHTMLファイルを展開するには：

  1. ドキュメント・サイトの HTML ファイルを格納するコンテナを作成します：

    docker create -it --name gitlab_docs registry.gitlab.com/gitlab-org/gitlab-docs:14.5

  2. /srv/gitlab/ の下にウェブサイトをコピーします：

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

    /srv/gitlab/html/ 、ドキュメントのウェブサイトを格納するディレクトリができます。

  3. コンテナを削除します：

    docker rm -f gitlab_docs
  4. /srv/gitlab/html/ のコンテンツを提供するようにウェブサーバーを指定します。
  5. ヘルプリンクを新しいドキュメントサイトにリダイレクトします。

ローカルの製品ドキュメンテーションサイトが稼働したら、GitLabアプリケーションのヘルプリンクをローカルのサイトにリダイレクトします。ドキュメンテーションのURLとして完全修飾ドメイン名を使用します。例えば、Dockerの方法を使った場合は、http://0.0.0.0:4000.

バージョンを追加する必要はありません。GitLabがそれを検出し、必要に応じてドキュメントURLリクエストに追加します。例えば、GitLabのバージョンが14.5の場合：

  • GitLabドキュメントのURLはhttp://0.0.0.0:4000/14.5/ になります。
  • GitLab のリンクは<instance_url>/help/administration/settings/help_page#destination-requirements と表示されます。
  • リンクを選択すると、http://0.0.0.0:4000/14.5/ee/administration/settings/help_page/#destination-requirements にリダイレクトされます。

設定をテストするには、GitLabでLearn moreリンクを選択してください。例えば

  1. 左のサイドバーで、自分のアバターを選択してください。
  2. 環境設定を選択します。
  3. 構文強調表示のテーマセクションで、[さらに詳しく]を選択します。

製品ドキュメントを新しいバージョンにアップグレード

ドキュメントサイトを新しいバージョンにアップグレードするには、新しいDockerイメージタグをダウンロードする必要があります。

Dockerを使用したアップグレード

Dockerを使用して新しいバージョンにアップグレードするには：

  • Dockerを使用する場合：

    1. 実行中のコンテナを停止します：

      sudo docker stop gitlab_docs

    2. 既存のコンテナを削除します：

      sudo docker rm gitlab_docs

    3. 新しいイメージを取り出します。例えば、14.6：

      docker run --detach --name gitlab_docs -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.6

  • Docker Composerを使用する場合：

    1. docker-compose.yaml のバージョンを変更してください（例：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'

    2. 変更を取り下げます：

      docker-compose up -d

GitLab Pages を使ったアップグレード

GitLab Pagesを使って新しいバージョンにアップグレードするには：

  1. 既存の.gitlab-ci.yml ファイルを編集し、image のバージョン番号を置き換えてください：

    image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5

  2. 変更をコミットしてプッシュすると、GitLab Pagesが新しいドキュメントサイトのバージョンをプルします。

自分のウェブサーバを使ってアップグレード

ご自身のウェブサーバを使用して新しいバージョンにアップグレードするには、以下の手順に従います：

  1. ドキュメントサイトのHTMLファイルをコピーしてください：

    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

  2. オプション。古いサイトを削除します：

    rm -r /srv/gitlab/html/14.5/

既知のイシュー

製品ドキュメントをセルフホストする場合

  • デフォルトでは、ランディングページはそれぞれのバージョン（例えば、/14.5/ ）にリダイレクトされます。このため、ランディングページhttps://docs.gitlab.com は表示されません。