Triển khai & vận hành

Chạy Gommo Developer như một API service. Docs và portal deploy riêng.

Layout đề xuất

Service	Domain	Cách
API	api.yourdomain.com	Docker / Railway / Fly
Docs	docs.yourdomain.com	VitePress — Vercel / GitHub Pages
Portal	/vi/portal/ trên API	Dev only; prod tắt trừ GATEWAY_PORTAL=true

Không commit .env, merchant token, admin key.

Dev local

cp .env.example .env
npm install
npm run dev            # :3001
npm run docs:dev       # :5173

curl http://localhost:3001/health

Health check

GET /health

{
  "success": true,
  "data": {
    "ok": true,
    "merchantConfigured": true,
    "adminConfigured": true
  }
}

Railway / Fly / k8s: probe GET /health.

Docker

docker build -t gommo-developer .
docker run --rm -p 3001:3001 --env-file .env gommo-developer

Platform inject PORT.

Self-host API modes (nâng cao)

Mode B (/gateway/*) và Mode C (proxy path) tùy chọn khi deploy repo này. Không bắt buộc tích hợp Gommo — app production gọi Gommo public API trực tiếp (Mode A).

Doc	Mục đích
Integration modes	So sánh Mode A / B / C
Endpoint map	Bảng path cross-mode
Choosing a mode	Cây quyết định

Trang này gom dưới Deploy trên sidebar (ẩn khỏi Models & routing). Bật lại nav mặc định: thêm link trong docs/.vitepress/config.ts → modelsRoutingInDocs*.

Railway

1. Deploy from GitHub.
2. Variables từ .env.example.
3. Domain api.yourdomain.com.
4. Health path /health.

Fly.io

fly launch --no-deploy
fly secrets set GOMMO_ACCESS_TOKEN=... ADMIN_API_KEY=... GOMMO_API_DOMAIN=<registration-domain>
fly secrets set GATEWAY_CORS_ORIGIN=https://your-frontend.example.com
fly deploy
fly certs add api.yourdomain.com

Env production

Biến	Mục đích
PORT	Platform inject
NODE_ENV	production — portal tắt mặc định
GOMMO_API_DOMAIN	Domain đăng ký
GOMMO_ACCESS_TOKEN	Merchant — server only
ADMIN_API_KEY	/vi/admin/*
GATEWAY_CORS_ORIGIN	Origin browser, phân cách dấu phẩy
GATEWAY_PORTAL	true bật portal prod (cẩn thận)
Rate limit vars	Xem Best practices
Billing	nạp credit Gommo mặc định không cần env thêm; PayOS legacy tùy chọn — xem Billing
BYOK_ENCRYPTION_KEY	Bắt buộc khi BYOK_ENABLED và NODE_ENV=production — npm run byok:generate-key
BYOK_STORE_FILE	Volume persistent — xem BYOK production

Template: .env.example ở root repo.

CORS production

GATEWAY_CORS_ORIGIN=https://app.example.com

Bỏ trống nếu chỉ server-side.

Portal

Môi trường	Mặc định
Dev	Bật /vi/portal/
Production	Tắt
GATEWAY_PORTAL=true	Ép bật

Deploy docs

Static — không chạy trong process API.

Dev: VitePress proxy /gateway, /vi/ai, /vi/billing → :3001. Prod: không có proxy — cần biết URL API lúc build.

VITE_GATEWAY_URL (bắt buộc cho docs production)

Set khi chạy npm run docs:build. Giá trị được bake vào bundle static.

Tính năng	Dùng VITE_GATEWAY_URL
Catalog / compare	Gommo public API (POST v2…/ai/models) hoặc portal proxy
Đăng nhập / tài khoản	POST /gateway/auth/login, /register, /change-password, /credits/transfer (JSON self-host)
Dashboard /vi/app/*	POST /ai/me, /vi/billing/*
Playground embed	{API}/portal/playground.html?embed=1

Dev — không cần set; proxy VitePress trên :5173.

Build production:

VITE_GATEWAY_URL=https://api.yourdomain.com npm run docs:build
npm run docs:preview

Nếu không set, bundle fallback https://api.yourdomain.com — đổi trước khi ship.

GitHub Pages

Workflow docs-pages.yml build docs/.vitepress/dist rồi deploy qua GitHub Actions.

Một lần (bắt buộc trước deploy thành công đầu tiên):

1. Settings → Pages → Build and deployment → Source: chọn GitHub Actions (không dùng “Deploy from a branch”).
2. Nếu job deploy báo 404 / Ensure GitHub Pages has been enabled — chưa bật Pages; làm bước 1, rồi Actions → Deploy docs → Run workflow. Checklist: docs-pages-setup trên GitHub.

Tuỳ chọn URL API lúc build:

1. Settings → Secrets and variables → Actions → Variables
2. VITE_GATEWAY_URL = https://api.yourdomain.com (không slash cuối)

Domain riêng: CNAME docs.yourdomain.com. CI cũng chạy docs:build mỗi push để bắt lỗi VitePress sớm.

Vercel

1. Build npm run docs:build · output docs/.vitepress/dist
2. Env Production: VITE_GATEWAY_URL=https://api.yourdomain.com
3. Domain docs.yourdomain.com

API khi docs khác origin

Biến API	Lý do
GATEWAY_CORS_ORIGIN	Thêm https://docs.yourdomain.com
GATEWAY_PORTAL=true	Bật playground embed trên /vi/app/playground/

GATEWAY_CORS_ORIGIN=https://docs.yourdomain.com
GATEWAY_PORTAL=true

Local dev: npm run docs:dev → :5173.

Checklist ops

• [ ] /health 200 + flags đúng
• [ ] Secrets trên platform
• [ ] VITE_GATEWAY_URL trên docs build (GitHub variable / Vercel env)
• [ ] GATEWAY_CORS_ORIGIN gồm origin docs
• [ ] GATEWAY_PORTAL=true nếu dùng playground embed prod
• [ ] Webhook PayOS HTTPS — chỉ khi dùng legacy /vi/billing/topup/*
• [ ] Merchant buffer đủ credit

Tiếp theo

→ Best practices · Privacy · Góp ý