プラントUML

PlantUMLインテグレーションを使うと、スニペット、Wiki、リポジトリにダイアグラムを作成することができます。このインテグレーションは、すべてのSaaSユーザーに対してGitLab.com上で有効になっており、追加の設定は必要ありません。

セルフマネージドインスタンスでインテグレーションを設定するには、PlantUMLサーバーを設定する必要があります。

インテグレーションが完了すると、PlantUML はplantuml ブロックを、ソースが PlantUML インスタンスを指している HTML イメージタグに変換します。PlantUML ダイアグラムの区切り文字@startuml/@enduml は、plantuml ブロックに置き換えられるため、必要ありません:

  • 拡張子が.mdMarkdownファイル:

     ```plantuml
     Bob -> Alice : hello
     Alice -> Bob : hi
     ```
    

    その他の拡張子については、languages.yaml ファイルをレビューしてください。

  • 拡張子が.asciidoc,.adoc, または.ascAsciiDocファイル:

     [plantuml, format="png", id="myDiagram", width="200px"]
     ----
     Bob->Alice : hello
     Alice -> Bob : hi
     ----
    
  • reStructuredText

     .. plantuml::
        :caption: Caption with **bold** and *italic*
       
        Bob -> Alice: hello
        Alice -> Bob: hi
    

    sphinxcontrib-plantumlとの互換性のためにuml:: ディレクティブを使うこともできますが、GitLab はcaption オプションしかサポートしていません。

PlantUML サーバーが正しく設定されていれば、これらの例はコードブロックの代わりにダイアグラムをレンダリングするはずです:

ブロックの中には、PlantUML がサポートしているダイアグラムを追加することができます:

ブロック定義にパラメータを追加できます:

  • id:ダイアグラムの HTML タグに追加される CSS ID。
  • width:imageタグに追加されたWidth属性。
  • height:imageタグにheight属性を追加。

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

PlantUMLサーバの設定

GitLabでPlantUMLを有効にする前に、ダイアグラムを生成するPlantUMLサーバーを設定しましょう:

Docker

PlantUML コンテナを Docker で実行するには、以下のコマンドを実行します:

docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat

PlantUML URLは、コンテナを実行するサーバーのホスト名です。

DockerでGitLabを実行する場合、GitLabはPlantUMLコンテナにアクセスできなければなりません。そのためには、Docker Composerを使います。この基本的なdocker-compose.yml ファイルでは、PlantUML は URLhttp://plantuml:8080/ で GitLab にアクセスできます:

version: "3"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:12.2.5-ee.0'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n    rewrite ^/-/plantuml/(.*) /$1 break;\n proxy_cache off; \n    proxy_pass  http://plantuml:8080/; \n}\n"

  plantuml:
    image: 'plantuml/plantuml-server:tomcat'
    container_name: plantuml

ローカルPlantUMLアクセスの設定

PlantUML サーバは、あなたのサーバ上でローカルに実行されますので、 デフォルトでは外部からのアクセスはできません。サーバは、https://gitlab.example.com/-/plantuml/ への外部 PlantUML 呼び出しをキャッチし、それらをローカルの PlantUML サーバにリダイレクトする必要があります。セットアップに応じて、URL は以下のいずれかになります:

  • http://plantuml:8080/
  • http://localhost:8080/plantuml/

GitLab を TLS で実行している場合、PlantUML は安全でない HTTP プロトコルを使うので、このリダイレクトを設定しなければなりません。Google Chrome 86+のような新しいブラウザは、HTTPSで提供されるページに安全でないHTTPリソースを読み込みません。

このリダイレクトを有効にするには

  1. /etc/gitlab/gitlab.rb に以下の行を追加してください:

    # Docker deployment
    nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n  rewrite ^/-/plantuml/(.*) /$1 break;\n  proxy_cache off; \n    proxy_pass  http://plantuml:8080/; \n}\n"
    
  2. 変更をアクティビティにするには、以下のコマンドを実行します:

    sudo gitlab-ctl reconfigure
    

Debian/Ubuntu

Debian/Ubuntu ディストリビューションでは、Tomcat や Jetty を使って PlantUML サーバをインストール・設定することができます。

前提条件:

  • JRE/JDKバージョン11以降。
  • (推奨)Jetty バージョン 11 以降。
  • (推奨)Tomcatバージョン10以降

インストール

PlantUMLはTomcat 10以上のインストールを推奨します。このページの範囲は、基本的なTomcatサーバのセットアップのみを含みます。本番環境でのより多くの設定については、Tomcatドキュメントを参照してください。

  1. JDK/JRE 11をインストールしてください:

    sudo apt update
    sudo apt-get install graphviz default-jdk git-core
    
  2. Tomcatのユーザーを追加します:

    sudo useradd -m -d /opt/tomcat -U -s /bin/false tomcat
    
  3. Tomcat 10のインストールと設定:

    wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.9/bin/apache-tomcat-10.1.9.tar.gz -P /tmp
    sudo tar xzvf /tmp/apache-tomcat-10*tar.gz -C /opt/tomcat --strip-components=1
    sudo chown -R tomcat:tomcat /opt/tomcat/
    sudo chmod -R u+x /opt/tomcat/bin
    
  4. systemdサービスを作成します。/etc/systemd/system/tomcat.service

    [Unit]
    Description=Tomcat
    After=network.target
       
    [Service]
    Type=forking
       
    User=tomcat
    Group=tomcat
       
    Environment="JAVA_HOME=/usr/lib/jvm/java-1.11.0-openjdk-amd64"
    Environment="JAVA_OPTS=-Djava.security.egd=file:///dev/urandom"
    Environment="CATALINA_BASE=/opt/tomcat"
    Environment="CATALINA_HOME=/opt/tomcat"
    Environment="CATALINA_PID=/opt/tomcat/temp/tomcat.pid"
    Environment="CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC"
       
    ExecStart=/opt/tomcat/bin/startup.sh
    ExecStop=/opt/tomcat/bin/shutdown.sh
       
    RestartSec=10
    Restart=always
       
    [Install]
    WantedBy=multi-user.target
    

    JAVA_HOMEsudo update-java-alternatives -l と同じパスです。

  5. ポートを設定するには、/opt/tomcat/conf/server.xml を編集し、ポートを選択します。8080Pumaは 8080メトリクス用に8080ポートをリッスンするので 8080、ポートの使用は避けてください。

    <Server port="8006" shutdown="SHUTDOWN">
    ...
        <Connector port="8005" protocol="HTTP/1.1"
    ...
    
  6. Tomcatをリロードして起動します:

    sudo systemctl daemon-reload
    sudo systemctl start tomcat
    sudo systemctl status tomcat
    sudo systemctl enable tomcat
    

    Javaプロセスがこれらのポートをリッスンしているはずです:

    root@gitlab-omnibus:/plantuml-server# netstat -plnt | grep java
    tcp6       0      0 127.0.0.1:8006          :::*                    LISTEN      14935/java
    tcp6       0      0 :::8005                 :::*                    LISTEN      14935/java
    
  7. /etc/gitlab/gitlab.rb の NGINX 設定を変更します。proxy_pass ポートがserver.xml の Connector ポートと一致していることを確認します:

    nginx['custom_gitlab_server_config'] = "location /-/plantuml {
        rewrite ^/-/(plantuml.*) /$1 break;
        proxy_set_header  HOST               $host;
        proxy_set_header  X-Forwarded-Host   $host;
        proxy_set_header  X-Forwarded-Proto  $scheme;
        proxy_cache off;
        proxy_pass http://localhost:8005/plantuml;
    }"
    
  8. 新しい変更を読み込むように GitLab を再設定します:

    sudo gitlab-ctl reconfigure
    
  9. PlantUMLをインストールし、.war ファイルをコピーします:

    plantuml-jsp の最新リリースを使用してください (例: plantuml-jsp-v1.2023.8.war)。コンテキストについては、このイシューを参照してください。

    cd /
    wget https://github.com/plantuml/plantuml-server/releases/download/v1.2023.8/plantuml-jsp-v1.2023.8.war
    sudo cp plantuml-jsp-v1.2023.8.war /opt/tomcat/webapps/plantuml.war
    sudo chown tomcat:tomcat /opt/tomcat/webapps/plantuml.war
    sudo systemctl restart tomcat
    

Tomcat サービスは再起動する必要があります。再起動が完了すると、PlantUML インテグレーションは準備が整い、ポート8005 でリクエストを待ち受けます:http://localhost:8005/plantuml

PlantUML サーバが動作しているかどうかをテストするには、curl --location --verbose "http://localhost:8005/plantuml/" を実行してください。

Tomcat のデフォルトを変更するには、/opt/tomcat/conf/server.xml ファイルを編集します。

note
この方法を使用する場合、デフォルトのURLは異なります。Dockerベースのイメージでは、相対パスなしのルートURLでサービスを利用できるようになります。それに応じて、以下の設定を調整してください。

404 ブラウザでPlantUMLページを開くとエラーが発生します。

PlantUML サーバがDebian または Ubuntu でセットアップされている場合、https://gitlab.example.com/-/plantuml/ にアクセスすると404 エラーが発生するかもしれません。

これはインテグレーションが動作しているときでも起こります。これは、必ずしも PlantUML サーバや設定に問題があるわけではありません。

PlantUML セキュリティの設定

PlantUML には、ネットワークリソースをフェッチする機能があります。PlantUML サーバをセルフホストする場合は、それを分離するために、 ネットワーク制御を配置します。例えば、PlantUML のセキュリティプロファイルを利用します。

@startuml
start
    ' ...
    !include http://localhost/
stop;
@enduml

PlantUML インテグレーションを有効化

ローカルの PlantUML サーバを設定した後、PlantUML インテグレーションを 有効にする準備ができました:

  1. GitLabに管理者ユーザーとしてサインインします。
  2. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  3. Admin Areaを選択します。
  4. 左のサイドバーで、設定 > 一般と進み、PlantUMLセクションを展開します。
  5. PlantUMLを有効にする]チェックボックスを選択します。
  6. PlantUML インスタンスをhttps://gitlab.example.com/-/plantuml/として設定し、Save changes を選択します。

PlantUML と GitLab のバージョン番号によっては、以下のステップも必要です:

  • plantuml.com のような v1.2020.9 以上を実行している PlantUML サーバでは、deflate 圧縮を有効にするためにPLANTUML_ENCODING 環境変数を設定する必要があります。Linux パッケージ・インストールでは、このコマンドで/etc/gitlab/gitlab.rb にこの値を設定することができます:

      gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' }
    

    GitLab Helmチャートでは、次のようにglobal.extraEnvセクションに変数を追加することで設定できます:

     global:
     extraEnv:
       PLANTUML_ENCODING: deflate
    
  • deflate は PlantUML のデフォルトエンコーディングタイプです。異なるエンコーディング・タイプを使用するために、PlantUMLインテグレーションは異なるエンコーディング・タイプを区別するためにURLのヘッダープレフィックスを必要とします。