Deployment Topology¶

Rendering service chạy trên Production VPS. VS Code và browser extension được cài trên workstation; GitLab Markdown Integration nằm trong custom GitLab image; Confluence app chạy 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 sử dụng custom image chứa GitLab Markdown Integration. Thành phần này chạy trước MarkdownFilter trong GitLab Banzai pipeline, chuyển tham số trên code fence thành directive và để GitLab tạo encoded image URL trong HTML.

Confluence integration được deploy dưới dạng Forge app. 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.