在單一網域名的環境啟用 GitLab Pages

GitLab Pages 是一個透過 GitLab CI/CD 的流程、來建立靜態網頁服務的一項功能。透過這樣的功能，開發者可以透過 CI/CD 的流程、自動更新／佈署網頁，雖然網頁的內容僅限於靜態網頁（不能使用 PHP 或 ASP 這類的動態功能），但是在某些情境下，其實也很夠用了。

像是 Heresy 之前也透過這種機制、搭配定時 pipeline 弄了個遊戲公告的自動擷取、比對系統出來（參考）。

而在以往的架構下，如果 GitLab 服務的網域是 gitlab.example.com 的情況下，需要另外一個 GitLab Pages 的網域是 *.example.io；而一個專案 /heresy/test_project 的 GitLab Pages 網址就會變成是 heresy.example.io/test_project。

設計成這個形式的其實不只是 GitLab、GitHub 也是同樣的設計。

而現在如果要在沒有 wildcard DNS 的狀況下建立 GitLab Pages 服務的話，就變成可以給 GitLab Pages 單一個網域、比如說是 pages.example.com；在這個狀況下，專案 /heresy/test_project 的 GitLab Pages 網址就會變成是 gitlab.example.com/heresy/test_project。

這樣的網址雖然沒有本來的簡潔，但是對於沒有網域控制權限的人來說，至少算是個可以動的方案了。

想要確認自己架設的 GitLab 服務的 GitLab Pages 的狀態的話，可以到 GitLab 的管理區域（Admin Area）裡面，在「Overview」、「Dashboard」裡面可以看到類似下面的畫面：

上圖「Features」裡面 GitLab Pages 右邊打勾的狀況就是已經啟用的狀態，否則應該會像「Sign Up」一樣、右邊是個電源的圖示；而點選那個問號的圖示、則可進去看到目前 GitLab Pages 的相關設定。

而右邊的 Components 裡面也可以看到 GitLab Pages 服務的版本，如果沒有啟用的話會根本看不到 GitLab Pages 這一項。

開始前，先講一下 Heresy 這邊的測試環境：

• Ubuntu VM：有一個實體 IP 與對應的 domain（假設是 gitlab.example.com）
• 使用 gitlab/gitlab-ce:latest 這個官方提供的 GitLab-CE Docker 映像檔

執行的命令是：

docker run -d --name gitlab \
  -p 80:80 -p 443:443 -p 24800:24800 \
  -v /mnt/gitlab/config:/etc/gitlab \
  -v /mnt/gitlab/logs:/var/log/gitlab \
  -v /mnt/gitlab/data:/var/opt/gitlab \
  gitlab/gitlab-ce:latest

基本上就是本來只有使用 80 和 443 兩個 port、24800 是預留給 GitLab Pages 的；然後資料、設定、紀錄則是都放在 /mnt/gitlab 目錄下。

這邊基本上是先透過這樣還建立一個沒有開啟 GitLab Pages 的 GitLab 服務後、再做後續的修改；會這樣做是要模擬實際運作的機器地修改方法。

官方的《GitLab Pages administration》這份文件（連結）算是提供了滿完整的 GitLab Pages 的設定說明；其中「without wildcard DNS」相關的部分，就是這次新增的實驗性功能。

不過，或許是因為可能的情境太多了吧，個人是覺得這份文件不算好閱讀、也不是很容易釐清自己需要的設定…像是 Heresy 總覺得自己最後的狀況其實根本沒有完全滿足他的 prerequisites。 o_O

總之，基本上 GitLab 的 Docker 版本裡面預設已經包含了 GitLab Pages 的功能，不過預設是沒有開啟的。

而在測試了一陣子後，發現要在單一 IP、單一網域的情況下、同時跑 GitLab 和 GitLab Pages 的服務，應該是參考《Pages domain without wildcard DNS》（連結）的設定就可以了。gitlab.rb 這個檔案的內容可以修改成：

external_url 'https://gitlab.example.com/'
pages_external_url "gitlab.example.com:24800/"
gitlab_pages['namespace_in_path'] = true
pages_nginx['enable'] = true

這邊是最低限度的設定檔，黃色的部分是針對 GitLab Pages 新增的，如果本來還有其他內容基本上是不會影響。

這邊是讓 GitLab Pages 去使用 24800 這個 port，有需要的話也可以自己修改；不過要注意的是，由於 GitLab Docker 內部的服務相當多，如果 port 沒選好有可能會因為和其他內部服務的 port 衝突而無法正常啟動。

修改好設定檔後，只要要求 GitLab 重新進行組態設定就可以了。以這邊使用 Docker 版的話，最簡單就是直接重新啟動 GitLab 這個容器，或是透過「docker exec gitlab gitlab-ctl reconfigure」來進行。

這樣一來，GitLab 本來的服務就會是「https://gitlab.example.com/」、而 GitLab Pages 則會是「https://gitlab.example.com:24800/」；不過如果直接連到 GitLab Pages 的網址會是 ngnix 的 404 訊息就是了。

理論上，上面的設定就可以完成 GitLab Pages 的設定了；而想要確認的話，也可以參考前面「確認 GitLab Pages 的狀態」的內容，到管理區域確認。

一切順利的話，接下來還需要另外找電腦來當作 GitLab Runner 來處理 CI/CD 的工作，這樣才能完成 pages 的發布。不過這部分不是這邊的重點，所以就先不講了。

至於要發布 GitLab Pages 的專案，基本上就是要在專案的根目錄下、建立 .gitlab-ci.yml 這個 CI/CD 的設定檔，然後裡面需要有一個名為「pages」的工作，並將最後的網頁內容都放到 public 這個資料夾下、作為 artifact 提交給 GitLab。

這邊也可以直接參考官方的範例或範本來建立專案，或是參考 Heresy 放在 GitLab.com 上的簡單範例（連結）；而它的結果會是：https://kheresy.gitlab.io/page_test/。

不過要注意的是，目前 GitLab 預設似乎是會開啟「Use unique domain」這個選項，所以預設的 Pages URL 會被加上一串機碼、應該是怕被試出來？這邊的設定是在專案裡面的「Deploy」裡面的「Pages」：

可以看到，這邊 Pages 的網址是「https://page-test-kheresy-1a572a734d727a35d6e0ab6bc4b34639eceed09cde392.gitlab.io」這樣難以記憶的形式。

這邊只要取消「Use unique domain」、按下「Save Changes」後，他就會變成「https://kheresy.gitlab.io/page_test/」這樣的形式了；這部分要不要切換基本上也是看個人需求了。

回過來看自己架設的 GitLab 的狀況。目前這樣的設定，確實可以讓 GitLab 和 GitLab Pages 都可以運作，但是實際上還是有問題的。

比如說 root 帳號的 page_test 這個專案來說，他的 GitLab Pages 的 URL 在系統上會告知是「http://gitlab.example.com:24800/root/page_test」；但是實際上進到這個網址會被重新導向到

http://gitlab.example.com:24800/root//root.gitlab.example.com:24800/page_test/

這樣一個奇怪的網址，然後會出現 GitLab 的 404 錯誤頁面。

不過要解決也還算簡單，只要自己在網址最後加一個「/」、變成「http://gitlab.example.com:24800/root/page_test/」就可以了；所以基本上算是可以用的。

這部分在官方的 feedback 也有人提交類似的問題，而 Heresy 自己也把自己的狀況回報了，官方目前也認定這是已知問題、而原因是目前重新導向的不支援 URL 有包含 port。

所以要解決這個問題，除了等官方更新外，大概就是準備另一個 domain name 給 Pages 用、然後不要用特定的 port 就可以了。
實際上 Heresy 也試過，把 GitLab 本來的服務加上 port、Pages 不要使用特殊 port 是可以正常運作的。

如果要開啟存取控制（access control）、允許每個專案各自設定對應的 pages 是否要開放（官方文件）的話，在 gitlab.rb 這個檔案裡面則還需要加入兩行額外的設定：

gitlab_pages['access_control'] = true
gitlab_pages['auth_redirect_uri'] = 'https://gitlab.example.com:24800/projects/auth'

在開啟存取控制後，在開啟  GitLab Pages 的時候會透過 GitLab 的 OAuth 來做認證、確認是否有權限讀取網頁，讓這個服務可以更安全。

而在每個使用者第一次使用的時候，會出現類似下面的畫面，要求使用者授權 GitLab Pages 所要求的授權。

這邊要注意的是，如果沒有加入 gitlab_pages['auth_redirect_uri'] 這個設定的話，他預設是會去透過「projects.gitlab.example.com」這個網站來要求授權，所以會變成沒辦法完成。

不過，在開啟存取控制後，在需要確認授權的時候，似乎還是可能會在取得授權過後、把網址重新導向到啟用 gitlab_pages['namespace_in_path'] 前的網址、也就是 https://root.gitlab.example.com:24800/page_test/ 這樣的形式。

而這樣當然就沒辦法正常開啟了…不過，在這樣的狀況下，回頭用正確的網址重新開啟似乎還是可以的。

不過呢，pages 的 URL 結尾沒有「/」的時候會重新導向錯誤的狀況看來還是和前面提到的一樣會錯就是了。 XD

整體來說，看來目前存取控制的狀況雖然和前面一樣、是重新導向的問題，但是問題應該是更多，可能先不要開起會稍微好一點吧？

另外，在第一次開啟存取控制功能的時候，GitLab 會自動把 GitLab Pages 加入成為一個附加的 OAuth 應用程式，這部分可以在管理區域裡面的「Applications」裡面看到。

而如果之後有修改 GitLab Pages 的相關設定、導致 GitLab Pages 服務的網址有變化的話（例如改 port、或是修改這邊的 auth_redirect_uri），要記得回來修改這邊的設定，否則在試著取得使用者授權的時候，會出現「The redirect URI included is not valid.」的錯誤。