GitLab 제품 설명서 호스팅
만약 docs.gitlab.com
에서 GitLab 제품 설명서에 접근할 수 없는 경우, 대신 스스로 설명서를 호스팅할 수 있습니다.
설명서 자체 호스팅 옵션
GitLab 제품 설명서를 호스팅하기 위해 다음을 사용할 수 있습니다:
- Docker 컨테이너
- GitLab 페이지
- 자체 웹 서버
다음 예제에서는 GitLab 16.0을 사용하지만, 귀하의 GitLab 인스턴스와 일치하는 버전을 사용해야 합니다.
Docker를 사용한 제품 설명서 자체 호스팅
다음 예에서는 설명서 웹사이트가 컨테이너 내의 포트 4000
에서 제공됩니다. 다음 예에서는 호스트의 동일한 포트에서 이를 노출합니다.
반드시 다음 중 하나를 수행하세요:
- 방화벽에서 포트
4000
을 허용하십시오. - 다른 포트를 사용하십시오. 다음 예에서 왼쪽의
4000
을 다른 포트 번호로 대체하십시오.
Docker 컨테이너에서 GitLab 제품 설명서 웹사이트를 실행하려면:
-
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
-
-
http://0.0.0.0:4000
을 방문하여 설명서 웹사이트를 확인하고 작동 여부를 확인하십시오. - 도움말 링크를 새 설명서 사이트로 리디렉션하십시오.
GitLab 페이지를 사용한 제품 설명서 자체 호스팅
GitLab 페이지를 사용하여 GitLab 제품 설명서를 호스팅할 수 있습니다.
전제 조건:
- Pages 사이트 URL이 서브폴더를 사용하지 않도록 확인하십시오. 사이트가 사전 컴파일된 방식 때문에 CSS 및 JavaScript 파일은 메인 도메인 또는 서브도메인을 기준으로 상대적입니다. 예를 들어
https://example.com/docs/
와 같은 URL은 지원되지 않습니다.
GitLab 페이지로 제품 설명서 사이트를 호스팅하려면:
- 빈 프로젝트 만들기.
-
.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
-
선택 사항. GitLab Pages 도메인 이름 설정. GitLab Pages 웹사이트 유형에 따라 두 가지 옵션이 있습니다:
웹사이트 유형 기본 도메인 사용자 정의 도메인 프로젝트 웹사이트 지원되지 않음 지원됨 사용자 또는 그룹 웹사이트 지원됨 지원됨 - 도움말 링크를 새 설명서 사이트로 리디렉션하십시오.
자체 웹 서버에 제품 설명서 자체 호스팅
16.0/
).
Docker 이미지는 기본적으로 이 버전을 사용합니다.제품 설명서 사이트가 정적이므로 컨테이너 내의 /usr/share/nginx/html
내용을 가져와서 원하는 곳에 설명서를 호스팅할 수 있습니다.
html
디렉토리는 다음과 같은 구조를 갖습니다:
├── 16.0/
├── index.html
이 예에서:
-
16.0/
은 설명서가 호스팅되는 디렉토리입니다. -
index.html
은 간단한 HTML 파일로, 설명서가 포함된 디렉토리로 리디렉션합니다. 이 경우16.0/
.
설명서 사이트의 HTML 파일을 추출하려면:
-
설명서 웹사이트의 HTML 파일을 보관하는 컨테이너를 생성하십시오:
docker create -it --name gitlab_docs registry.gitlab.com/gitlab-org/gitlab-docs/archives:16.0
-
웹사이트를
/srv/gitlab/
하위에 복사하십시오:docker cp gitlab-docs:/usr/share/nginx/html /srv/gitlab/
이제
/srv/gitlab/html/
디렉토리에 설명서 웹사이트가 보관됩니다. -
컨테이너를 삭제하십시오:
docker rm -f gitlab_docs
- 웹 서버를 방향으로 설정하여
/srv/gitlab/html/
내용을 제공하십시오. - 도움말 링크를 새 설명서 사이트로 리디렉션하십시오.
/help
링크를 새 문서 사이트로 리디렉션하기
로컬 제품 설명서 사이트가 실행된 후에는
도큐먼트 URL로 완전히 정규화된 도메인 이름을 사용하여 GitLab 응용 프로그램에서 도움말 링크를
로컬 사이트로 리디렉션합니다. 예를 들어, 도커 방법을 사용했다면 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에서 자세히 알아보기 링크를 선택하세요. 예를 들어:
- 왼쪽 사이드바에서 아바타를 선택합니다.
- 환경 설정 선택합니다.
- 구문 강조 테마 섹션에서 자세히 알아보기를 선택합니다.
제품 설명서를 최신 버전으로 업그레이드하기
제품 설명서 사이트를 최신 버전으로 업그레이드하려면 새로운 Docker 이미지 태그를 다운로드해야 합니다.
Docker를 사용하여 업그레이드하기
도커를 사용하여 나중 버전으로 업그레이드하려면:
-
도커를 사용하는 경우:
-
동작 중인 컨테이너를 중지합니다:
sudo docker stop gitlab_docs
-
기존 컨테이너를 제거합니다:
sudo docker rm gitlab_docs
-
새 이미지를 가져옵니다. 예를 들어, 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를 사용하는 경우:
-
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'
-
변경 사항을 가져옵니다:
docker-compose up -d
-
GitLab Pages를 사용하여 업그레이드하기
GitLab Pages를 사용하여 나중 버전으로 업그레이드하려면:
-
기존
.gitlab-ci.yml
파일을 편집하고image
버전 번호를 바꿉니다:image: registry.gitlab.com/gitlab-org/gitlab-docs/archives:16.0
-
변경 사항을 커밋하고 푸시하면 GitLab Pages가 새로운 설명서 사이트 버전을 가져옵니다.
자체 웹 서버를 사용하여 업그레이드하기
자체 웹 서버를 사용하여 나중 버전으로 업그레이드하려면:
-
설명서 사이트의 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
-
선택 사항. 이전 사이트를 제거합니다:
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