在自架 GitLab 使用 Kroki 來繪圖


自己架設的 GitLab Server 上,管理者其實有相當多的設定可以調整,也有相當多的外部服務可以整合來一起用。

其中一類,就是讓使用者可以在 Markdown 的文件(包含 wiki)中,使用特殊的語法來繪圖。

比如說,當單純用文字比較難說明的時候,就可以透過簡單的語法來描述,系統會自動把這些描述轉換成圖像,幫助其他人來了解。

GitLab 在這部分,提供了 PlantUML(官網) 和 Kroki!(官網) 這兩套服務可以整合,讓使用者可以自行設定要使用的服務網址。

像右圖就是一個用 PlantUML 的語法畫出來的圖;要畫這樣一張圖,他的語法如下:

```plantuml
package "Some Group" {
  HTTP - [First Component]
  [Another Component]
}

node "Other Groups" {
  FTP - [Second Component]
  [First Component] --> FTP
}

cloud {
  [Example 1]
}

database "MySql" {
  folder "This is my folder" {
    [Folder 3]
  }
  frame "Foo" {
    [Frame 4]
  }
}

[Another Component] --> [Example 1]
[Example 1] --> [Folder 3]
[Folder 3] --> [Frame 4]
```

基本上,還算是滿簡單的~

而實際上,光是 PlantUML 能提供的圖形種類就非常多了,應該是能滿足大部分的需求。


GitLab 中的基本設定

GitLab 最早只有支援 PlantUML,Kroki! 是後來才支援的;而實際上,Kroki 比較像是同類型的服務集合、其中也包含了 PlantUML 的功能(Kroki 官網),所以 Heresy 現在就只有使用 Kroki! 了。

而要在 GitLab 中提供這樣的功能,需要使用 GitLab 的系統管理者帳號,進到 Admin Area 後,點選左邊的 Settings、General 就可以找到這部分的設定了。

以 Kroki! 來說,這邊只需要把「Enable Kroki」勾起來,然後在「Kroki URL」輸入自己架設的 Kroki 網址就可以了。Heresy 這邊是設定成「https://gitlab.heresy.tw:8081」。

如果不想架設,也可以直接使用 Kroki 官方提供的服務,他的網址就是「https://kroki.io」。


架設 Docker 版 Kroki Server

不過考量 Heresy 這邊的網站是對內服務的,要畫的圖的資訊其實也不適合丟給開放式的服務來畫,所以這邊就決定自己架設了~

由於現在有 Docker 這種東西,所以要架設一個服務起來很簡單,只要使用下面的指令就可以了:

docker run -d --restart always --name kroki -p 8000:8000 yuzutech/kroki

如此一來,在 8000 port 就會有一個 kroki 的服務在執行了。

不過這樣跑起來其實還不能用。因為 Kroki 只有提供 http 的版本,沒有提供 https 版…所以如果要搭配 https 版的 GitLab 的話,還需要另外想辦法轉換成 https 才行…


使用 NGINX 做反向代理加上 https

為了要讓 Kroki 可以以 https 的形式服務,Heresy 也找了一些資料,但是看來官方提供的 Docker Image 並沒辦法做到這件事;而官方的建議,是透過前面再加上一層 NGINX 來解決。

目前 Heresy 的做法,是用 Docker 跑一個 NGINX(官網),來做為反向代理(reverse proxy、維基百科),讓外部透過他來連線到 Kroki 提供的 http 服務。

這邊的 Docker 命令如下:

docker run -d --restart always --name kroki_proxy \
    -p 8081:443 --link kroki \
    -v /proxy_conf/default.conf:/etc/nginx/conf.d/default.conf \
    -v /proxy_conf/ssl/:/myssl/ \
    nginx

這邊是把 8081 port 對應到 443 port,讓外面透過 8081 來連線(443 已經被 GitLab 用了) ;而為了讓他可以連到 Kroki,這邊也加上「–link kroki」。

再來,就是把必要的檔案對應進去了。

其中,default.conf 的內容如下:

server {
    listen       443 ssl;
    server_name  localhost;
    ssl_certificate     /myssl/server.crt;
    ssl_certificate_key /myssl/server.key;

    #access_log  /var/log/nginx/host.access.log  main;

    location / {
        proxy_pass http://kroki:8000;
    }

    #error_page  404              /404.html;

    # redirect server error pages to the static page /50x.html
    #
    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

這邊重點一個是 SSL 的憑證,他是使用 /myssl 下的檔案,是由外部的  /proxy_conf/ssl 對應進去的,處理方法和 GitLab Server 的一樣。

location 的部分,則是告訴他要連到「http://kroki:8000/」(官方文件);這邊可以直接用 kroki 當網站名稱,是因為前面的 Docker 指令有加上「–link kroki」的關係。

如此一來,就可以透過 8081 port、也就是 https://gitlab.heresy.tw:8081 來存取 https 的 kroki 服務了!


修正 GitLab 不允許同一台 localhost 服務的設定

理論上上面的步驟就夠了,但是如果 Kroki/NGINX 的服務和 GitLab 在同一台電腦上,網址相同的話,這邊應該在第一步就會踩到 GitLab 不允許要求 localhost 的錯誤。

他的錯誤訊息是:「Kroki url is not valid. Requests to localhost are not allowed」。

而解決問題呢,是到 Admin Area 的 Settings 中,找到 Network 下的「Outbound requests」;然後把兩個 allow request 都打勾,並在下面輸入 Kroki 的網址。

這樣應該就可以完成設定了!


另外,這邊其實還可以另外裝 BlockDiag、BPMN、Excalidraw 等服務、然後透過 Kroki 來使用;不過這邊 Heresy 就還沒有特別去搞了。

這部分可以參考官方文件,另外在 GitLab 也要另外勾選。

發表迴響

在下方填入你的資料或按右方圖示以社群網站登入:

WordPress.com 標誌

您的留言將使用 WordPress.com 帳號。 登出 /  變更 )

Google photo

您的留言將使用 Google 帳號。 登出 /  變更 )

Twitter picture

您的留言將使用 Twitter 帳號。 登出 /  變更 )

Facebook照片

您的留言將使用 Facebook 帳號。 登出 /  變更 )

連結到 %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.