Kroki - 텍스트 기반 다이어그램

(본 게시글은 ChatGPT를 기반으로 작성되었습니다.)

https://kroki.io

Kroki!

 

프로젝트를 진행하면서 복잡한 비즈니스 로직이나 시스템 아키텍처를 설명해야 할 때, 다이어그램이나 흐름도를 직접 그려본 적 있으신가요?

• 문서화 부담: 최신 요구사항으로 문서를 재작성하려면, 기존 그림을 일일이 수정해야 합니다.
• 버전 불일치: PowerPoint나 기타 툴로 만든 다이어그램은 파일 단위로 관리되어, 최신 버전이 여러 곳에 흩어져 있을 수 있습니다.
• 협업 난이도: 변경 이력을 추적하기 어렵고, 팀원 간 동시에 편집하는 데 제한이 많습니다.

이런 고민을 해본 분이라면, Kroki가 제시하는 텍스트 기반 다이어그램 작성 방식에 주목해보세요. 몇 줄의 텍스트로 자동 생성한 다이어그램을, 언제든지 쉽게 수정하고 공유할 수 있기 때문입니다.

1) 무엇: Kroki란 무엇인가?

Kroki는 PlantUML, Mermaid, Graphviz 등 다양한 텍스트 DSL(Domain-Specific Language)을 지원해 다이어그램을 생성해주는 **“텍스트 기반 다이어그램 통합 툴”**입니다.

• 한 줄 요약: 텍스트 작성 → 다이어그램 자동 생성 → 링크 혹은 이미지 형태 공유

2) 누구: 이 글을 읽으면 좋은 사람

• 개발자: UML 시퀀스, 클래스 다이어그램을 자주 작성하는 분
• 기획/PM: 비즈니스 플로우나 요구사항 변경이 잦아, 빠른 다이어그램 업데이트가 필요한 분
• 블로거/기술 작가: 많은 다이어그램을 문서화하며, 한눈에 내용 전달이 필요한 분
• 디자이너: 디자인 초안과 정보 아키텍처(IA) 다이어그램이 자주 수정되는 환경의 구성원

3) 왜: Kroki가 중요한 이유

1. 효율성: 텍스트만 수정하면 다이어그램이 실시간으로 갱신되므로, 작업 시간이 크게 단축됩니다.
2. 일관성: 다이어그램 버전 관리가 용이해, 팀원 모두가 동일한 최신 버전을 참조할 수 있습니다.
3. 유연성: PlantUML, Mermaid, Graphviz, C4 모델 등 여러 DSL을 한 번에 지원하므로, 다양한 유형의 다이어그램을 커버합니다.

지원 다이어그램 종류

kroki_cheatsheet_20210515_v1.1_EN.pdf

3.11MB

UML

• Block diagram
• Sequence diagram
• Activity diagram
• Network diagram
• Use case diagram
• Class diagram
• State diagram
• Object diagram
• Deployment diagram
• Timing diagram
• Entity Relationship Diagram

C4

• C4 Context diagram
• C4 Container diagram
• C4 Component diagram
• Software Architecture using Structurizr DSL
  • System Landscape diagram
  • System Context diagram
  • Container diagram
  • Component diagram
  • Dynamic diagram
  • Deployment diagram

Diagram

• Object Oriented Graph
• Work Breakdown Structure
• Mind Map diagram
• Gantt diagram
• Ditaa diagram
• Packet diagram
• Rack diagram
• Digital Timing diagram (waveform)
• BPMN diagram
• Bytefield diagram
• HDL Component diagram
• Excalidraw
• diagrams.net (experimental)
• WireViz

Visualization

• Bar charts
• Line & area charts
• Circular charts
• Scatter plots
• Distributions
• Geographic maps
• Tree diagrams
• Network diagrams
• Heatmaps
• Word clouds
• Beeswarm plots

Looking for inspiration? Visit the examples page.

4) 어떻게: Kroki 활용 방법

1. Kroki 서버 직접 운영 ( 맨 아래 참조 )
2. 공개 클라우드 사용
3. GitLab/GitHub 연동
4. ClickUp 화이트보드 병행

5) 유사 솔루션들과의 비교

구분	Kroki	PlantUML / Mermaid / Graphviz	Draw.io(diagrams.net)	Lucidchart	WebSequenceDiagrams
기본 방식	텍스트 DSL을 통합해서 렌더링 (서버·클라우드)	각 DSL별로 개별 문법을 사용하여 텍스트 기반으로 렌더링	웹 기반 드래그 앤 드롭 방식	웹 기반 실시간 협업 + 드래그 앤 드롭	시퀀스 다이어그램에 특화된 텍스트 기반 DSL
지원 다이어그램	PlantUML, Mermaid, Graphviz, C4 등 다양한 DSL을 단일 인터페이스로 지원	PlantUML(주로 UML), Mermaid(다양한 차트, UML), Graphviz(그래프 표현) 등 각각 별도 사용	Flowchart, BPMN, Mind Map 등 다양한 템플릿 제공	Flowchart, UML, 조직도, Mind Map, Wireframe 등 광범위	시퀀스 다이어그램 중심. 일부 제한된 형식만 지원
설치/사용 방식	- 로컬/서버 설치(도커 등) - https://kroki.io클라우드 이용<br/>- Markdown 등에 URL 형식 삽입	- CLI/로컬 설치 또는 웹 에디터(PlantText, Mermaid Live Editor 등) - 개별 DSL에 맞춰 환경 설정 필요	- 웹 브라우저 접속 후 직접 도형 배치	- 웹 브라우저에서 사용자 계정 생성 후 이용 - Confluence 등과 플러그인 연동 가능	- 웹 브라우저에서 텍스트 입력 후 시퀀스 다이어그램 자동 생성
라이선스 / 비용	- 오픈소스 (무료)	- PlantUML: 오픈소스(무료)<br/>- Mermaid: 오픈소스(무료)<br/>- Graphviz: 오픈소스(무료)	- 무료/유료 버전 존재(기본 무료, 일부 기능 제한)<br/>- 오픈소스 프로젝트(diagrams.net)	- 무료 체험 가능<br/>- 사용자·기능 확대 시 유료 플랜 필요	- 무료 플랜 존재(일부 기능 제한)
협업 및 버전 관리	- 텍스트 기반이라 Git 등으로 버전 관리 용이<br/>- 변경 시마다 다이어그램 자동 업데이트 가능	- 각각 DSL별로 텍스트 기반이라 Git으로 버전 관리는 가능하지만, 여러 DSL을 통합하려면 추가 설정 필요	- 일반적으로 완료된 이미지를 첨부해 관리<br/>- 버전 관리는 수동 (파일로 관리)	- 여러 명이 실시간으로 다이어그램 편집 가능<br/>- 버전 관리 자체는 에디터 내 이력 정도로 제한	- Git 버전 관리는 가능하지만, 시퀀스 다이어그램 이외에는 적용 범위 제한
학습 곡선	- DSL 문법을 알아야 하지만 여러 DSL을 한 곳에서 다룰 수 있음	- 개별 DSL을 배워야 하며, 각 문법과 렌더링 방식이 상이	- 드래그 앤 드롭 형식으로 직관적이지만, 복잡한 다이어그램은 시간 소요	- 드래그 앤 드롭이 직관적이며 템플릿 다양<br/>- 복잡한 설정은 일부 러닝커브 있음	- 시퀀스 다이어그램에 한정해서 매우 간단<br/>- 다른 유형은 지원 부족
장점	- 여러 DSL(UML, Mermaid, Graphviz 등)을 통합 지원<br/>- 텍스트만 수정해도 다이어그램 자동 생성<br/>- 완전 무료로 서버 구축 가능	- 자유도 높은 텍스트 DSL (특정 목적에 특화)<br/>- 오픈소스 커뮤니티 활발<br/>- 공식/비공식 에디터 다양	- 시각적 편집이 쉬워서 초보자도 사용 용이<br/>- 다양한 템플릿과 아이콘 제공	- 팀 협업에 특화(실시간 편집, 댓글, 공유)<br/>- 시각적으로 깔끔한 다이어그램	- 시퀀스 다이어그램에만 집중하므로 러닝커브가 낮음<br/>- 간단한 UI/UX
단점	- 텍스트 DSL에 대한 일정 수준의 학습 필요<br/>- 시각 편집 기능은 제한적	- 단일 DSL에 따라 표현 범위가 제한<br/>- 필요에 따라 여러 DSL을 혼합해야 하는 경우 복잡도 상승	- 변경 시 수동 편집필수<br/>- 다이어그램이 많아지면 파일 관리가 번거로울 수 있음	- 유료 플랜으로 업그레이드하지 않으면 용량·사용자 수 제한<br/>- 텍스트 기반 버전 관리는 미흡	- 지원 다이어그램 유형이 제한적<br/>- 큰 프로젝트에는 활용 범위 제한

---

활용예시

• 개발 현장 사례: 결제 로직처럼 자주 바뀌는 시스템을 Kroki로 문서화했더니, “다이어그램만 따로 업데이트하면 되니 빠르다”라는 팀 피드백이 다수 있었습니다.
• 문제 해결 과정: 버그가 발생했을 때, 코드와 시퀀스 다이어그램이 일치한다면, 문제 구간을 빠르게 찾아낼 수 있습니다. 실제로 코드-다이어그램이 함께 Git에서 버전 관리되면서 디버깅 시간이 줄었다는 보고가 있었습니다.
• 개인 경험 & 통찰: 블로그 글을 여러 편 쓰면서, 다이어그램은 프로젝트 규모가 커질수록 꼭 필요한 요소라는 점을 깨달았습니다. 그 과정에서 Draw.io나 Lucidchart도 사용해봤지만, 결국 코드 기반의 정확한 버전 관리가 필요한 상황에서 Kroki가 탁월한 효율을 보인다고 느꼈습니다.

위에서 설명한 Kroki와 유사 솔루션들을 비교해보시고, 만약 다음과 같은 요구사항이 있다면 꼭 시도해보세요.

• 지속적 변경이 필요한 다이어그램 문서화
• 버전 관리와 자동화가 중요한 환경
• 텍스트로 문서를 관리해, 누구나 협업하며 최신 버전을 즉시 확인하고 싶은 팀

실제 프로젝트에 Kroki를 적용해, 다이어그램 문서화의 생산성을 높이는 경험을 해보시길 권장드립니다.

 

로컬 설치 및 테스트

docker run

docker run -p8000:8000 yuzutech/kroki

docekr-compose.yml

services:
  kroki:
    image: yuzutech/kroki
    depends_on:
      - mermaid
      - bpmn
      - excalidraw
    environment:
      - KROKI_MERMAID_HOST=mermaid
      - KROKI_BPMN_HOST=bpmn
      - KROKI_EXCALIDRAW_HOST=excalidraw
    ports:
      - "8000:8000"
  mermaid:
    image: yuzutech/kroki-mermaid
    expose:
      - "8002"
  bpmn:
    image: yuzutech/kroki-bpmn
    expose:
      - "8003"
  excalidraw:
    image: yuzutech/kroki-excalidraw
    expose:
      - "8004"

컨네이어 올린 후 접속

 

기본 사용법

https://docs.kroki.io/kroki/setup/usage/

Usage :: Kroki Documentation

Post방식으로 호출해야 하는터라 매우 불편하여 간단하게 웹페이지를 만들었습니다.

kroki-live-editor.html

0.02MB

인터넷이 되지 않는 환경에서 해야 한다면.

kroki-web.html

0.01MB