プラントUML

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

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

インテグレーションが完了すると、PlantUML はplantuml ブロックを、ソースが PlantUML インスタンスを指している HTML イメージタグに変換します。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: 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で。
Debian/Ubuntuでは。

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リソースを読み込みません。

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

/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"

変更をアクティビティにするには、以下のコマンドを実行します：
```
sudo gitlab-ctl reconfigure
```

Debian/Ubuntu

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

前提条件：

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

インストール

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

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

sudo apt update
sudo apt-get install graphviz default-jdk git-core

Tomcatのユーザーを追加します：

sudo useradd -m -d /opt/tomcat -U -s /bin/false tomcat

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

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_HOME はsudo update-java-alternatives -l と同じパスです。

ポートを設定するには、/opt/tomcat/conf/server.xml を編集し、ポートを選択します。8080Pumaは 8080メトリクス用に8080ポートをリッスンするので 8080、ポートの使用は避けてください。
```
<Server port="8006" shutdown="SHUTDOWN">
...
    <Connector port="8005" protocol="HTTP/1.1"
...
```

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

/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;
}"

新しい変更を読み込むように GitLab を再設定します：
```
sudo gitlab-ctl reconfigure
```

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 ファイルを編集します。

この方法を使用する場合、デフォルトの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 インテグレーションを有効にする準備ができました：

GitLabに管理者ユーザーとしてサインインします。
左のサイドバーで、Search を選択するか、次のページに進んでください。
Admin Areaを選択します。
左のサイドバーで、設定 > 一般と進み、PlantUMLセクションを展開します。
PlantUMLを有効にする]チェックボックスを選択します。
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のヘッダープレフィックスを必要とします。

プラントUML

PlantUMLサーバの設定

Docker

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

Debian/Ubuntu

インストール

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

PlantUML セキュリティの設定

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

Help & feedback

Docs

Product

Feature availability and product trials

Get Help

プラントUML

PlantUMLサーバの設定

Docker

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

Debian/Ubuntu

インストール

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

PlantUML セキュリティの設定

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

Help & feedback

Docs

Product

Feature availability and product trials

Get Help

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