PlantUML 통합을 사용하여 스니펫, 위키, 저장소에서 다이어그램을 만드세요. GitLab.com은 모든 사용자에게 PlantUML과 통합되며 추가 구성이 필요하지 않습니다.

GitLab Self-Managed 인스턴스에서 통합을 설정하려면 PlantUML 서버를 구성해야 합니다.

통합을 완료하면 PlantUML이 plantuml 블록을 소스가 PlantUML 인스턴스를 가리키는 HTML 이미지 태그로 변환합니다. PlantUML 다이어그램 구분 기호 @startuml/@enduml은 plantuml 블록으로 대체되므로 필요하지 않습니다:

• .md 확장자를 가진 Markdown 파일:

  <div class="diagram-placeholder"><div class="diagram-placeholder-header">PlantUML 다이어그램 (2줄)</div><details><summary>소스 코드 보기</summary><pre><code>Bob -&gt; Alice : hello
  Alice -&gt; Bob : hi</code></pre></details></div>
  
  

  추가 허용 확장자는 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 서버가 올바르게 구성된 경우 이러한 예시는 코드 블록 대신 다이어그램을 렌더링해야 합니다:

Bob -> Alice : hello
Alice -> Bob : hi

블록 안에 PlantUML이 지원하는 다이어그램을 추가하세요:

• Activity
• Class
• Component
• Object
• Sequence
• State
• Use Case

블록 정의에 매개변수를 추가합니다:

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

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

다이어그램 파일 포함#

저장소의 별도 파일에서 PlantUML 다이어그램을 포함하거나 임베드하려면 include 지시자를 사용하세요. 이를 사용하여 전용 파일에서 복잡한 다이어그램을 유지하거나 다이어그램을 재사용하세요. 예를 들어:

• Markdown:

  <div class="diagram-placeholder"><div class="diagram-placeholder-header">PlantUML 다이어그램 (1줄)</div><details><summary>소스 코드 보기</summary><pre><code>::include{file=diagram.puml}</code></pre></details></div>
  
  

• AsciiDoc:

  [plantuml, format="png", id="myDiagram", width="200px"]
  ----
  include::diagram.puml[]
  ----
  

PlantUML 서버 구성#

GitLab에서 PlantUML을 활성화하기 전에 다이어그램을 생성할 자체 PlantUML 서버를 설정하세요:

• Docker (권장)
• Debian/Ubuntu

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은 URL http://plantuml:8080/에서 GitLab에 액세스할 수 있습니다:

services:
  gitlab:
    image: 'gitlab/gitlab-ee:18.9.1-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:8080/; \n}\n"

  plantuml:
    image: 'plantuml/plantuml-server:tomcat'
    container_name: plantuml
    ports:
     - "8005:8080"

다음으로:

1. 로컬 PlantUML 액세스 구성
2. PlantUML 설치 확인이 성공했는지 확인

Debian/Ubuntu#

Tomcat 또는 Jetty를 사용하여 Debian/Ubuntu 배포판에 PlantUML 서버를 설치하고 구성할 수 있습니다. 아래 지침은 Tomcat용입니다.

사전 조건:

• JRE/JDK 버전 11 이상.
• (권장) Jetty 버전 11 이상.
• (권장) Tomcat 버전 10 이상.

설치#

PlantUML은 Tomcat 10.1 이상 설치를 권장합니다. 이 페이지의 범위에는 기본 Tomcat 서버 설정만 포함됩니다. 더 많은 프로덕션 준비 구성은 Tomcat 문서를 참조하세요.

1. JDK/JRE 11 설치:

   sudo apt update
   sudo apt install default-jre-headless graphviz git
   

2. Tomcat 사용자 추가:

   sudo useradd -m -d /opt/tomcat -U -s /bin/false tomcat
   

3. Tomcat 10.1 설치 및 구성:

   wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.33/bin/apache-tomcat-10.1.33.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
   

4. 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에서 보이는 것과 동일한 경로여야 합니다.

5. 포트를 구성하려면 /opt/tomcat/conf/server.xml을 편집하고 포트를 선택합니다. 권장:

   • Tomcat 종료 포트를 8005에서 8006으로 변경합니다.
   • Tomcat HTTP 엔드포인트에 포트 8005를 사용합니다. Puma가 메트릭을 위해 포트 8080에서 수신 대기하므로 기본 포트 8080은 피해야 합니다.

   - 
   + 
   
   - 
   + 
   

6. Tomcat 다시 로드 및 시작:

   sudo systemctl daemon-reload
   sudo systemctl start tomcat
   sudo systemctl status tomcat
   sudo systemctl enable tomcat
   

   Java 프로세스가 이러한 포트에서 수신 대기해야 합니다:

   root@gitlab-omnibus:/plantuml-server# ❯ ss -plnt | grep java
   LISTEN   0        1          [::ffff:127.0.0.1]:8006                   *:*       users:(("java",pid=27338,fd=52))
   LISTEN   0        100                         *:8005                   *:*       users:(("java",pid=27338,fd=43))
   

7. PlantUML 설치 및 .war 파일 복사:

   plantuml-jsp의 최신 릴리즈를 사용합니다 (예: plantuml-jsp-v1.2024.8.war). 배경 정보는 이슈 265를 참조하세요.

   wget -P /tmp https://github.com/plantuml/plantuml-server/releases/download/v1.2024.8/plantuml-jsp-v1.2024.8.war
   sudo cp /tmp/plantuml-jsp-v1.2024.8.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.

Tomcat 기본값을 변경하려면 /opt/tomcat/conf/server.xml 파일을 편집하세요.

다음으로:

1. 로컬 PlantUML 액세스 구성. 링크에서 구성된 proxy_pass 포트가 server.xml의 Connector 포트와 일치하는지 확인합니다.
2. PlantUML 설치 확인이 성공했는지 확인.

로컬 PlantUML 액세스 구성#

PlantUML 서버가 서버에서 로컬로 실행되므로 기본적으로 외부에서 액세스할 수 없습니다. 서버는 https://gitlab.example.com/-/plantuml/에 대한 외부 PlantUML 호출을 캐치하고 로컬 PlantUML 서버로 리디렉션해야 합니다. 설정에 따라 URL은 다음 중 하나입니다:

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

GitLab with TLS를 실행하는 경우 PlantUML이 안전하지 않은 HTTP 프로토콜을 사용하기 때문에 이 리디렉션을 구성해야 합니다. 최신 브라우저는 HTTPS로 제공되는 페이지에서 안전하지 않은 HTTP 리소스를 로드하지 않습니다.

번들된 GitLab NGINX 사용#

/etc/gitlab/gitlab.rb를 수정할 수 있는 경우 번들된 NGINX를 구성하여 리디렉션을 처리합니다:

1. 설정 방법에 따라 /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"
   
   # Debian/Ubuntu 설치
   nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n  rewrite ^/-/plantuml/(.*) /$1 break;\n  proxy_cache off; \n    proxy_pass  http://localhost:8005/plantuml; \n}\n"
   

2. 변경 사항을 활성화하려면 다음 명령을 실행합니다:

   sudo gitlab-ctl reconfigure
   

HTTPS PlantUML 서버 사용#

gitlab.rb 파일을 수정할 수 없는 경우 PlantUML 서버를 직접 HTTPS를 사용하도록 구성하세요. 이 방법은 GitLab Dedicated 인스턴스에 권장됩니다.

이 설정은 NGINX를 사용하여 SSL 종료를 처리하고 요청을 PlantUML 컨테이너로 프록시합니다. SSL 종료를 위해 AWS Application Load Balancer(ALB)와 같은 클라우드 기반 로드 밸런서를 사용할 수도 있습니다.

1. nginx.conf 파일을 만듭니다:

   events {
       worker_connections 1024;
   }
   
   http {
       server {
           listen 443 ssl;
           server_name _;
           ssl_certificate /etc/nginx/ssl/plantuml.crt;
           ssl_certificate_key /etc/nginx/ssl/plantuml.key;
           location / {
               proxy_pass http://plantuml:8080;
               proxy_set_header Host $host;
               proxy_set_header X-Real-IP $remote_addr;
               proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
               proxy_set_header X-Forwarded-Proto $scheme;
           }
       }
   }
   

2. ssl 디렉토리에 plantuml.crt 및 plantuml.key 파일을 추가합니다.

3. docker-compose.yml 파일을 구성합니다:

   version: '3.8'
   
   services:
     plantuml:
       image: plantuml/plantuml-server:tomcat
       container_name: plantuml
       networks:
         - plantuml-net
   
     plantuml-ssl:
       image: nginx
       container_name: plantuml-ssl
       ports:
         - "8443:443"
       volumes:
         - ./nginx.conf:/etc/nginx/nginx.conf:ro
         - ./ssl:/etc/nginx/ssl:ro
       depends_on:
         - plantuml
       networks:
         - plantuml-net
   
   networks:
     plantuml-net:
       driver: bridge
   

4. docker-compose up으로 PlantUML 서버를 시작합니다.

5. URL https://your-server:8443으로 PlantUML 통합 활성화합니다.

PlantUML 설치 확인#

설치가 성공했는지 확인하려면:

1. PlantUML 서버를 직접 테스트합니다:

   # Docker 설치
   curl --location --verbose "http://localhost:8005/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000"
   
   # Debian/Ubuntu 설치
   curl --location --verbose "http://localhost:8005/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000"
   

   hello 텍스트가 포함된 SVG 출력을 받아야 합니다.

2. 다음을 방문하여 GitLab이 NGINX를 통해 PlantUML에 액세스할 수 있는지 테스트합니다:

   http://gitlab.example.com/-/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000
   

   gitlab.example.com을 GitLab 인스턴스 URL로 교체합니다. hello를 표시하는 렌더링된 PlantUML 다이어그램이 표시되어야 합니다.

   Bob -> Alice : hello
   

PlantUML 보안 구성#

PlantUML에는 네트워크 리소스를 가져올 수 있는 기능이 있습니다. PlantUML 서버를 자체 호스팅하는 경우 네트워크 제어를 통해 격리하세요. 예를 들어 PlantUML의 보안 프로파일을 활용하세요.

@startuml
start
    ' ...
    !include http://localhost/
stop;
@enduml

PlantUML SVG 다이어그램 출력 보안#

SVG 형식으로 PlantUML 다이어그램을 생성할 때 향상된 보안을 위해 서버를 구성하세요. 잠재적인 보안 문제를 방지하기 위해 NGINX 구성에서 SVG 출력 경로를 비활성화합니다.

SVG 출력 경로를 비활성화하려면 PlantUML 서비스를 호스팅하는 NGINX 서버에 이 구성을 추가합니다:

location ~ ^/-/plantuml/svg/ {
    return 403;
}

이 구성은 잠재적으로 악의적인 다이어그램 코드가 브라우저에서 실행되는 것을 방지합니다.

PlantUML 통합 활성화#

로컬 PlantUML 서버를 구성한 후 PlantUML 통합을 활성화할 준비가 됩니다:

1. Administrator 사용자로 GitLab에 로그인합니다.
2. 오른쪽 상단에서 Admin을 선택합니다.
3. 왼쪽 사이드바에서 Settings > General로 이동하고 PlantUML 섹션을 확장합니다.
4. Enable PlantUML 체크박스를 선택합니다.
5. PlantUML 인스턴스를 https://gitlab.example.com/-/plantuml/로 설정하고 Save changes를 선택합니다.

브라우저가 외부 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 파일을 약간 변경하고 커밋합니다. 이렇게 하면 재렌더링이 트리거됩니다.
• Markdown 캐시 무효화를 통해 데이터베이스나 Redis에 캐시된 Markdown을 강제로 지웁니다.

여전히 업데이트된 URL이 표시되지 않으면 다음을 확인하세요:

• GitLab 인스턴스에서 PlantUML 서버에 액세스할 수 있는지 확인합니다.
• GitLab 설정에서 PlantUML 통합이 활성화되어 있는지 확인합니다.
• PlantUML 렌더링과 관련된 오류에 대해 GitLab 로그를 확인합니다.
• GitLab Redis 캐시 지우기.

브라우저에서 PlantUML 페이지를 열 때 404 오류#

Debian 또는 Ubuntu에서 PlantUML 서버를 설정할 때 https://gitlab.example.com/-/plantuml/를 방문하면 404 오류가 발생할 수 있습니다.

통합이 작동 중인 경우에도 이 오류가 발생할 수 있습니다. 반드시 PlantUML 서버 또는 구성의 문제를 나타내는 것은 아닙니다.

PlantUML이 올바르게 작동하는지 확인하려면 PlantUML 설치 확인을 할 수 있습니다.