PlantUML

Tier: Free, Premium, Ultimate Offering: Self-managed

PlantUML 통합을 사용하면 스니펫, 위키 및 리포지터리에서 다이어그램을 생성할 수 있습니다. 이 통합은 모든 SaaS 사용자를 위해 GitLab.com에서 활성화되며 추가 구성이 필요하지 않습니다.

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&#46;", width="200px"]
----
Bob -> Alice : hello
Alice -> Bob : hi
----

reStructuredText
```
.. plantuml::
   :caption: **볼드** 및 *이탤릭*이 포함된 캡션
     
   Bob -> Alice: hello
   Alice -> Bob: hi
```
호환성을 위해 sphinxcontrib-plantuml과 uml:: 지시문을 사용할 수 있지만 GitLab은 caption 옵션만 지원합니다.

PlantUML 서버가 올바르게 구성된 경우, 이러한 예제는 코드 블록이 아닌 다이어그램을 렌더링해야 합니다:

블록 내에서 PlantUML이 지원하는 다양한 다이어그램을 추가할 수 있습니다:

블록 정의에 매개변수를 추가할 수 있습니다:

id: 다이어그램 HTML 태그에 추가되는 CSS ID
width: 이미지 태그에 추가되는 너비 속성
height: 이미지 태그에 추가되는 높이 속성

Markdown은 어떠한 매개변수도 지원하지 않으며 항상 PNG 형식을 사용합니다.

PlantUML 서버 구성

GitLab에서 PlantUML을 활성화하려면 자신의 PlantUML 서버를 설정하여 다이어그램을 생성해야 합니다.

Docker에서 실행
Debian/Ubuntu에서 실행

Docker

Docker에서 PlantUML 컨테이너를 실행하려면 다음 명령을 실행하세요:

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

PlantUML URL은 컨테이너를 실행하는 서버의 호스트명입니다.

GitLab을 Docker에서 실행하는 경우 PlantUML 컨테이너에 액세스해야 합니다. 이를 위해 Docker Compose를 사용하세요. 이 간단한 docker-compose.yml 파일에서 PlantUML은 GitLab에서 http://plantuml:8005/ URL에서 접근할 수 있습니다:

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:8005/; \n}\n"
  
  plantuml:
    image: 'plantuml/plantuml-server:tomcat'
    container_name: plantuml

로컬 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/

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:8005/; \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 Documentation을 참조하세요.

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.15/bin/apache-tomcat-10.1.15.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 파일을 편집하고 포트를 선택하세요. 8080 포트는 사용하지 않도록 하세요. Puma는 메트릭을 위해 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

NGINX 구성을 변경하려면 /etc/gitlab/gitlab.rb에서 설정을 편집하세요. 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.12.war)를 사용하세요. 상황에 맞는 내용은 이 이슈에서 확인하세요.

wget -P /tmp https://github.com/plantuml/plantuml-server/releases/download/v1.2023.12/plantuml-jsp-v1.2023.12.war
sudo cp /tmp/plantuml-jsp-v1.2023.12.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이 다릅니다. 도커 기반 이미지는 상대 경로가 없는 루트 URL에 서비스를 제공합니다. 아래 구성을 그에 맞게 조정하세요.

브라우저에서 PlantUML 페이지를 열 때 `404` 오류

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에 로그인합니다.
왼쪽 사이드바에서 가장 아래에서 관리 영역을 선택합니다.
왼쪽 사이드바에서 설정 > 일반으로 이동한 다음 PlantUML 섹션을 확장합니다.
PlantUML 활성화 확인란을 선택합니다.
PlantUML 인스턴스를 https://gitlab.example.com/-/plantuml/로 설정하고, 변경 사항 저장을 선택합니다.

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에서 헤더 접두어가 필요합니다 고유한 인코딩 유형을 구별하기 위해.

PlantUML

PlantUML 서버 구성

Docker

로컬 PlantUML 액세스 구성

Debian/Ubuntu

설치

브라우저에서 PlantUML 페이지를 열 때 `404` 오류

PlantUML 보안 구성

PlantUML 통합 기능 활성화

도움말

기능 사용 가능성과 제품 평가판

도움받기

PlantUML

PlantUML 서버 구성

Docker

로컬 PlantUML 액세스 구성

Debian/Ubuntu

설치

브라우저에서 PlantUML 페이지를 열 때 404 오류

PlantUML 보안 구성

PlantUML 통합 기능 활성화

도움말

기능 사용 가능성과 제품 평가판

도움받기

브라우저에서 PlantUML 페이지를 열 때 `404` 오류