GitLab製品ドキュメントをホストする

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

コンテナレジストリURL

必要なコンテナイメージのURLは、必要なGitLabドキュメントのバージョンによって異なります。次のセクションで使用するURLのガイドとして、次の表を参照してください。

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

GitLab製品ドキュメントをホストするには、次のものを使用できます:

• Dockerコンテナ
• GitLab Pages
• 独自のWebサーバー

次の例ではGitLab 17.8を使用していますが、GitLabインスタンスインスタンスに対応するバージョンを使用してください。

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

ドキュメントWebサイトは、コンテナ内のポート4000で提供されます。次の例では、これをホスト上の同じポートで公開します。

次のいずれかを確認してください:

• ファイアウォールでポート4000を許可します。
• 別のポートを使用します。次の例では、左端の4000を別のポート番号に置き換えます。

DockerコンテナでGitLab製品ドキュメントWebサイトを実行するには:

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

   • プレーンDockerを使用する場合は、次を実行します:

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

   • Docker Composeを使用してGitLabインスタンスインスタンスをホストする場合は、既存のdocker-compose.yamlに次を追加します:

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

     次に、変更をプルします:

     docker-compose up -d

2. http://0.0.0.0:4000にアクセスしてドキュメントWebサイトを表示し、動作することを確認します。

3. 新しいドキュメントサイトへのヘルプリンクのリダイレクト。

GitLab Pagesを使用した製品ドキュメントのセルフホスト

GitLab Pagesを使用して、GitLab製品ドキュメントをホストできます。

前提要件:

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

GitLab Pagesを使用して製品ドキュメントサイトをホストするには:

1. 空のプロジェクトを作成。

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

   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. オプション。GitLab Pagesドメイン名を設定します。GitLab PagesWebサイトのタイプに応じて、2つのオプションがあります:

   Webサイトのタイプ	デフォルトドメイン	カスタムドメイン
   プロジェクトWebサイト	サポートされていません	サポート対象
   ユーザーまたはグループWebサイト	サポート対象	サポート対象

4. 新しいドキュメントサイトへのヘルプリンクのリダイレクト。

独自のWebサーバーでの製品ドキュメントのセルフホスト

製品ドキュメントサイトは静的なので、コンテナ内から/usr/share/nginx/htmlのコンテンツを取得し、独自のWebサーバーを使用して、必要な場所にドキュメントをホストできます。

htmlディレクトリはそのまま提供する必要があり、次の構造になっています:

├── 17.8/
├── index.html

この例では:

• 17.8/は、ドキュメントがホストされているディレクトリです。
• index.htmlは、ドキュメントを含むディレクトリにリダイレクトする単純なHTMLファイルです。この場合、17.8/。

ドキュメントサイトのHTMLファイルを抽出するには:

1. ドキュメントWebサイトのHTMLファイルを保持するコンテナを作成します:

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

2. Webサイトを/srv/gitlab/の下にコピーします:

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

   ドキュメントWebサイトを保持する/srv/gitlab/html/ディレクトリになります。

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

   docker rm -f gitlab_docs

4. /srv/gitlab/html/のコンテンツを提供するようにWebサーバーをポイントします。

5. 新しいドキュメントサイトへのヘルプリンクのリダイレクト。

新しいドキュメントサイトへの/helpリンクのリダイレクト

ローカル製品ドキュメントサイトが実行された後、ドキュメントURLとして完全修飾ドメイン名を使用して、GitLabアプリケーションのヘルプリンクをリダイレクトします。たとえば、Dockerメソッドを使用した場合は、 http://0.0.0.0:4000を入力します。

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

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

設定をテストするには、GitLabで詳細リンクを選択します。次に例を示します:

1. 左側のサイドバーで、自分のアバターを選択します。
2. 設定を選択します。
3. 構文ハイライトのテーマセクションで、詳細を選択します。

GitLab製品ドキュメントを以降のバージョンにアップグレード

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

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

以降のバージョンにアップグレードするには、Dockerを使用します:

• Dockerを使用する場合:

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

     sudo docker stop gitlab_docs

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

     sudo docker rm gitlab_docs

  3. 新しいイメージをプルします。例：17.8:

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

• Docker Composeを使用する場合:

  1. docker-compose.yamlのバージョンを変更します（たとえば、17.8）:

     version: '3.6'
     services:
       gitlab_docs:
         image: registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/archives:17.8
         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/technical-writing/docs-gitlab-com/archives:17.8

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

独自のWebサーバーを使用したアップグレード

以降のバージョンにアップグレードするには、独自のWebサーバーを使用します:

1. ドキュメントサイトのHTMLファイルをコピーします:

   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. オプション。古いサイトを削除します:

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

トラブルシューティング

検索が機能しない

ローカル検索は、バージョン15.6以降に含まれています。以前のバージョンを使用している場合、検索は機能しません。

詳細については、GitLabドキュメントが使用しているさまざまな種類の検索についてお読みください。

Dockerイメージが見つかりません

Dockerイメージが見つからないというエラーが表示された場合は、正しいレジストリURLを使用しているかどうかを確認してください。

Dockerでホストされているドキュメントサイトのリダイレクトに失敗する

macOS上のDockerでGitLabドキュメントをプレビューすると、ドキュメントへのリダイレクトを妨げるイシューが発生し、 If you are not redirected automatically, click here.というメッセージが表示されることがあります

リダイレクトをエスケープするには、 http://127.0.0.0.1:4000/16.8/のように、URLにバージョン番号を追加する必要があります。