Deploy & ops

รัน Gommo Developer เป็น API service เดียว Docs (VitePress) และ dev portal deploy แยก

โครงสร้างที่แนะนำ

Service	Domain	วิธี
API	`api.yourdomain.com`	Docker / Railway / Fly
Docs	`docs.yourdomain.com`	VitePress static — Vercel หรือ GitHub Pages
Portal	`/th/portal/` บน API (dev เท่านั้น)	ปิดใน prod ยกเว้น `GATEWAY_PORTAL=true`

ห้าม commit .env, GOMMO_ACCESS_TOKEN หรือ ADMIN_API_KEY — ใช้ platform secrets

พัฒนาในเครื่อง

bash

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

Portal static (ทางเลือก): npm run portal:dev → :5180

ตรวจสอบ:

bash

curl http://localhost:3001/health

Health check

http

GET /health

ตัวอย่าง response:

json

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

ใช้ /health สำหรับ Railway, Fly, Kubernetes และ load balancer probes

ตั้งค่า platform:

Platform	การตั้งค่า
Railway	Health check path `/health`
Fly.io	HTTP check ใน `fly.toml` → `GET /health`
Docker / k8s	Liveness probe บน `/health`

Docker

bash

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

Image รัน node dist/index.js หลัง npm run build Platform inject PORT — gateway อ่าน process.env.PORT

Self-host API modes (ขั้นสูง)

Mode B (/gateway/*) และ Mode C (path proxy) ทางเลือก เมื่อ deploy repo นี้ ไม่จำเป็น สำหรับการเชื่อมต่อ Gommo — แอป production เรียก Gommo public API โดยตรง (Mode A)

Doc	วัตถุประสงค์
Integration modes	เปรียบเทียบ Mode A / B / C
Endpoint map	ตาราง path ข้ามโหมด
Choosing a mode	แผนผังตัดสินใจ

หน้าเหล่านี้อยู่ใต้ Deploy บน sidebar (ซ่อนจาก Models & routing) คืน nav เริ่มต้น: เพิ่ม link ใน docs/.vitepress/config.ts → modelsRoutingInDocs*

Railway

New project → Deploy from GitHub
Railway detect Dockerfile หรือ Nixpacks (npm run build, npm start)
Variables: คัดลอกจาก .env.example — อย่างน้อย GOMMO_API_DOMAIN, GOMMO_ACCESS_TOKEN, ADMIN_API_KEY
Custom domain: api.yourdomain.com → CNAME ไป Railway URL
Health check: /health

Fly.io

bash

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

fly.toml มี HTTP check บน GET /health

Production environment

Variable	วัตถุประสงค์
`PORT`	Inject โดย platform (3001 ในเครื่อง)
`NODE_ENV`	`production` — ปิด portal โดย default
`GOMMO_API_DOMAIN`	Domain ลงทะเบียน (see `.env.example`)
`GOMMO_ACCESS_TOKEN`	Merchant — server เท่านั้น
`ADMIN_API_KEY`	ป้องกัน `/th/admin/*`
`GATEWAY_CORS_ORIGIN`	Browser origins คั่นด้วย comma
`GATEWAY_PORTAL`	`true` เปิด `/th/portal` ใน prod (ใช้ด้วยความระมัดระวัง)
`GATEWAY_RATE_LIMIT_MAX`	Default 120/min/IP สำหรับ `/gateway`
`ADMIN_RATE_LIMIT_MAX`	Default 30/min/IP สำหรับ `/th/admin`
`BILLING_RATE_LIMIT_MAX`	Default 60/min/IP สำหรับ `/th/billing`
Billing	Gommo เติมเครดิต default ไม่ต้อง env เพิ่ม; PayOS legacy ทางเลือก — ดู Billing
`BYOK_ENCRYPTION_KEY`	จำเป็น เมื่อ `BYOK_ENABLED` และ `NODE_ENV=production` — `npm run byok:generate-key`
`BYOK_STORE_FILE`	Persistent volume — ดู BYOK production

เทมเพลตเต็ม: .env.example ที่ root repo

CORS ใน production

ตั้งเมื่อ browser client เรียกจาก origin อื่น:

env

GATEWAY_CORS_ORIGIN=https://app.example.com,https://www.example.com

ไม่ตั้งสำหรับ integration แบบ API-only (server-side)

พฤติกรรม Portal

Environment	Default
`NODE_ENV !== production`	Portal เปิด ที่ `/th/portal/`
Production	Portal ปิด
`GATEWAY_PORTAL=true`	บังคับเปิด
`GATEWAY_PORTAL=false`	บังคับปิด

Error monitoring

REST routes คืน structured errors:

json

{ "success": false, "message": "…", "code": "UPSTREAM_ERROR" }

Log code + path สำหรับ alerts Upstream 502 จาก proxy บ่งชี้ปัญหา connectivity Gommo

Deploy docs

Docs เป็น static — ไม่ serve โดย API process ใน production

ใน dev VitePress proxy /gateway, /th/ai และ /th/billing ไป :3001 ใน production ไม่มี proxy — site ต้องรู้ API URL ตอน build

`VITE_GATEWAY_URL` (จำเป็นสำหรับ production docs)

ตั้งเมื่อรัน npm run docs:build ฝังใน static bundle (ไม่ใช่ runtime secret)

Feature	ใช้ `VITE_GATEWAY_URL`
Models catalog / compare	Gommo public API (`POST v2…/ai/models`) หรือ portal proxy
Sign in / account	`POST /gateway/auth/login`, `/register`, `/change-password`, `/credits/transfer` (JSON self-host)
Dashboard `/th/app/*`	`POST /ai/me`, `/th/billing/*`
Playground embed	`{API}/portal/playground.html?embed=1` (iframe + postMessage)

Dev — ไม่ตั้ง; VitePress proxy จัดการ API บน :5173

Production build:

bash

VITE_GATEWAY_URL=https://api.yourdomain.com npm run docs:build
npm run docs:preview   # optional — serve dist ในเครื่อง

ถ้าไม่ตั้งตอน build bundle fallback เป็น https://api.yourdomain.com — แทนที่ placeholder ก่อน ship

GitHub Pages

Workflow .github/workflows/docs-pages.yml build docs/.vitepress/dist แล้ว deploy ผ่าน GitHub Actions

ครั้งเดียว (ก่อน deploy สำเร็จครั้งแรก):

Settings → Pages → Build and deployment → Source: เลือก GitHub Actions
ถ้า job deploy ได้ 404 / Ensure GitHub Pages has been enabled — เปิด Pages ตามข้อ 1 แล้ว Actions → Deploy docs → Run workflow อีกครั้ง — docs-pages-setup

ตัวแปร API (ไม่บังคับ): Settings → Variables → VITE_GATEWAY_URL = https://api.yourdomain.com

Push ไป main (paths ใต้ docs/**) trigger build + deploy · CI รัน docs:build ทุก push

Vercel

Import repo บน Vercel
Build: npm run docs:build · Output: docs/.vitepress/dist (ดู vercel.json)
Environment variables: VITE_GATEWAY_URL = https://api.yourdomain.com (Production)
Custom domain: docs.yourdomain.com

ฝั่ง API เมื่อ docs อยู่ origin อื่น

API variable	เหตุผล
`GATEWAY_CORS_ORIGIN`	รวม `https://docs.yourdomain.com` — browser เรียกจาก catalog, login, `/th/app/`
`GATEWAY_PORTAL=true`	เปิด `/th/portal/playground.html` สำหรับ embedded playground บน `/th/app/playground/`

ตัวอย่าง:

env

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

Preview ในเครื่อง (dev server hot reload): npm run docs:dev → :5173

Ops checklist

[ ] GET /health คืน 200 พร้อม flags ที่คาดหวัง
[ ] Secrets ตั้งบน platform (ไม่ใน git)
[ ] VITE_GATEWAY_URL ตั้งตอน build docs (GitHub variable หรือ Vercel env)
[ ] GATEWAY_CORS_ORIGIN รวม docs origin (https://docs.…)
[ ] GATEWAY_PORTAL=true ถ้าใช้ embed /th/app/playground/ ใน prod
[ ] PayOS webhook URL ลงทะเบียน (HTTPS) — เฉพาะ legacy /th/billing/topup/*
[ ] Merchant buffer credits พอสำหรับ fulfillment topup
[ ] Rate limits เหมาะกับ traffic

ขั้นตอนถัดไป

→ Best practices · Privacy · Report feedback

Deploy & ops ​

โครงสร้างที่แนะนำ ​

พัฒนาในเครื่อง ​

Health check ​

Docker ​

Self-host API modes (ขั้นสูง) ​

Railway ​

Fly.io ​

Production environment ​

CORS ใน production ​

พฤติกรรม Portal ​

Error monitoring ​

Deploy docs ​

VITE_GATEWAY_URL (จำเป็นสำหรับ production docs) ​

GitHub Pages ​

Vercel ​

ฝั่ง API เมื่อ docs อยู่ origin อื่น ​

Ops checklist ​

ขั้นตอนถัดไป ​

Deploy & ops

โครงสร้างที่แนะนำ

พัฒนาในเครื่อง

Health check

Docker

Self-host API modes (ขั้นสูง)

Railway

Fly.io

Production environment

CORS ใน production

พฤติกรรม Portal

Error monitoring

Deploy docs

`VITE_GATEWAY_URL` (จำเป็นสำหรับ production docs)

GitHub Pages

Vercel

ฝั่ง API เมื่อ docs อยู่ origin อื่น

Ops checklist

ขั้นตอนถัดไป