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 ---- -
재구조화된 텍스트:
.. plantuml:: :caption: Caption with **bold** and *italic* Bob -> Alice: hello Alice -> Bob: hi단,
sphinxcontrib-plantuml과의 호환을 위해uml::지시문을 사용할 수 있지만 GitLab은caption옵션만 지원합니다.
PlantUML 서버가 올바로 구성되었다면 이러한 예제는 코드 블록 대신 다이어그램을 렌더링해야 합니다:
블록 내에서는 PlantUML이 지원하는 다이어그램을 추가할 수 있습니다: - Activity - Class - Component - Object - Sequence - State - Use Case
블록 정의에 매개변수를 추가할 수 있습니다:
- id: 다이어그램 HTML 태그에 추가되는 CSS ID
- width: 이미지 태그에 추가되는 너비 속성
- height: 이미지 태그에 추가되는 높이 속성
Markdown은 어떤 매개변수도 지원하지 않으며 항상 PNG 형식을 사용합니다.
PlantUML 서버 구성
GitLab에서 PlantUML을 활성화하려면 다이어그램을 생성할 자체 PlantUML 서버를 설정해야 합니다:
도커
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은 URL http://plantuml:8005/에서 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 호출을 캐치하고 로컬 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 -
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 오류
Debian 또는 Ubuntu에서 PlantUML 서버를 설정했을 때 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에서 다양한 인코딩 유형을 구분하기 위한 헤더 접두사가 필요합니다.
문제 해결
업데이트 후 렌더링된 다이어그램 URL이 동일함
렌더링된 다이어그램은 캐시됩니다. 업데이트를 확인하려면 다음 단계를 시도해보세요.
- 만약 다이어그램이 Markdown 파일에 있다면, Markdown 파일에 작은 변경을 가하고, 커밋합니다. 이렇게 하면 다시 렌더링됩니다.
- GitLab 캐시를 지웁니다.
업데이트된 URL이 아직 보이지 않는다면 다음을 확인하세요.
- PlantUML 서버가 GitLab 인스턴스에서 접근 가능한지 확인합니다.
- GitLab 설정에서 PlantUML 통합이 활성화되어 있는지 확인합니다.
- PlantUML 렌더링과 관련된 GitLab 로그에서 오류를 확인합니다.
도움말