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フォーマットを使用します。