PlantUML

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

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

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: hi
```
sphinxcontrib-plantuml과 호환성을 위해 uml:: 지시문을 사용할 수 있지만, GitLab에서는 caption 옵션만 지원합니다.

PlantUML 서버가 올바르게 구성되어 있다면, 이러한 예제는 코드 블록이 아닌 다이어그램으로 렌더링되어야 합니다:

블록 내에서 PlantUML이 지원하는 다이어그램 중 아무 것이나 추가할 수 있습니다:

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

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

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

PlantUML 서버 구성

GitLab에서 PlantUML을 활성화하기 전에, 자체 PlantUML 서버를 설정하여 다이어그램을 생성해야 합니다:

도커에서.
Debian/Ubuntu에서.

도커

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

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

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

GitLab을 도커에서 실행할 때, PlantUML 컨테이너에 액세스해야 합니다. 이를 위해 도커 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 호출을 가져와 로컬 PlantUML 서버로 리디렉션해야 합니다. 시스템에 따라 URL은 다음 중 하나입니다:

http://plantuml:8080/
http://localhost:8080/plantuml/
http://plantuml:8005/
http://localhost:8005/plantuml/

GitLab with 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을 편집하고 포트를 선택하세요. Puma가 메트릭을 위해 포트 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;
}"

변경 사항을 읽으려면 다음 명령을 실행하세요:
```
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이 다를 수 있습니다. Docker 기반 이미지는 루트 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에 헤더 접두어를 필요로 합니다 to distinguish different encoding types.

PlantUML

PlantUML 서버 구성

도커

지역 PlantUML 액세스 구성

Debian/Ubuntu

설치

브라우저에서 PlantUML 페이지를 열 때 `404` 오류가 발생하는 문제

PlantUML 보안 구성

PlantUML 통합 활성화

도움말

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

도움받기

PlantUML

PlantUML 서버 구성

도커

지역 PlantUML 액세스 구성

Debian/Ubuntu

설치

브라우저에서 PlantUML 페이지를 열 때 404 오류가 발생하는 문제

PlantUML 보안 구성

PlantUML 통합 활성화

도움말

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

도움받기

브라우저에서 PlantUML 페이지를 열 때 `404` 오류가 발생하는 문제