Phiên bản: Next

Cài đặt — chọn chế độ & chạy lần đầu

Đối tượng: người dựng hệ thống (dev tự chạy + sysadmin deploy). Nguồn chi tiết: INSTALLATION.md trong repo (1600+ dòng) — trang này là bản điều hành rút gọn: chọn mode → lệnh chạy → xác minh. Tham chiếu biến đầy đủ: Biến môi trường.

Chọn 1 trong 3 chế độ

	A. DEV-LITE	A2. DEV FULL-STACK	B. PRODUCTION
Mục đích	Sửa code, hot reload	Kiểm thử tích hợp thật	Chạy thật đa team
Chạy	`dev.sh deps up` + `npm run dev` (2 process host)	`dev.sh up` (11 containers)	`docker compose -f docker-compose.prod.yml up -d`
Danh tính	`AGENTBOARD_DEV_IDENTITY=1` (mọi request = `owner`)	nginx tiêm `X-Forwarded-Email`	Cloudflare Access JWT
Phân quyền	bypass	thật, fail-closed	thật, fail-closed
Khởi động	~40 giây	~5–10 phút lần đầu	theo hạ tầng

A. DEV-LITE
A2. DEV FULL-STACK
B. PRODUCTION

./scripts/dev.sh deps up — 8 backing container (Postgres Board, Arkon đủ 7).
npm run dev trong ai-agent-board (nhớ npm run build:shared lần đầu).
packages/server/.env: AGENTBOARD_DEV_IDENTITY=1, DATABASE_URL (Postgres :5434), ARKON_API_URL, ARKON_ENCRYPTION_KEY, ARKON_SSO_SHARED_SECRET.
Cài ≥1 agent CLI (claude / copilot / codex…) và đăng nhập — hoặc AGENTBOARD_FAKE_AGENT=1 để demo không cần key.

./scripts/dev.sh init — sinh ARKON_ENCRYPTION_KEY, ARKON_SSO_SHARED_SECRET, ARKON_POSTGRES_PASSWORD, ARKON_REDIS_PASSWORD, MINIO_SECRET_KEY.
./scripts/dev.sh up — build + chạy 11 containers (NODE_ENV=production, fail-fast y prod; --real-agent để nhúng CLI thật).
./scripts/dev.sh member <spaceId> <email> viewer — thử RBAC thật. Đây là môi trường chạy Nghiệm thu.

Chuẩn bị /opt/agentjira/.env (chmod 600) + arkon/.env.docker — đủ secret bắt buộc (xem Vận hành hằng ngày).
Chạy check-placeholder-secrets.cjs — fail build nếu còn giá trị ví dụ.
docker compose -f docker-compose.prod.yml pull && up -d --remove-orphans (stack app, 10 services).
docker compose -f docker-compose.docs.yml pull && up -d (site tài liệu này, :8082 — stack riêng, xem § Deploy docs độc lập).
Seed owner đầu tiên (AGENTBOARD_BOOTSTRAP_OWNERS) + nhập embedding key vào Arkon.
Chạy 10 điều kiện go-live ở dưới trước khi mở cho user.

Hai quy tắc an toàn

Không bao giờ chạy cấu hình DEV trên máy reachable từ mạng. Server từ chối boot khi AGENTBOARD_DEV_IDENTITY đi cùng NODE_ENV=production.
A (DEV-LITE) không kiểm thử được phân quyền — mọi thứ RBAC/Human Gate/membership chỉ kiểm chứng được ở A2 hoặc B.

Yêu cầu tiên quyết

OS macOS/Linux/Windows (WSL2); Docker + Compose; Node 22+ (dev); ≥1 agent CLI đã đăng nhập.
Cổng trống: 8080 (API loopback), 8081 (Board), 5055 (Arkon API), 3119 (Arkon UI), 9002/9003 (MinIO), 8082 (site tài liệu này).
Ba biến bắt buộc mọi môi trường container: ARKON_SSO_SHARED_SECRET = SSO_SHARED_SECRET, ARKON_ENCRYPTION_KEY, MINIO_ENDPOINT=minio:9000 (không dấu _).

Xác minh sau khởi chạy

# 8 backing container healthy (dev-lite) / 11 containers (A2/prod)
docker compose ps   # tất cả healthy/running

# Arkon tự báo hạ tầng
curl http://localhost:5055/health
# → {"status":"healthy","services":{"database":"healthy","redis":"healthy","minio":"healthy"}}

# Board sống + không còn preflight bị bỏ qua
curl -fsS http://127.0.0.1:8080/api/health
docker compose logs agentjira_server | grep -i preflight

# Realtime: mở UI → DevTools → Network → WS phải 101 connected (không 403)

Cờ 0B/0C — 12 cờ, mặc định TẮT

Tắt lại một cờ là rollback trọn vẹn tính năng đó, không cần đổi image. Truthy: 1 / true / on / yes — còn lại là TẮT. Bật từng cái một, đừng bật cả 12 ở lần deploy đầu (thứ tự gợi ý: Vận hành hằng ngày).

# 8 cờ 0B + 4 cờ 0C + 2 nhịp (reconciler RBAC, sweep retro; rỗng = 15 phút)
AGENTBOARD_ARKON_SOURCES= AGENTBOARD_WIKI_LINKS= AGENTBOARD_UNIFIED_REVIEW_QUEUE=
AGENTBOARD_WIKI_DEEP_UI= AGENTBOARD_ARKON_USER_TOKENS= AGENTBOARD_ARKON_RBAC_SYNC=
AGENTBOARD_ARKON_PERSONA_TOKENS= AGENTBOARD_ARKON_MCP= AGENTBOARD_ARKON_RBAC_RECONCILE_MS=
AGENTBOARD_COMMAND_PALETTE= AGENTBOARD_MENTION_SUBTASK= AGENTBOARD_AUTO_RETRO=
AGENTBOARD_AUTO_RETRO_SWEEP_MS= AGENTBOARD_WS_TOPICS=

Cờ trong .env mà tính năng không đổi → soi container, không soi file

Biến phải có trong environment: của compose mới tới được process. Sau mọi sửa env:

docker exec agentjira_server printenv | grep AGENTBOARD_
curl -s localhost:8081/api/features

Bẫy riêng AGENTBOARD_WS_TOPICS: bật cờ này thì AGENT_BOARD_PUBLIC_URL bắt buộc phải khai và host của nó phải nằm trong ALLOWED_HOSTS, nếu không server từ chối boot.

Hai file env Arkon phải khớp tay

4 service Arkon (migrator, api, 2 worker) lấy toàn bộ cấu hình từ arkon/.env.docker (không có environment:) — production không có lệnh render cả hai file cùng lúc như dev.

`/opt/agentjira/.env` (cấu hình server)	`arkon/.env.docker` (cấu hình Arkon)
`ARKON_POSTGRES_USER` / `_PASSWORD` / `_DB`	`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` + `DATABASE_URL`
`ARKON_REDIS_PASSWORD`	`REDIS_PASSWORD`
`MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`	`MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`
`ARKON_SSO_SHARED_SECRET`	`SSO_SHARED_SECRET`

Lệch một giá trị là chết lúc chạy (arkon_migrator: password authentication failed), không báo lúc cấu hình. Kiểm trước up -d:

node ai-agent-board/scripts/check-env-consistency.cjs --env .env.prod
node ai-agent-board/scripts/check-placeholder-secrets.cjs

Production tuyệt đối không down -v

Postgres chỉ áp POSTGRES_PASSWORD ở lần khởi tạo đầu — volume cũ giữ mật khẩu cũ, khiến .env mới đúng vẫn fail y như sai. Trên production: sửa .env cho khớp volume, hoặc đổi mật khẩu bên trong Postgres. Chi tiết: RUNBOOK.md §2.1.

Deploy docs độc lập (stack riêng `:8082`)

Site này chạy file compose riêng docker-compose.docs.yml (1 service docs, site tĩnh, không secret, không DB) — deploy docs không restart 10 services app, và push chỉ sửa docs thì CD bỏ qua rebuild 4 images app.

# Tay (server /opt/agentjira):
docker compose -f docker-compose.docs.yml pull
docker compose -f docker-compose.docs.yml up -d
curl -fsS http://127.0.0.1:8082/   # verify

# Rollback docs = up lại tag cũ (mỗi build CD gắn tag sha, xem cd.yml job deploy-docs)
docker compose -f docker-compose.docs.yml up -d  # sau khi pull tag cũ về

Tự động: merge vào main mà đổi docs-site/** → job build-and-push-docs build-push image → job deploy-docs SCP file compose + pull/up chỉ file docs + verify :8082. Không --remove-orphans toàn stack, không prune image app.

Lần deploy đầu sau tách

Chạy up -d --remove-orphans với docker-compose.prod.yml 1 lần cuối để dọn container agentjira_docs cũ (vốn thuộc project app), rồi mới up file docs riêng — nếu không sẽ có 2 container cùng tên/phạm vi port 8082.

10 điều kiện go-live (production)

Gate contract + E2E xanh (587 contract + 222 E2E pass, exit 0).
Gate trên PostgreSQL thật, 0 test skipped.
Gate Arkon xanh (466 passed).
Toàn bộ service healthy + UI + WebSocket 101.
PENTEST Human Gate → 403 (header giả, service token). Không 403 → DỪNG DEPLOY.
PENTEST RBAC → 403 (viewer approve; người lạ GET task).
Smoke agent thật: task → result.json hợp lệ → verdict → human approve → merge --no-ff OK.
Smoke Arkon end-to-end: Space mới → Department + Wiki Home → tab Wiki → .board/wiki/**.
Schema additive-only + test ratchet không giảm.
Không secret nào còn giá trị placeholder.

Đọc tiếp: Vận hành & backup · Nghiệm thu · Vận hành hằng ngày.

Chọn 1 trong 3 chế độ​

Yêu cầu tiên quyết​

Xác minh sau khởi chạy​

Cờ 0B/0C — 12 cờ, mặc định TẮT​

Hai file env Arkon phải khớp tay​

Deploy docs độc lập (stack riêng :8082)​

10 điều kiện go-live (production)​