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

컨테이너 레지스트리 URL#

원하는 컨테이너 이미지에 대한 URL은 필요한 GitLab 문서 버전에 따라 다릅니다. 다음 섹션에서 사용할 URL에 대한 가이드로 다음 표를 참조하세요.

문서 셀프 호스팅 옵션#

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

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

다음 예제는 GitLab 17.8을 사용하지만, 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/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: 'docs.gitlab.example.com'
         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 설치와 동일한 버전인지 확인합니다:

   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 Pages 웹사이트 유형에 따라 두 가지 옵션이 있습니다:

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

4. 새 문서 사이트로 도움말 링크를 리디렉션합니다.

자체 웹 서버에서 제품 문서 셀프 호스팅#

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

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

├── 17.8/
├── index.html

이 예제에서:

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

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

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

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

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

새 Docs 사이트로 /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에서 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. 새 이미지를 가져옵니다. 예를 들어 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: 'docs.gitlab.example.com'
         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가 새 문서 사이트 버전을 가져옵니다.

자체 웹 서버를 사용하여 업그레이드#

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

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 Docs에서 사용 중인 다양한 유형의 검색을 참조하세요.

Docker 이미지를 찾을 수 없음#

Docker 이미지를 찾을 수 없다는 오류가 발생하면 올바른 레지스트리 URL을 사용하고 있는지 확인합니다.

Docker 호스팅 문서 사이트가 리디렉션에 실패#

macOS의 Docker에서 GitLab 문서를 미리 볼 때 문서로의 리디렉션을 방해하는 문제가 발생하여 If you are not redirected automatically, click here. 메시지가 표시될 수 있습니다.

리디렉션을 피하려면 http://127.0.0.1:4000/16.8/과 같이 URL에 버전 번호를 추가해야 합니다.