GitLab 제품 문서 호스팅

Tier: Free, Premium, Ultimate Offering: Self-managed

docs.gitlab.com에서 GitLab 제품 문서에 접근할 수 없는 경우, 문서를 직접 호스팅할 수 있습니다.

note
귀하의 인스턴스의 로컬 헬프는 모든 문서를 포함하지 않으며(예: GitLab Runner 또는 GitLab Operator 문서가 포함되지 않음), 검색 가능하거나 탐색할 수 없습니다. 이것은 자체 관리되는 GitLab 인스턴스 내에서 특정 페이지에 대한 직접 링크만 지원하기 위한 것입니다.

문서 자체 호스팅 옵션

GitLab 제품 문서를 호스팅하기 위해 다음을 사용할 수 있습니다:

  • Docker 컨테이너
  • GitLab Pages
  • 자체 웹 서버

다음 예시는 GitLab 16.0을 사용하지만, 귀하의 GitLab 인스턴스에 해당하는 버전을 사용해야 합니다.

Docker로 제품 문서 자체 호스팅하기

문서 웹사이트는 컨테이너 내의 포트 4000에서 제공됩니다. 다음 예제에서는 호스트에서 같은 포트를 노출합니다.

다음 중 하나를 확인하세요:

  • 방화벽에서 포트 4000을 허용하세요.
  • 다른 포트를 사용하세요. 다음 예제에서는 가장 왼쪽의 4000을 다른 포트 번호로 교체합니다.

Docker 컨테이너에서 GitLab 제품 문서 웹사이트를 실행하려면:

  1. GitLab을 호스팅하는 서버 또는 GitLab 인스턴스가 통신할 수 있는 다른 서버에서:

    • 일반 Docker를 사용하는 경우, 다음을 실행하세요:

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

    • Docker compose를 사용하여 GitLab 인스턴스를 호스팅하는 경우, 기존 docker-compose.yaml에 다음을 추가하세요:

      version: '3.6'
services:
  gitlab_docs:
    image: registry.gitlab.com/gitlab-org/gitlab-docs/archives:16.0
    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/archives:16.0
pages:
  script:
    - mkdir public
    - cp -a /usr/share/nginx/html/* public/
  artifacts:
    paths:
    - public

  3. 선택 사항. GitLab Pages 도메인 이름을 설정하세요. GitLab Pages 웹사이트의 유형에 따라 두 가지 옵션이 있습니다:

    웹사이트 유형 기본 도메인 사용자 지정 도메인
    프로젝트 웹사이트 지원되지 않음 지원됨
    사용자 또는 그룹 웹사이트 지원됨 지원됨

  4. 헬프 링크를 새 문서 사이트로 리디렉션하기.

제품 문서를 자체 웹 서버에 호스팅하기

참고:
당신이 생성한 웹사이트는 설치한 GitLab 버전과 일치하는 하위 디렉토리 아래에 호스팅되어야 합니다
(예: 16.0/). Docker 이미지는 기본적으로 이 버전을 사용합니다.

제품 문서 사이트는 정적이므로, 컨테이너 내부의 /usr/share/nginx/html에서 내용을 가져와
원하는 위치에 문서를 호스팅할 수 있습니다.

html 디렉토리는 그대로 제공되어야 하며 다음과 같은 구조를 가집니다:

├── 16.0/
├── index.html

이 예시에서:

  • 16.0/은 문서가 호스팅되는 디렉토리입니다.
  • index.html은 문서가 있는 디렉토리로 리디렉션하는 간단한 HTML 파일입니다. 이 경우, 16.0/입니다.

문서 사이트의 HTML 파일을 추출하려면:

  1. 문서 웹사이트의 HTML 파일을 보유하는 컨테이너를 생성합니다:

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

  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. 도움말 링크를 새 문서 사이트로 리디렉션합니다.

/help 링크를 새 Docs 사이트로 리디렉션하기

로컬 제품 문서 사이트가 실행 중인 후,

도움말 링크를 리디렉션합니다
GitLab 응용 프로그램에서 로컬 사이트로, 문서 URL로 완전한 도메인 이름을 사용합니다.
예를 들어, Docker 방법을 사용한 경우, http://0.0.0.0:4000을 입력합니다.

버전을 추가할 필요는 없습니다. GitLab이 이를 감지하고 필요에 따라 문서 URL 요청에 추가합니다. 예를 들어, GitLab 버전이 16.0인 경우:

  • GitLab 문서 URL은 http://0.0.0.0:4000/16.0/이 됩니다.
  • GitLab의 링크는 <instance_url>/help/administration/settings/help_page#destination-requirements로 표시됩니다.
  • 링크를 선택하면 http://0.0.0.0:4000/16.0/ee/administration/settings/help_page/#destination-requirements로 리디렉션됩니다.

설정을 테스트하기 위해 GitLab에서 Learn more 링크를 선택합니다. 예:

  1. 왼쪽 사이드바에서 아바타를 선택합니다.
  2. Preferences를 선택합니다.
  3. Syntax highlighting theme 섹션에서 Learn more를 선택합니다.

제품 문서를 더 최신 버전으로 업그레이드하기

문서 사이트를 최신 버전으로 업그레이드하려면 새로운 Docker 이미지 태그를 다운로드해야 합니다.

Docker를 사용하여 업그레이드하기

더 최신 버전으로 업그레이드하려면 Docker 사용:

  • Docker를 사용하는 경우:

    1. 실행 중인 컨테이너를 중지합니다:

      sudo docker stop gitlab_docs

    2. 기존 컨테이너를 제거합니다:

      sudo docker rm gitlab_docs

    3. 새로운 이미지를 가져옵니다. 예: 16.0:

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

  • Docker Compose를 사용하는 경우:

    1. docker-compose.yaml에서 버전을 변경합니다. 예: 16.0:

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

  2. 변경 사항을 커밋하고 푸시하면 GitLab Pages가 새로운 문서 사이트 버전을 가져옵니다.

자체 웹 서버를 통한 업그레이드

자체 웹 서버를 사용하여 최신 버전으로 업그레이드하려면:

  1. 문서 사이트의 HTML 파일을 복사합니다:

    docker create -it --name gitlab_docs registry.gitlab.com/gitlab-org/gitlab-docs/archives:16.0
docker cp gitlab_docs:/usr/share/nginx/html /srv/gitlab/
docker rm -f gitlab_docs

  2. 선택사항. 이전 사이트를 제거합니다:

    rm -r /srv/gitlab/html/16.0/

문제 해결

검색이 작동하지 않음

로컬 검색은 15.6버전 및 이후 버전에 포함되어 있습니다. 이전 버전을 사용하고 있다면 검색이 작동하지 않습니다.

이 이미지는 컨테이너 레지스트리의 별도 리포지토리에 푸시됩니다.

로컬 검색을 원하시면 이름에 archives가 포함된 Docker 이미지를 사용해야 합니다, 예를 들어:

registry.gitlab.com/gitlab-org/gitlab-docs/archives:16.0

자세한 정보는 GitLab Docs에서 사용하고 있는 다양한 검색 유형에 대해 읽어보세요.

Docker 이미지가 발견되지 않음

15.5버전 및 이전 버전을 사용하고 있다면 Docker 이미지 이름에서 /archives를 제거해야 합니다.

예를 들어:

registry.gitlab.com/gitlab-org/gitlab-docs:15.5