PlantUML
PlantUML 통합을 사용하면 스니펫, 위키 및 리포지토리에서 다이어그램을 만들 수 있습니다.
이 통합은 모든 SaaS 사용자를 위해 GitLab.com에서 활성화되며 추가 구성이 필요하지 않습니다.
자체 관리 인스턴스에서 통합을 설정하려면 PlantUML 서버를 구성해야 합니다.
통합을 완료한 후, PlantUML는 plantuml 블록을 HTML 이미지 태그로 변환하며, 소스는 PlantUML 인스턴스를 가리킵니다.
PlantUML 다이어그램 구분자인 @startuml/@enduml은 필요하지 않으며, 이는 plantuml 블록으로 대체됩니다:
-
Markdown 파일은 확장자가
.md인 경우:```plantuml Bob -> Alice : hello Alice -> Bob : hi ```추가로 허용되는 확장자에 대한 내용은
languages.yaml파일을 검토하세요. -
AsciiDoc 파일은 확장자가
.asciidoc,.adoc, 또는.asc인 경우:[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: hiuml::지시어를sphinxcontrib-plantuml와의 호환성을 위해 사용할 수 있지만,
GitLab은 오직caption옵션만을 지원합니다.
PlantUML 서버가 올바르게 구성되었다면, 이러한 예제는 코드 블록 대신 다이어그램을 렌더링해야 합니다:
블록 안에는 PlantUML에서 지원하는 모든 다이어그램을 추가할 수 있습니다, 예를 들어:
블록 정의에 매개변수를 추가할 수 있습니다:
-
id: 다이어그램 HTML 태그에 추가되는 CSS ID. -
width: 이미지 태그에 추가되는 너비 속성. -
height: 이미지 태그에 추가되는 높이 속성.
Markdown은 어떤 매개변수도 지원하지 않으며, 항상 PNG 형식을 사용합니다.
PlantUML 서버 구성하기
GitLab에서 PlantUML을 활성화하기 전에, 다이어그램을 생성하기 위해 자체 PlantUML 서버를 설정해야 합니다:
Docker
Docker에서 PlantUML 컨테이너를 실행하려면, 이 명령어를 실행하세요:
docker run -d --name plantuml -p 8005:8080 plantuml/plantuml-server:tomcat
PlantUML URL은 컨테이너를 실행 중인 서버의 호스트 이름입니다.
Docker에서 GitLab을 실행하는 경우, PlantUML 컨테이너에 접근할 수 있어야 합니다.
이를 달성하기 위해 Docker Compose를 사용하세요.
이 기본 docker-compose.yml 파일에서, PlantUML은 http://plantuml:8005/ URL에서 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:8005/; \n}\n"
plantuml:
image: 'plantuml/plantuml-server:tomcat'
container_name: plantuml
ports:
- "8005:8080"
로컬 PlantUML 접근 구성
PlantUML 서버는 귀하의 서버에서 로컬로 실행되므로 기본적으로 외부에서 접근할 수 없습니다. 귀하의 서버는 외부 PlantUML 호출을 https://gitlab.example.com/-/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 배포 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 문서를 참조하세요.
-
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.targetJAVA_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 tomcatJava 프로세스는 다음 포트에서 수신 대기해야 합니다:
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.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에서 서비스를 사용할 수 있게 합니다. 아래 구성을 accordingly 조정하십시오.
브라우저에서 PlantUML 페이지를 열 때 404 오류
https://gitlab.example.com/-/plantuml/를 방문할 때 404 오류가 발생할 수 있습니다. 이는 PlantUML 서버가 Debian 또는 Ubuntu에서 설정되어 있을 때 발생할 수 있습니다.
이것은 통합이 작동하더라도 발생할 수 있습니다.
이는 반드시 PlantUML 서버나 설정에 문제가 있음을 나타내는 것은 아닙니다.
PlantUML 보안 구성
PlantUML은 네트워크 리소스를 가져올 수 있는 기능을 가지고 있습니다. PlantUML 서버를 직접 호스팅하는 경우, 이를 격리하기 위해 네트워크 제어를 적용하세요.
예를 들어, PlantUML의 보안 프로필을 활용하세요.
@startuml
start
' ...
!include http://localhost/
stop;
@enduml
PlantUML 통합 활성화
로컬 PlantUML 서버를 구성한 후, PlantUML 통합을 활성화할 준비가 되었습니다:
- 관리자 사용자로 GitLab에 로그인합니다.
- 왼쪽 사이드바에서 맨 아래로 가서 Admin을 선택합니다.
- 왼쪽 사이드바에서 Settings > General로 이동하여 PlantUML 섹션을 확장합니다.
- Enable PlantUML 체크박스를 선택합니다.
- PlantUML 인스턴스를
https://gitlab.example.com/-/plantuml/로 설정하고, Save changes를 선택합니다.
귀하의 PlantUML 및 GitLab 버전 번호에 따라 다음 단계도 수행해야 할 수 있습니다:
-
v1.2020.9 이상에서 실행되는 PlantUML 서버, 예를 들어 plantuml.com의 경우,
PLANTUML_ENCODING환경 변수를 설정하여deflate압축을 활성화해야 합니다. Linux 패키지 설치의 경우,/etc/gitlab/gitlab.rb에서 이 값을 다음 명령어로 설정할 수 있습니다:gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' }GitLab Helm 차트에서는 아래와 같이 global.extraEnv 섹션에 변수를 추가하여 설정할 수 있습니다:
global: extraEnv: PLANTUML_ENCODING: deflate -
deflate는 PlantUML의 기본 인코딩 유형입니다. 다른 인코딩 유형을 사용하려면, PlantUML 통합은 URL에서 헤더 접두사가 필요합니다 이를 통해 서로 다른 인코딩 유형을 구별할 수 있습니다.
문제 해결
업데이트 후 렌더링된 다이어그램 URL이 동일하게 유지됨
렌더링된 다이어그램은 캐시됩니다. 업데이트를 보기 위해 다음 단계를 시도하세요:
- 다이어그램이 Markdown 파일에 있으면, Markdown 파일에 작은 변경을 가하고 커밋하세요. 이는 재렌더링을 트리거합니다.
- GitLab 캐시를 지우세요.
업데이트된 URL이 여전히 보이지 않는 경우, 다음을 확인하세요:
- PlantUML 서버가 GitLab 인스턴스에서 접근 가능함을 확인하세요.
- GitLab 설정에서 PlantUML 통합이 활성화되어 있는지 확인하세요.
- PlantUML 렌더링과 관련된 오류에 대해 GitLab 로그를 확인하세요.
도움말