PlantUML
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 서버를 설정하여 다이어그램을 생성해야 합니다:
도커
도커에서 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
파일을 편집하세요.
브라우저에서 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.