PlantUML
- プラン: Free、Premium、Ultimate
- 提供形態: GitLab Self-Managed、GitLab Dedicated
スニペット、Wiki、リポジトリでダイアグラムを作成するにはPlantUMLインテグレーションを使用します。すべてのユーザー向けにGitLab.comはPlantUMLと統合されており、追加の設定は不要です。
GitLab Self-Managedインスタンスでインテグレーションをセットアップするには、PlantUMLサーバーを設定する必要があります。
インテグレーションが完了すると、PlantUMLは、plantumlブロックをHTML画像タグに変換します。このとき、ソースはPlantUMLインスタンスを指しています。PlantUMLダイアグラムの区切り文字@startuml/@endumlはplantumlブロックに置き換えられるため、これらの区切り文字は不要です:
拡張子
.mdが付いたMarkdownファイル:```plantuml Bob -> Alice : hello Alice -> Bob : hi ```その他の使用可能な拡張子については、
languages.yamlファイルを参照してください。拡張子
.asciidoc、.adoc、または.ascが付いたAsciiDocファイル:[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: hisphinxcontrib-plantumlとの互換性を保つためにuml::ディレクティブを使用できますが、GitLabはcaptionオプションのみをサポートします。
PlantUMLサーバーが正しく設定されている場合、これらの例では、コードブロックではなく、ダイアグラムがレンダリングされます:
Bob -> Alice : hello Alice -> Bob : hi
ブロック内には、PlantUMLがサポートする次のようなダイアグラムを追加します:
ブロック定義にパラメータを追加します:
id: ダイアグラムHTMLタグに追加されたCSS ID。width: 画像タグに追加された幅属性。height: 画像タグに追加された高さ属性。
Markdownはパラメータをサポートしておらず、常にPNG形式を使用します。
ダイアグラムファイルをインクルードする
リポジトリ内の別のファイルからPlantUMLダイアグラムをインクルードするかまたは埋め込むには、includeディレクティブを使用します。これを使用して、専用ファイルで複雑なダイアグラムを管理したり、ダイアグラムを再利用したりします。次に例を示します:
Markdown:
```plantuml ::include{file=diagram.puml} ```AsciiDoc:
[plantuml, format="png", id="myDiagram", width="200px"] ---- include::diagram.puml[] ----
PlantUMLサーバーを設定する
GitLabでPlantUMLを有効にする前に、ダイアグラムを生成するために、独自のPlantUMLサーバーを設定します:
Docker
DockerでPlantUMLコンテナを実行するには、次のコマンドを実行します:
docker run -d --name plantuml -p 8005:8080 plantuml/plantuml-server:tomcatPlantUML URLは、コンテナを実行しているサーバーのホスト名です。
DockerでGitLabを実行する場合、PlantUMLコンテナにアクセスできる必要があります。アクセスできるようにするには、Docker Composeを使用します。この基本的なdocker-compose.ymlファイルで、GitLabはURL http://plantuml:8005/でPlantUMLにアクセスできます:
version: "3"
services:
gitlab:
image: 'gitlab/gitlab-ee:17.9.1-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:8005/; \n}\n"
plantuml:
image: 'plantuml/plantuml-server:tomcat'
container_name: plantuml
ports:
- "8005:8080"その後、次のことができるようになります:
Debian/Ubuntu
TomcatまたはJettyを使用して、Debian/UbuntuディストリビューションにPlantUMLサーバーをインストールして設定できます。以下の手順はTomcat用です。
前提要件:
- JRE/JDKバージョン11以降。
- （推奨）Jettyバージョン11以降。
- （推奨）Tomcatバージョン10以降。
インストール
PlantUMLでは、Tomcat 10.1以降をインストールすることをお勧めします。このページでは、基本的なTomcatサーバーのセットアップのみを扱います。本番環境により適合した設定については、Tomcatのドキュメントを参照してください。
JDK/JRE 11をインストールします:
sudo apt update sudo apt install default-jre-headless graphviz gitTomcatのユーザーを追加します:
sudo useradd -m -d /opt/tomcat -U -s /bin/false tomcatTomcat 10.1をインストールして設定します:
wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.33/bin/apache-tomcat-10.1.33.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/binsystemdサービスを作成します。
/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.targetJAVA_HOMEは、sudo update-java-alternatives -lに表示されるパスと同じである必要があります。ポートを設定するには、
/opt/tomcat/conf/server.xmlを編集してポートを選択します。次の操作を行うことをおすすめします:- Tomcatシャットダウンポートを
8005から8006に変更します。 - Tomcat HTTPエンドポイントにポート
8005を使用します。Pumaがポート8080でメトリクスをリッスンするため、デフォルトのポート8080は避ける必要があります。
- <Server port="8006" shutdown="SHUTDOWN"> + <Server port="8005" shutdown="SHUTDOWN"> - <Connector port="8005" protocol="HTTP/1.1" + <Connector port="8080" protocol="HTTP/1.1"- Tomcatシャットダウンポートを
Tomcatを再読み込みして起動します:
sudo systemctl daemon-reload sudo systemctl start tomcat sudo systemctl status tomcat sudo systemctl enable tomcatJavaプロセスはこれらのポートでリッスンする必要があります:
root@gitlab-omnibus:/plantuml-server# ❯ ss -plnt | grep java LISTEN 0 1 [::ffff:127.0.0.1]:8006 *:* users:(("java",pid=27338,fd=52)) LISTEN 0 100 *:8005 *:* users:(("java",pid=27338,fd=43))PlantUMLをインストールし、
.warファイルをコピーします:plantuml-jspの最新リリース（例:plantuml-jsp-v1.2024.8.war）を使用します。詳細については、イシュー265を参照してください。wget -P /tmp https://github.com/plantuml/plantuml-server/releases/download/v1.2024.8/plantuml-jsp-v1.2024.8.war sudo cp /tmp/plantuml-jsp-v1.2024.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でリクエストをリッスンする準備が整います。
Tomcatのデフォルトを変更するには、/opt/tomcat/conf/server.xmlファイルを編集します。
このアプローチを使用する場合、デフォルトのURLは異なります。Dockerベースのイメージでは、相対パスなしで、ルートURLでサービスを利用できます。必要に応じて、以下の設定を調整します。
その後、次のことができるようになります:
- ローカルPlantUMLアクセスを設定します。リンクで設定された
proxy_passポートがserver.xmlのコネクタポートと一致していることを確認します。 - PlantUMLのインストールが成功したことを確認します。
ローカルPlantUMLアクセスを設定する
PlantUMLサーバーはサーバーでローカルに実行されます。そのため、デフォルトでは外部からアクセスできません。サーバーは、https://gitlab.example.com/-/plantuml/への外部PlantUML呼び出しをキャッチして、ローカルPlantUMLサーバーにリダイレクトする必要があります。セットアップに応じて、URLは次のいずれかになります:
http://plantuml:8080/http://localhost:8080/plantuml/http://plantuml:8005/http://localhost:8005/plantuml/
TLSを使用してGitLabを実行している場合は、PlantUMLが脆弱なHTTPプロトコルを使用します。したがって、このリダイレクトを設定する必要があります。Google Chrome 86以降などの新しいブラウザでは、HTTPSを介して提供されるページ上で脆弱なHTTPリソースは読み込まれません。
バンドルされているGitLab NGINXを使用する
/etc/gitlab/gitlab.rbを変更できる場合は、リダイレクトを処理するようにバンドルされているNGINXを設定します:
セットアップ方法に応じて、
/etc/gitlab/gitlab.rbに次の行を追加します:# Docker install nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n rewrite ^/-/plantuml/(.*) /$1 break;\n proxy_cache off; \n proxy_pass http://plantuml:8005/; \n}\n" # Debian/Ubuntu install nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n rewrite ^/-/plantuml/(.*) /$1 break;\n proxy_cache off; \n proxy_pass http://localhost:8005/plantuml; \n}\n"変更を有効にするには、次のコマンドを実行します:
sudo gitlab-ctl reconfigure
HTTPS PlantUMLサーバーを使用する
gitlab.rbファイルを変更できない場合は、HTTPSを直接使用するようにPlantUMLサーバーを設定してください。この方法は、GitLab Dedicatedインスタンスにおすすめです。
この設定では、NGINXを使用してSSLターミネーションを処理し、PlantUMLコンテナへのリクエストをプロキシします。SSLターミネーションには、AWS Applicationロードバランサー (ALB)のようなクラウドベースのロードバランサーも使用できます。
nginx.confファイルを作成します:events { worker_connections 1024; } http { server { listen 443 ssl; server_name _; ssl_certificate /etc/nginx/ssl/plantuml.crt; ssl_certificate_key /etc/nginx/ssl/plantuml.key; location / { proxy_pass http://plantuml:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } }plantuml.crtファイルとplantuml.keyファイルをsslディレクトリに追加します。docker-compose.ymlファイルを設定します:version: '3.8' services: plantuml: image: plantuml/plantuml-server:tomcat container_name: plantuml networks: - plantuml-net plantuml-ssl: image: nginx container_name: plantuml-ssl ports: - "8443:443" volumes: - ./nginx.conf:/etc/nginx/nginx.conf:ro - ./ssl:/etc/nginx/ssl:ro depends_on: - plantuml networks: - plantuml-net networks: plantuml-net: driver: bridgedocker-compose upを使用してPlantUMLサーバーを起動します。URL
https://your-server:8443でPlantUMLインテグレーションを有効にします。
PlantUMLのインストールを確認する
インストールが成功したことを確認するには、次の手順に従います:
PlantUMLサーバーを直接テストします:
# Docker install curl --location --verbose "http://localhost:8005/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000" # Debian/Ubuntu install curl --location --verbose "http://localhost:8005/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000"テキスト
helloが含まれるSVG出力を受け取るはずです。次の場所にアクセスして、GitLabがNGINXを介してPlantUMLにアクセスできることをテストします:
http://gitlab.example.com/-/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000gitlab.example.comをGitLabインスタンスのURLに置き換えます。helloを表示するレンダリングされたPlantUMLダイアグラムが表示されるはずです。Bob -> Alice : hello
PlantUMLのセキュリティを設定する
PlantUMLには、ネットワークリソースのフェッチを許可する機能があります。PlantUMLサーバーをセルフホストする場合は、ネットワークコントロールを配置して、PlantUMLサーバーを分離します。たとえば、PlantUMLのセキュリティプロファイルを利用します。
@startuml
start
' ...
!include http://localhost/
stop;
@endumlPlantUML SVGダイアグラム出力を保護する
PlantUMLダイアグラムをSVG形式で生成する際は、サーバーを設定してセキュリティを強化します。発生のおそれがあるセキュリティ上の問題を回避するために、NGINX設定でSVG出力ルートを無効にします。
SVG出力ルートを無効にするには、PlantUMLサービスをホストしているNGINXサーバーにこの設定を追加します:
location ~ ^/-/plantuml/svg/ {
return 403;
}この設定により、悪意のある可能性があるダイアグラムコードがブラウザで実行されることを防げます。
PlantUMLインテグレーションを有効にする
ローカルPlantUMLサーバーを設定したら、PlantUMLインテグレーションを有効にする準備が整います:
- 管理者ユーザーとしてGitLabにサインインします。
- 左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにした場合は、右上隅でアバターを選択し、次に管理者を選択します。
- 左側のサイドバーで、設定 > 一般に移動し、PlantUMLセクションを展開する。
- PlantUMLを有効化チェックボックスをオンにします。
- PlantUMLインスタンスを
https://gitlab.example.com/-/plantuml/として設定し、変更を保存を選択します。
PlantUMLとGitLabのバージョン番号によっては、次の手順も実行する必要がある場合があります:
plantuml.comなど、v1.2020.9以降を実行しているPlantUMLサーバーの場合、
PLANTUML_ENCODING環境変数を設定して、deflate圧縮を有効にする必要があります。Linuxパッケージインストールでは、次のコマンドを使用して、この値を/etc/gitlab/gitlab.rbに設定できます:gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' }GitLab Helmチャートでは、次のように、変数をglobal.extraEnvセクションに追加して値を設定できます:
global: extraEnv: PLANTUML_ENCODING: deflatedeflateは、PlantUMLのデフォルトのエンコードタイプです。別のエンコードタイプを使用する場合、PlantUMLインテグレーションでは、URLのヘッダープレフィックスで異なるエンコードタイプを区別する必要があります。
トラブルシューティング
更新後もレンダリングされたダイアグラムのURLが同じままである
レンダリングされたダイアグラムはキャッシュされます。更新を表示するには、次の手順を試してください:
- ダイアグラムがMarkdownファイルにある場合は、Markdownファイルに小さな変更を加えてコミットします。これにより、再レンダリングがトリガーされます。
- Markdownキャッシュを無効にして、データベースまたはRedisにキャッシュされたMarkdownを強制的にクリアします。
更新されたURLがまだ表示されない場合は、以下を確認してください:
- PlantUMLサーバーがGitLabインスタンスからアクセスできることを確認します。
- PlantUMLインテグレーションがGitLabの設定で有効になっていることを確認します。
- PlantUMLレンダリングに関連するエラーについてGitLabログを確認します。
- GitLab Redisキャッシュをクリアします。
ブラウザでPlantUMLページを開くと404エラーが発生する
PlantUMLサーバーがDebianまたはUbuntuでセットアップされている場合、https://gitlab.example.com/-/plantuml/にアクセスすると404エラーが発生することがあります。
このエラーは、インテグレーションが機能している場合でも発生する可能性があります。これは、PlantUMLサーバーまたは設定に関する問題を必ずしも示すものではありません。
PlantUMLが正しく動作しているか確認するには、PlantUMLのインストールを確認してください。