Deployment Landscape¶
Code To UML được phát hành thành nhiều artifact và chạy trên các môi trường khác nhau. Tài liệu này mô tả artifact nào được đưa tới đâu và ranh giới thực thi của từng phần sau khi triển khai.
1. Bản đồ triển khai¶
| Phần | Artifact phát hành | Đích triển khai | Ranh giới thực thi |
|---|---|---|---|
| Gateway và Java core | Image từ Dockerfile.render |
Docker Compose trên Production VPS | Gateway runtime container |
| Pydia sandbox | Image từ Dockerfile.pydia |
Docker Compose trên Production VPS | Container biệt lập, không có IP network |
| Playground | Web assets trong Gateway runtime image | Gateway /playground trên Production VPS |
Browser sau khi tải assets |
| VS Code extension | VSIX | Máy người dùng | VS Code extension host |
| GitLab document integration | Custom GitLab image | Self-managed GitLab | GitLab Markdown pipeline |
| GitLab MR browser extension | Manifest V3 package | Máy người dùng | Chromium content script và service worker |
| Confluence integration | Forge app và Custom UI resource | Atlassian Forge / Confluence Cloud | Forge functions và browser sandbox |
| Website tài liệu | Static website trong site/ |
Cloudflare Workers static assets | Browser sau khi tải website |
Sơ đồ chỉ thể hiện artifact nằm trong môi trường nào sau khi triển khai. Gateway runtime và Pydia là hai container độc lập trên VPS. Website, GitLab document integration và Confluence integration thuộc các nền tảng hosting tương ứng; VS Code extension và MR extension chạy trên máy người dùng.
2. Gateway runtime trên Production VPS¶
Production dùng compose.vps.yml. Khi thay đổi ảnh hưởng deployment được đưa
vào nhánh main, workflow GitHub Actions kiểm tra image, tạo archive từ đúng
commit, chuyển archive lên VPS và gọi deployment command trên host với commit
SHA tương ứng. Workflow hiện không chuyển image qua container registry;
compose.vps.yml khai báo build context và hai runtime image từ source trên host.
TLS được kết thúc bởi ingress do host quản lý. Gateway container lắng nghe ở
port 10000, còn host chỉ bind
127.0.0.1:${PORT:-10000}:10000. Application port vì vậy không được publish
trực tiếp ra Internet.
Pydia được triển khai trong container riêng, không có IP network. Gateway kết
nối tới Pydia qua Unix socket trong named volume pydia-runtime; container
Pydia không nhận traffic từ TLS ingress.
3. Gateway runtime ở local¶
Local development dùng compose.code-to-uml.yml để chạy cùng ranh giới Gateway
runtime và Pydia trên máy phát triển.
| Thành phần | Cấu hình local |
|---|---|
| Gateway runtime | Build từ Dockerfile.render; container port 10000 được map thành localhost:8000 |
| Pydia sandbox | Build từ Dockerfile.pydia; không có IP network và dùng chung Unix socket volume |
Môi trường này phục vụ phát triển và kiểm tra Gateway runtime trước khi đưa thay đổi lên Production VPS. Các ứng dụng tích hợp vẫn chạy trong môi trường riêng.
4. VS Code extension¶
VS Code extension được đóng gói thành VSIX từ vscode-extension/. CI chạy test,
tạo VSIX và lưu package thành workflow artifact. Người dùng cài VSIX vào VS Code;
extension chạy trong extension host và kết nối tới Gateway deployment qua HTTPS.
Java core và Gateway không được bundle vào VSIX.
5. GitLab MR browser extension¶
Browser extension được build từ browser-extension/ thành Manifest V3 package.
Sau khi cài trên Chromium, người dùng bấm biểu tượng extension để cấp quyền tạm
thời trên tab GitLab hiện tại. Service worker dùng activeTab và scripting để
đưa content script vào trang merge request và thực hiện các tác vụ nền.
Manifest không giữ quyền truy cập cố định tới GitLab host; một package có thể
dùng trên GitLab.com và GitLab self-managed qua HTTPS. Gateway host vẫn nằm
trong host_permissions. Package không chứa Gateway runtime và không được triển
khai lên GitLab server.
6. GitLab self-managed¶
7. Confluence Forge¶
Confluence integration được phát hành dưới dạng Forge app từ
confluence-code-to-uml-poc/, triển khai lên Atlassian Forge / Confluence Cloud
bằng forge deploy rồi forge install -p Confluence — không đi qua Production
VPS hay workflow deploy nhánh main. Artifact gồm hai phần chạy ở hai ranh giới
khác nhau. Backend Forge functions chạy trên Forge managed runtime
(nodejs24.x): một resolver (renderDiagram cho trang đã publish, previewDiagram
cho live preview trong editor) và một page-event handler tự chuyển code block hợp
lệ thành macro khi trang được tạo hoặc cập nhật. Custom UI resources là hai
bundle Vite tự chứa — static/code-to-uml/dist (view macro) và
static/code-to-uml/dist/editor (config editor) — Forge phục vụ mỗi bundle như một
resource độc lập, chạy trong iframe sandbox của Forge trên browser.
Browser không gọi encoded GET công khai và không nhận rendering token. Custom UI
chỉ invoke resolver; resolver đọc diagram source từ macro context do Forge cấp,
validate, rồi gửi POST /{renderer}/svg có xác thực tới Gateway qua HTTPS. Egress
này được khai báo trong manifest.yml tại permissions.external.fetch.backend
(allow-list đúng Gateway host). Bearer token là encrypted Forge variable
RENDER_API_TOKEN, chỉ tồn tại ở backend runtime — không nằm trong page ADF, macro
config, browser storage, URL hay frontend JavaScript. Đổi Gateway host phải cập
nhật cả RENDER_BASE_URL lẫn backend fetch allow-list rồi deploy lại; đổi scope
hoặc manifest permission cần forge install --upgrade, và Forge chỉ áp dụng thay
đổi biến sau khi deploy.
Resolver giới hạn source 200 KiB, SVG 4 MiB, timeout 25 giây, bắt buộc content type
image/svg+xml và loại bỏ active content (script, event handler, embed, XXE entity,
javascript:/file: URI) trước khi Custom UI hiển thị SVG qua Blob URL trong
<img> sandbox. App giữ scope đọc và ghi page vì auto-convert ADF cần chúng; Pydia
bị chặn mặc định và chỉ bật khi ALLOW_PYDIA=true cùng numeric space ID nằm trong
PYDIA_ALLOWED_SPACE_IDS. Forge app không chứa Java core, Gateway runtime hay
rendering token — việc render vẫn dựa vào Gateway (và Pydia sandbox) đã triển khai ở
phần 2.
8. Website tài liệu¶
Website được build độc lập với Gateway runtime từ mkdocs.yml, docs/ và
requirements-docs.txt. MkDocs tạo static website trong site/; Wrangler phát
hành thư mục này lên Cloudflare Workers theo wrangler.jsonc.
Kroki plugin tạo image URL từ server đặt bằng KROKI_SERVER_URL; nếu biến này
không được truyền, build dùng URL mặc định trong mkdocs.yml. URL đó được ghi
vào HTML, vì vậy browser của người đọc gọi Gateway qua encoded GET khi tải
diagram. Đổi Gateway URL, Markdown, theme hoặc stylesheet đều cần build lại
site/ và phát hành lại static assets.
Website artifact không chứa Java core, Gateway hoặc rendering token. site_url
trong mkdocs.yml xác định canonical URL và sitemap của website được phát hành.