GitLab with pages

helm chart를 만들때 page 기능이 필요해 이를 사용하는 방법에 대하여 정리해보고자 한다.
여기서 사용하려는 버전은 self-managed 즉 private 환경에서 사용하는 방법이라 보면된다.

Have to know

먼저 알아두어야할 것은 다음 3가지 방식으로 사용이 가능하다는것이다.

1. Pages daemom이 GitLab과 동일 서버에서 동작되며 secondary IP를 사용하여 Pages에 접근이 되는 환경
2. Pages daemon이 GitLab과 다른 서버에서 동작
3. Pages daemon이 GitLab과 동일 서버에서 동작되고 IP는 같으나 다른 port로 서비스 된다.
   (이 환경은 Load Balancer를 이용한 proxy환경이 필요하다.)

• 참고 : https://docs.gitlab.com/ee/administration/pages/#overview

또한 별도의 도메인이 필요하다. 기본적으로 GitLab 접근시 gitlab.example.com을 사용중이었다면 pages는 다른 도메인이어야 하며 wildcard DNS record를 사용해야 한다. (또한 기존 GitLab domain과 의존성이 있으면 안되기에 아래 링크를 통한 규칙을 확인하여 domain을 사용하자.)

• 참고 : https://docs.gitlab.com/ee/administration/pages/#prerequisites

추가로 gitlab-runner가 동작되는 환경이어야 한다.
즉, cicd pipeline으로 build deploy가 되는 환경이어야 한다.

• https://www.youtube.com/watch?v=dD8c7WNcc6s

How to set the GitLab page

여기서는 위 3가지 방식중 3번 방식으로 구성을 해볼 예정이다.

먼저 도메인 등록이 필요하다. 다음과 같은 wirdcard 도메인이 등록되어야
userspace 별로 접근이 이루어지는 page 주소가 접근이 가능하다.

실제 동작될 gitlab과 runner를 docker-compose를 이용해서 동작시켜보자.

version: "3.8"

services:
  gitlab:
    container_name : gitlab
    image: 'gitlab/gitlab-ce:14.6.4-ce.0'
    restart: always
    hostname: 'gitlab-server'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.jacobbaek.com'
        gitlab_rails['lfs_enabled'] = true
        gitlab_rails['gitlab_shell_ssh_port'] = 2222
        gitlab_rails['manage_backup_path'] = true
        nginx['ssl_certificate'] = "/etc/cert/ssl/cert.pem"
        nginx['ssl_certificate_key'] = "/etc/cert/ssl/privkey.pem"
        nginx['redirect_http_to_https'] = true
        pages_external_url 'https://gitlabpage.jacobbaek.com'
        pages_nginx['enable'] = true
        pages_nginx['redirect_http_to_https'] = true
        pages_nginx['ssl_certificate'] = "/etc/cert/ssl/cert.pem"
        pages_nginx['ssl_certificate_key'] = "/etc/cert/ssl/privkey.pem"
      GITLAB_ROOT_PASSWORD: password
      GITLAB_TIMEZONE: Asia/Seoul
        # Add any other gitlab.rb configuration here, each on its own line
    ports:
      - '192.168.1.40:80:80'
      - '192.168.1.40:443:443'
      - '192.168.1.40:2222:22'
    volumes:
      - './gitlab/config:/etc/gitlab'
      - './gitlab/logs:/var/log/gitlab'
      - './gitlab/data:/var/opt/gitlab'
      - './gitlab/backups:/var/opt/gitlab/backups'
      - './certs:/etc/cert/ssl'
  gitlab-runner:
    container_name: gitlab-runner
    image: 'gitlab/gitlab-runner:latest'
    restart: always
    volumes:
     - './gitlab-runner/config:/etc/gitlab-runner'
     - '/var/run/docker.sock:/var/run/docker.sock'

참고로 certs 라는 볼륨에 인증서파일들(cert.pem / privkey.pem)은 미리 복사해두어야 한다.

gitlab-runner 등록은 다음 링크를 참조하자.

• https://mr100do.tistory.com/1403

만약 lets encrypt에서 발급받은 인증서를 사용하는 환경(혹은 self-signed 인증서)에서 pages 사용시 인증서에 대해 다음과 같은 에러가 발생될 수 있다.

{"correlation_id":"01FZW9B5GHX6ZBYETA2VGD2XTW","error":"Get \"https://gitlab.jacobbaek.com/api/v4/internal/pages?host=dubaek.gitlabpage.jacobbaek.com\": x509: certificate signed by unknown authority","host":"dubaek.gitlabpage.jacobbaek.com","level":"error","msg":"could not fetch domain information from a source","path":"/usepage","time":"2022-04-05T07:17:07Z"}

다음 링크를 참고하여 ca-certificate update를 수행하자.

• https://docs.gitlab.com/omnibus/settings/ssl.html#other-certificate-authorities

How to use

pages 의 기능을 확인하기 위해 기본 template으로 제공되는 pages로 웹페이지를 출력시킬수 있는 template을 사용해 repository를 생성한다.

template에는 기본적으로 .gitlab-ci.yml 파일이 포함되어 있다.
(해당 파일을 사용하여 웹페이지 출력을 위한 빌드 과정을 수행한다.)

해당 pipeline 에 job이 실행완료가 되면 page에 접근할수 있는 페이지 파일이 만들어지게 된다.
실제 파일은 다음과 같은 경로에 artifacts.zip 파일로 존재한다.
(정확히 해당 압축파일은 CICD pipeline으로 생성된것이고 이를 어떻게 출력하는 파일로 만드는지는 좀더 분석이 필요해보인다.)

root@gitlab-server:/var/opt/gitlab/gitlab-rails/shared/pages/@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce/pages_deployments/4# unzip -l artifacts.zip
Archive:  artifacts.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  04-05-2022 05:47   public/
       54  04-05-2022 05:47   public/.gitignore
      829  04-05-2022 05:47   public/.gitlab-ci.yml
        0  04-05-2022 05:47   public/gitbook/
        0  04-05-2022 05:47   public/gitbook/fonts/
        0  04-05-2022 05:47   public/gitbook/fonts/fontawesome/
   124988  04-05-2022 05:47   public/gitbook/fonts/fontawesome/FontAwesome.otf
    76518  04-05-2022 05:47   public/gitbook/fonts/fontawesome/fontawesome-webfont.eot
   391622  04-05-2022 05:47   public/gitbook/fonts/fontawesome/fontawesome-webfont.svg
   152796  04-05-2022 05:47   public/gitbook/fonts/fontawesome/fontawesome-webfont.ttf
    90412  04-05-2022 05:47   public/gitbook/fonts/fontawesome/fontawesome-webfont.woff
    71896  04-05-2022 05:47   public/gitbook/fonts/fontawesome/fontawesome-webfont.woff2
        0  04-05-2022 05:47   public/gitbook/gitbook-plugin-fontsettings/
     6447  04-05-2022 05:47   public/gitbook/gitbook-plugin-fontsettings/fontsettings.js
     8596  04-05-2022 05:47   public/gitbook/gitbook-plugin-fontsettings/website.css
        0  04-05-2022 05:47   public/gitbook/gitbook-plugin-highlight/
     2865  04-05-2022 05:47   public/gitbook/gitbook-plugin-highlight/ebook.css
    31446  04-05-2022 05:47   public/gitbook/gitbook-plugin-highlight/website.css
        0  04-05-2022 05:47   public/gitbook/gitbook-plugin-lunr/
    15005  04-05-2022 05:47   public/gitbook/gitbook-plugin-lunr/lunr.min.js
     1616  04-05-2022 05:47   public/gitbook/gitbook-plugin-lunr/search-lunr.js
        0  04-05-2022 05:47   public/gitbook/gitbook-plugin-search/
    15005  04-05-2022 05:47   public/gitbook/gitbook-plugin-search/lunr.min.js
     1268  04-05-2022 05:47   public/gitbook/gitbook-plugin-search/search-engine.js
      974  04-05-2022 05:47   public/gitbook/gitbook-plugin-search/search.css
     6368  04-05-2022 05:47   public/gitbook/gitbook-plugin-search/search.js
        0  04-05-2022 05:47   public/gitbook/gitbook-plugin-sharing/
     2875  04-05-2022 05:47   public/gitbook/gitbook-plugin-sharing/buttons.js
   105401  04-05-2022 05:47   public/gitbook/gitbook.js
        0  04-05-2022 05:47   public/gitbook/images/
     4817  04-05-2022 05:47   public/gitbook/images/apple-touch-icon-precomposed-152.png
     4286  04-05-2022 05:47   public/gitbook/images/favicon.ico
    52701  04-05-2022 05:47   public/gitbook/style.css
   113264  04-05-2022 05:47   public/gitbook/theme.js
    11295  04-05-2022 05:47   public/index.html
    23188  04-05-2022 05:47   public/search_index.json
---------                     -------
  1316532                     36 files

CICD pipeline 까지 완료되면 다음 pages 메뉴상에 access pages 가 출력된다.

실제 접근을 해보면 접근할수 있는 페이지가 존재함을 확인할 수 있다.

root@dubaek-gitlabtest:/home/ubuntu# curl -k -I https://dubaek.gitlabpage.jacobbaek.com/usepage
HTTP/2 302
server: nginx
date: Tue, 05 Apr 2022 07:24:46 GMT
content-type: text/html; charset=utf-8
location: //dubaek.gitlabpage.jacobbaek.com/usepage/
vary: Origin
strict-transport-security: max-age=63072000

trouble shooting

pages 접근시 이슈가 있다면 gitlab page가 동작되는 container에서 로그를 확인해볼수 있다.

gitlab-ctl tail gitlab-pages

deploy with source file

참고로 source file을 가져와 직접 binary 형태로 실행하는 방법도 있다.

• https://gitlab.com/gitlab-org/gitlab-pages

참고사이트

• https://docs.gitlab.com/ee/administration/pages