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, content script chạy trong trang merge request còn
service worker thực hiện các tác vụ nền của extension.
GitLab host được giới hạn bởi matches; GitLab và Gateway hosts được giới hạn
bởi host_permissions trong manifest.json. Thay đổi một trong các host này cần
tạo lại package với manifest tương ứng. 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¶
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.