PlantUML
PlantUML 통합을 사용하면 스니펫, 위키 및 저장소에서 다이어그램을 만들 수 있습니다. 이 통합은 GitLab.com의 모든 SaaS 사용자에게 활성화되어 있으며 추가 구성이 필요하지 않습니다.
자체 관리 인스턴스에서 통합을 설정하려면 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 호출을 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에 추가하세요. 설정 방법에 따라 다음 명령을 실행하세요:# 도커 배포 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파일을 편집하고 포트를 선택하세요. 메트릭을 위해 포트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 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 -
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 tomcatTomcat 서비스가 다시 시작해야 합니다. 다시 시작이 완료되면 PlantUML 통합이 준비되어 있고 포트
8005에서 요청을 수신합니다:http://localhost:8005/plantumlPlantUML 서버가 작동하는지 테스트하려면
curl --location --verbose "http://localhost:8005/plantuml/"를 실행하세요.
Tomcat 기본값을 변경하려면 /opt/tomcat/conf/server.xml 파일을 편집하세요.
참고: 이 방법을 사용할 때 기본 URL이 다릅니다. 도커 기반 이미지는 상대 경로를 사용하지 않고 루트 URL에서 서비스를 사용할 수 있게 합니다. 아래 구성을 그에 맞게 조정하세요.
브라우저에서 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에 로그인합니다.
- 왼쪽 사이드바에서 가장 아래에 있는 관리 영역을 선택합니다.
- 왼쪽 사이드바에서 설정 > 일반으로 이동하고 PlantUML 섹션을 확장합니다.
- PlantUML 활성화 확인란을 선택합니다.
- PlantUML 인스턴스를
https://gitlab.example.com/-/plantuml/로 설정하고 변경 사항 저장을 선택합니다.
PlantUML 및 GitLab 버전 번호에 따라 다음 단계가 필요할 수도 있습니다:
-
plantuml.com과 같은 v1.2020.9 이상에서 실행 중인 PlantUML 서버의 경우,
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에 헤더 접두사가 필요합니다.
도움말