Deployment Topology¶

Rendering service chạy trên Production VPS. VS Code và browser extension được cài trên workstation; GitLab Markdown Integration được đóng gói trong custom GitLab CE image; Confluence Forge Integration được deploy riêng trên Atlassian Forge; website tài liệu được phát hành lên Cloudflare. Các thành phần cần render kết nối tới Gateway qua HTTPS.

Mô hình triển khai¶

Kroki

Production VPS chứa public endpoint và rendering runtime; Pydia chạy trong sidecar có sandbox riêng. Các extension, integration và static assets được build từ repository rồi lần lượt phát hành dưới dạng VSIX, browser package, custom GitLab image, Forge app hoặc static site.

Production VPS¶

compose.vps.yml chạy rendering runtime và Pydia trong hai container. TLS ingress nhận hai loại request public; rendering container bind 127.0.0.1:${PORT:-10000}:10000. Gateway, Java Core và browser companions cùng nằm trong rendering container và giao tiếp qua loopback process boundaries.

Volume pydia-runtime mang Unix socket giữa hai container. Pydia sử dụng OCI runtime runsc-pydia, network_mode: none và chỉ nhận render job qua socket. Cách bố trí này đặt Python execution, resource limits và sandbox policy tách khỏi public API process.

Extension trên workstation¶

VS Code Extension được đóng gói thành VSIX và chạy trong Extension Host. GitLab MR Browser Extension được phát hành dưới dạng Manifest V3 package; content script làm việc trong tab GitLab, còn service worker giữ Gateway token. Browser của người đọc tải trang từ GitLab, Confluence hoặc Cloudflare rồi gọi encoded GET khi trang chứa sơ đồ nhúng.

Triển khai trên các nền tảng¶

Self-managed GitLab được triển khai bằng custom GitLab CE image có Markdown filter của Krokup. Filter chuẩn hóa fence params trước khi GitLab tạo encoded image URL; rendering vẫn diễn ra tại Production VPS.

Confluence integration là Forge app có source, test và manifest trong repository. Nó không được deploy bởi workflow rendering service trên main. Mỗi Forge environment và Confluence site cần được deploy, install và kiểm chứng riêng bằng Forge CLI.

Khi app được cài, Custom UI phục vụ editor và viewer trong browser iframe; Resolver cùng Page Event chạy trên Forge managed runtime. Gateway token được lưu trong encrypted variable của backend. Forge KVS lưu tạm SVG của trang đã publish theo renderer và source hash; storage này do Atlassian quản lý và không nằm trên Production VPS.

MkDocs build docs/ thành static site/, sau đó Wrangler phát hành artifact lên Cloudflare. Website chứa HTML, assets và encoded image URL; rendering tiếp tục được phục vụ từ Production VPS.

Quy trình build, rollout, rollback và cấu hình môi trường nằm trong Operations. Môi trường local dùng compose.code-to-uml.yml, map Gateway tại localhost:8000 và giữ Pydia trong container riêng để gần với topology production.