PlantUML & GitLab
GitLab 8.16 で導入されました。
PlantUMLインテグレーションを有効にしてGitLabで設定すると、スニペット、Wiki、リポジトリで作成されたAsciiDocやMarkdownドキュメントでシンプルなダイアグラムを作成することができます。
PlantUMLサーバー
GitLabでPlantUMLを有効にする前に、ダイアグラムを生成するPlantUMLサーバーをセットアップする必要があります。
Docker
Dockerを使えば、このようにコンテナを実行するだけです:
docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat
PlantUML URLは、コンテナを実行しているサーバのホスト名になります。
GitLab を Docker で実行する場合は、PlantUML コンテナにアクセスする必要があります。 これを実現する最も簡単な方法は、Docker Composerを使うことです。
簡単なdocker-compose.yml
:
version: "3"
services:
gitlab:
image: 'gitlab/gitlab-ce:12.2.5-ce.0'
environment:
GITLAB_OMNIBUS_CONFIG: |
nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n proxy_cache off; \n proxy_pass http://plantuml:8080/; \n}\n"
plantuml:
image: 'plantuml/plantuml-server:tomcat'
container_name: plantuml
このシナリオでは、PlantUMLはGitLabのURLhttp://plantuml:8080/
からアクセスできるようになります。
Debian/Ubuntu
Debian/Ubuntuディストリビューションでは、あなた自身のPlantUMLサーバのインストールと設定は、Tomcatを使って簡単にできます。
まず、ソースコードからplantuml.war
ファイルを作成する必要があります:
sudo apt-get install graphviz openjdk-8-jdk git-core maven
git clone https://github.com/plantuml/plantuml-server.git
cd plantuml-server
mvn package
上記の一連のコマンドは、Tomcatを使用してデプロイできるWARファイルを生成します:
sudo apt-get install tomcat8
sudo cp target/plantuml.war /var/lib/tomcat8/webapps/plantuml.war
sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war
sudo service tomcat8 restart
Tomcat サービスが再起動すると、PlantUML サービスは準備が整い、ポート 8080 でリクエストを待ち受けます:
http://localhost:8080/plantuml
これらのデフォルトは、/etc/tomcat8/server.xml
ファイルを編集することで変更できます。
デフォルトのURLは、Dockerベースのイメージを使用する場合とは異なり、相対パスなしでURLのルートでサービスが利用可能であることに注意してください。 それに応じて、以下の設定を調整してください。
GitLab のカスタム設定を使ってローカルの PlantUML にアクセスできるようにする方法
PlantUML サーバは、サーバ上でローカルに実行されるため、外部からはアクセスでき ません。 そのため、外部の PlantUML 呼び出しをキャッチし、ローカルサーバに リダイレクトする必要があります。
このアイデアは、https://gitlab.example.com/-/plantuml/
への各コールを、セットアップに応じて、ローカルの PlantUML サーバhttp://plantuml:8080/
またはhttp://localhost:8080/plantuml/
にリダイレクトすることです。
リダイレクトを有効にするには、/etc/gitlab/gitlab.rb
に以下の行を追加します:
# Docker deployment
nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n proxy_cache off; \n proxy_pass http://plantuml:8080/; \n}\n"
# Built from source
nginx['custom_gitlab_server_config'] = "location /-/plantuml { \n rewrite ^/-/(plantuml.*) /$1 break;\n proxy_cache off; \n proxy_pass http://localhost:8080/plantuml; \n}\n"
変更をアクティブにするには、以下のコマンドを実行します:
sudo gitlab-ctl reconfigure
セキュリティ
PlantUMLには、ネットワーク・リソースをフェッチする機能があります。
@startuml
start
' ...
!include http://localhost/
stop;
@enduml
PlantUML サーバをセルフホストする場合、それを隔離するためにネットワーク 管理を行う必要があります。
GitLab
PlantUMLインテグレーションを有効にするには、管理者エリアの設定から行う必要があります。 これを行うには、管理者アカウントでログインし、以下を実行してください:
- GitLabで、Admin Area > Settings >Integrationに進みます。
- PlantUMLセクションを展開します。
- PlantUML を有効にするチェックボックスをオンにします。
- PlantUML インスタンスを
https://gitlab.example.com/-/plantuml/
として設定します。
deflate
圧縮を有効にするためにPLANTUML_ENCODING
環境変数を設定します。 Omnibus では、これは/etc/gitlab.rb
で設定できます:gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' }
GitLab 13.1以降では、PlantUMLインテグレーションは異なるエンコーディング・タイプを区別するためにURLのヘッダープレフィックスを要求するようになりました。
ダイアグラムの作成
PlantUMLインテグレーションを有効にして設定すると、区切りブロックを使用して、AsciiDocスニペット、Wiki、リポジトリにダイアグラムを追加することができます:
-
マークダウン
```plantuml Bob -> Alice : hello Alice -> Bob : hi ```
-
アスキードック
[plantuml, format="png", id="myDiagram", width="200px"] ---- Bob->Alice : hello Alice -> Bob : hi ----
-
再構造化テキスト
.. plantuml:: :caption: Caption with **bold** and *italic* Bob -> Alice: hello Alice -> Bob: hi
sphinxcontrib-plantuml
との互換性を保つためにuml::
ディレクティブを使うこともできますが、現在のところcaption
オプションしかサポートしていないことに注意してください。
上記のブロックは、ソースが PlantUML インスタンスを指す HTML イメージ・タグに変換されます。 PlantUML サーバが正しく設定されていれば、ブロックの代わりに美しいダイアグラムがレンダリングされるはずです:
ブロック内部では、シーケンス図、ユースケース図、クラス図、アクティビティ図、コンポーネント図、状態図、オブジェクト図など、PlantUML でサポートされている図を追加することができます。 PlantUML ダイアグラムの区切り記号@startuml
/@enduml
は、AsciiDocplantuml
ブロックで置き換えられるため、使用する必要はありません。
AsciiDoc ブロック定義にはいくつかのパラメータを追加することができます:
-
format
png
デフォルトはsvg
.svg
png
-
id
ダイアグラムの HTML タグに追加される CSS ID。 -
width
imageタグにWidth属性を追加しました。 -
height
画像タグに高さ属性を追加しました。
Markdownはパラメータをサポートしておらず、常にPNGフォーマットを使用します。