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/として設定します。

注意:v1.2020.9 以上を実行している PlantUML サーバを使用している場合 (例えばplantuml.com)、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 ブロック定義にはいくつかのパラメータを追加することができます：

formatpng デフォルトはsvg. svg png
idダイアグラムの HTML タグに追加される CSS ID。
widthimageタグにWidth属性を追加しました。
height画像タグに高さ属性を追加しました。

Markdownはパラメータをサポートしておらず、常にPNGフォーマットを使用します。

クリエーションラインについて

私たちクリエーションラインは、日本で最も古く2017年にGitLabサービスの提供を開始し、2022年には「Asia-Pacific Partner of the Year」も獲得。GitLabのサブスクリプション販売やテクニカルサポートだけでなく、GitLab Enterpriseの導入支援やGitLabトレーニングなど多様なサービスを提供し、エンタープライズを中心に豊富な実績を誇ります。GitLabに関するお悩みがありましたら、ぜひお気軽にお問い合わせください。日本で唯一、3度にわたるMVPを獲得したGitLabエバンジェリストをはじめとしたエキスパートチームが、あなたの課題解決をご支援します。