Thiết lập từng bước.
Sẵn sàng triển khai.

Một mã nguồn backend NestJS phục vụ hai ứng dụng Angular độc lập. Cùng danh tính Keycloak, khác phạm vi công việc và client đăng nhập.

Dùng Docker Keycloak orkestr-e2e, PostgreSQL local, Local Git sandbox và AI local-deterministic. Không cần tài khoản provider thật.

Các lệnh bên dưới chạy từ thư mục gốc repository orkestr/. Khối sao chép file dùng PowerShell; trên macOS/Linux thay Copy-Item bằng cp.

1. Cài dependency và tạo cấu hình local

   Chỉ sao chép khi chưa có backend/.env.local; giữ cấu hình cá nhân đã điền.

   PowerShell · repo root

   npm --prefix backend ci
   npm --prefix frontend ci
   Copy-Item backend/.env.example backend/.env.local

   Kiểm tra CORS_ORIGINS chứa cả hai origin. Mặc định backend dùng realm local ở bước tiếp theo.

   backend/.env.local

   CORS_ORIGINS=http://localhost:4200,http://localhost:4300

2. Bật database, Keycloak và chạy migration

   Terminal · repo root

   npm --prefix backend run db:up
   npm --prefix frontend run auth:up
   npm --prefix backend run migration:run

   PostgreSQL ở 127.0.0.1:55440; Keycloak ở http://127.0.0.1:18080. Realm và user test được nhập từ frontend/e2e/keycloak/realm-orkestr-e2e.json. Lấy thông tin user từ fixture local; không dùng tài khoản test trên dev/main.

3. Chạy ba tiến trình backend

   Mở ba terminal riêng. Chờ API build xong rồi khởi động worker và runner.

   Terminal 1 · API

   npm --prefix backend run start:dev

   Terminal 2 · Worker

   npm --prefix backend run start:worker

   Terminal 3 · Runner

   npm --prefix backend run start:runner

4. Mở Portal và Console

   Terminal 4 · Portal

   npm --prefix frontend run start:portal

   Terminal 5 · Console

   npm --prefix frontend run start:console

   Portal · localhost:4200 để làm việc theo project; Console · localhost:4300 dành cho user có orkestr-admin. Nếu volume Keycloak cũ chưa có hai client mới, cập nhật realm local theo cấu hình client rồi đăng nhập lại; không xóa volume đang chứa định danh cần giữ.

5. Kiểm chứng một luồng hoàn chỉnh

   Mở API health, xác nhận database: up. Trên Portal: tạo project → thêm Local Git sandbox → tạo PRD/Story → Publish → Create Technical Tasks → Analyze Codebase → Approve plan → Execute → Delivery report.

   Trên Console: đăng nhập bằng admin, mở tổng quan và cấp provider/model cho project test. Việc cấp model không chạy inference.

$env:ORKESTR_POSTGRES_PORT = '15440'
npm --prefix backend run db:up

Portal, Console và backend vẫn chạy trên máy bạn; chỉ đăng nhập qua auth-dev.cloudsolution.vn, realm orkestr.

1. Hoàn tất cài dependency và PostgreSQL ở bước local. Tạo user trong realm orkestr; bật Email verified.
2. Thêm origin localhost vào đúng client dev: Portal cổng 4200, Console cổng 4300. Xem bảng client. Không thêm localhost vào client production.
3. Tạo .env.poc ở root, giữ local database và điền issuer/JWKS của auth-dev. Không dùng .env.dev có database remote cho POC.

Copy-Item .env.poc.example .env.poc

CORS_ORIGINS=http://localhost:4200,http://localhost:4300
OIDC_ISSUER=https://auth-dev.cloudsolution.vn/realms/orkestr
OIDC_AUDIENCE=orkestr-api
OIDC_JWKS_URI=https://auth-dev.cloudsolution.vn/realms/orkestr/protocol/openid-connect/certs
OIDC_ALLOWED_ALGORITHMS=RS256

Chạy migration một lần, sau đó chạy từng lệnh start:* trong terminal riêng. Dừng các process local cũ trước để giải phóng cổng và tránh xử lý queue bằng sai ENV.

npm --prefix backend run migration:poc

npm --prefix backend run start:poc
npm --prefix backend run start:worker:poc
npm --prefix backend run start:runner:poc
npm --prefix frontend run start:portal:poc
npm --prefix frontend run start:console:poc

ENV backend dùng chung cho API, worker và runner. Angular nhận cấu hình công khai khi build; không tự đọc file ENV backend.

Domain API dev là cấu hình dự kiến cho mô hình tách ứng dụng; cần DNS, TLS và backend tương ứng. Domain main và Keycloak production phải được chốt trước release.

CORS_ORIGINS=https://orkestr-portal-dev.aila.vn,https://orkestr-console-dev.aila.vn

Chuẩn bị một realm, hai public client cho trình duyệt và một audience cho API. Tên trường có thể khác nhẹ theo phiên bản Keycloak.

1. Tạo realm và kiểm tra discovery

   Trong Keycloak Admin Console của auth-dev.cloudsolution.vn, tạo hoặc chọn realm orkestr, bật Enabled. Dùng user có email đã xác minh; có thể tắt self-registration nếu quy trình tổ chức dùng tài khoản được cấp.

   Mở OIDC discovery của realm dev. issuer phải đúng chuỗi dưới đây; jwks_uri là nguồn khóa công khai mà backend dùng.

   Issuer · dev / POC

   https://auth-dev.cloudsolution.vn/realms/orkestr

   Docker local dùng realm orkestr-e2e. Main dùng Keycloak production riêng đã được chốt, không trỏ mặc định về auth-dev.

2. Tạo client audience orkestr-api

   Vào Clients → Create client, chọn OpenID Connect, Client ID orkestr-api. Tắt Client authentication, Standard flow, Direct access grants, Implicit flow và Service accounts nếu có. Client này chỉ đại diện cho audience, không có redirect URI hay client secret dùng trong Orkestr.

3. Tạo riêng Portal và Console

   Lặp lại Clients → Create client hai lần với ID orkestr-portal và orkestr-console. Cả hai dùng cấu hình chung:

   Thiết lập	Giá trị
   Client type / protocol	OpenID Connect
   Client authentication	Off — public client, không tạo secret
   Standard flow	On — Authorization Code
   Direct access grants / Implicit / Service accounts	Off
   Advanced → Proof Key for Code Exchange Code Challenge Method	S256
   Default client scopes	basic, profile, email, roles (tên scope theo realm/version)

   CLIENT 01

   orkestr-portal

   Workspace của thành viên project

   Root URL / Home URL	https://orkestr-portal-dev.aila.vn
   Valid redirect URIs	https://orkestr-portal-dev.aila.vn/*
   Valid post logout redirect URIs	https://orkestr-portal-dev.aila.vn/*
   Web origins	https://orkestr-portal-dev.aila.vn

   Thêm localhost khi dùng POC

   Thêm các dòng dưới đây vào client orkestr-portal trên realm dev; giữ nguyên domain dev đã có.

   Valid redirect URIs

   http://localhost:4200/*

   Valid post logout redirect URIs

   http://localhost:4200/*

   Web origins

   http://localhost:4200

   CLIENT 02

   orkestr-console

   Quản trị hệ thống

   Root URL / Home URL	https://orkestr-console-dev.aila.vn
   Valid redirect URIs	https://orkestr-console-dev.aila.vn/*
   Valid post logout redirect URIs	https://orkestr-console-dev.aila.vn/*
   Web origins	https://orkestr-console-dev.aila.vn

   Thêm localhost khi dùng POC

   Thêm các dòng dưới đây vào client orkestr-console trên realm dev.

   Valid redirect URIs

   http://localhost:4300/*

   Valid post logout redirect URIs

   http://localhost:4300/*

   Web origins

   http://localhost:4300

   Lưu từng client. Wildcard /* chỉ ở phần path của đúng origin; không dùng * cho toàn bộ URI hoặc Web origins. localhost và 127.0.0.1 là hai origin khác nhau: mở frontend bằng đúng localhost.

   Main tạo lại hai client trong realm production với domain main đã xác nhận. Không mang origin dev/localhost sang production. Local Docker dùng cùng hai client ID, nhưng chỉ các origin local trong realm orkestr-e2e.

4. Thêm audience mapper cho cả hai client

   Trong từng client, mở Client scopes → [client-id]-dedicated → Add mapper → By configuration → Audience. Nếu giao diện khác, tìm dedicated client scope của client rồi thêm protocol mapper loại Audience.

   Name	orkestr-api audience
   Included Client Audience	orkestr-api
   Add to access token	On
   Add to ID token	Off
   Add to token introspection	On nếu phiên bản có tùy chọn này

   Access token từ cả Portal và Console phải có aud chứa orkestr-api. Backend không dùng client ID frontend làm audience.

5. Cấp role quản trị và kiểm claim

   Vào Realm roles → Create role, tạo orkestr-admin. Mở user quản trị → Role mapping → Assign role → chọn realm role này. Giữ client scope roles là default; nếu realm giới hạn role scope mappings, cho phép role xuất hiện trong scope của client cần dùng.

   Đăng xuất và đăng nhập lại Console. Access token phải có realm_access.roles chứa orkestr-admin. Backend xác minh JWT trước khi trả quyền tại GET /api/v1/me; kết quả cần có user.systemAdmin: true.

   Project Owner không đồng nghĩa System Admin.

   Role trên Keycloak mở quyền quản trị toàn hệ thống. Membership và role từng project vẫn do Orkestr kiểm trong database; không thêm realm role để thay cho lời mời project.

6. Kiểm đăng nhập và đăng xuất ở cả hai ứng dụng

   Kiểm token tại máy của bạn: sub có giá trị, iss đúng realm, aud chứa orkestr-api, email_verified đúng, role admin chỉ cấp cho user phù hợp. Không gửi access token lên công cụ web công khai.

   Mở Portal, đăng nhập và kiểm API. Mở Console, kiểm user admin và một user không có role. Đăng xuất từng ứng dụng, xác nhận quay về đúng origin và không có lỗi post_logout_redirect_uri.

Tên và ý nghĩa các trường đối chiếu theo Keycloak Server Administration Guide. Cấu hình ứng dụng ở đây dùng hai public client riêng; không dùng client cũ orkestr-web cho hai build mới.

Triển khai Portal, Console và Guide thành ba static site; API chạy trên host backend. Worker và runner không cần domain public.

Build hai ứng dụng

Từ repository root, build dev riêng từng ứng dụng. Kiểm API base, Keycloak URL/realm/client ID và URL liên kết qua lại trước khi upload.

npm --prefix frontend run build:portal:dev
npm --prefix frontend run build:console:dev

npm --prefix frontend run build:apps build cả hai target. Với main, cần cấu hình production đã điền Keycloak và domain thực; không xuất bản build auth-dev dưới domain production.

1. Backend: chuẩn bị host Node/Git/Docker, database và storage; chạy migration. Quản lý API, worker, runner bằng supervisor/service manager. Reverse proxy hỗ trợ streaming SSE, không buffer log stream và có timeout phù hợp.
2. Frontend: upload mỗi output vào đúng site. Cấu hình SPA fallback về index.html cho route ứng dụng: Portal /projects, /p/:slug/*; Console /overview, /ai-connections, /project-access, /access.
3. DNS & TLS: gắn custom domain trên hosting trước, thêm A/AAAA hoặc CNAME đúng target do hạ tầng cung cấp, chờ chứng chỉ HTTPS hợp lệ. Không tự đoán IP hay dùng hostname API làm target của static site.
4. OIDC & CORS: lưu đúng origin trong hai client Keycloak và CORS_ORIGINS của API. Kiểm API base đầy đủ https://orkestr-api-dev.aila.vn/api/v1.
5. Guide: chọn thư mục publish guide, không cần lệnh build. Gắn orkestr-guide.aila.vn. Host hỗ trợ _headers sẽ đọc chính sách cache/security đi kèm; host khác cấu hình header tương đương.