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

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

A2. DEV FULL-STACK

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

B. PRODUCTION

1. 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).
2. Chạy check-placeholder-secrets.cjs — fail build nếu còn giá trị ví dụ.
3. docker compose -f docker-compose.prod.yml pull && up -d --remove-orphans.
4. Seed owner đầu tiên (AGENTBOARD_BOOTSTRAP_OWNERS) + nhập embedding key vào Arkon.
5. 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)

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

1. Gate contract + E2E xanh (255 contract + 198 E2E pass, exit 0).
2. Gate trên PostgreSQL thật, 0 test skipped.
3. Gate Arkon xanh (59 passed).
4. Toàn bộ service healthy + UI + WebSocket 101.
5. PENTEST Human Gate → 403 (header giả, service token). Không 403 → DỪNG DEPLOY.
6. PENTEST RBAC → 403 (viewer approve; người lạ GET task).
7. Smoke agent thật: task → result.json hợp lệ → verdict → human approve → merge --no-ff OK.
8. Smoke Arkon end-to-end: Space mới → Department + Wiki Home → tab Wiki → .board/wiki/**.
9. Schema additive-only + test ratchet không giảm.
10. 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.