Rogeeandrogee
abb1bed424
* H-337: add local Captain acceptance fixture * fix(H-337): close acceptance fixture review gaps * fix(H-337): reject non-string skill metadata --------- Co-authored-by: Rogee <rogee@ipao.vip>
128 lines
4.4 KiB
Markdown
128 lines
4.4 KiB
Markdown
# GoChat Docker Compose Quickstart
|
|
|
|
This directory starts a local GoChat stack for manual business validation:
|
|
|
|
- GoChat API on `http://127.0.0.1:3000`
|
|
- PostgreSQL + pgvector
|
|
- Redis
|
|
- Meilisearch
|
|
- Mailhog SMTP/Web UI
|
|
- Optional deterministic seed data
|
|
|
|
It is intended for local/UAT quickstart, not hardened production deployment.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker Engine with Compose v2 (`docker compose version`)
|
|
- Free local ports: `3000`, `5432`, `6379`, `7700`, `1025`, `8025`
|
|
|
|
If those ports conflict, edit `.env` after copying `.env.example`.
|
|
|
|
## Start
|
|
|
|
```bash
|
|
cd deploy/quickstart
|
|
cp .env.example .env
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Wait until GoChat is healthy:
|
|
|
|
```bash
|
|
docker compose ps
|
|
docker compose logs -f gochat
|
|
curl -fsS http://127.0.0.1:3000/health
|
|
```
|
|
|
|
## Seed Demo Data
|
|
|
|
```bash
|
|
docker compose --profile seed run --rm seed
|
|
```
|
|
|
|
Default login after seeding:
|
|
|
|
- Email: `admin@gochat.local`
|
|
- Password: `changeme`
|
|
|
|
Change these values in `.env` before running the seed command if needed.
|
|
|
|
## Optional Captain provider
|
|
|
|
Set `GOCHAT_COPILOT_PROVIDER_CONFIG` and `GOCHAT_COPILOT_CHAT_API_KEY` in the
|
|
ignored `.env` to enable Captain chat and embeddings. The JSON uses the same
|
|
`chat`, `embedding`, `generation`, and `request` contract as the SuperAdmin
|
|
Copilot provider settings API. Set `GOCHAT_COPILOT_EMBEDDING_API_KEY` only when
|
|
`embedding.mode` is `separate`; runtime secrets are not written to the database.
|
|
|
|
Example settings value (the key remains a separate `.env` variable):
|
|
|
|
```json
|
|
{"chat":{"provider":"openai_compatible","base_url":"https://provider.example.com/v1","model":"gpt-5.6-luna"},"embedding":{"mode":"reuse_chat_credentials","provider":"openai_compatible","base_url":"https://provider.example.com/v1","model":"text-embedding-3-small","dimensions":1536},"generation":{"temperature":0.7,"max_tokens":2048},"request":{"timeout_seconds":60,"max_retries":2}}
|
|
```
|
|
|
|
## Local Captain acceptance fixture
|
|
|
|
The acceptance overlay uses a deterministic, OpenAI-compatible local service;
|
|
the configured key is a non-secret sentinel. The same service exposes the
|
|
container-reachable knowledge URL `http://captain-fixture:8080/knowledge`.
|
|
|
|
```bash
|
|
docker compose -f compose.yaml -f compose.acceptance.yaml up -d --build
|
|
GANBING_SOURCE=/path/to/read-only-assets ./scripts/preflight_acceptance.sh
|
|
```
|
|
|
|
Fixture scenarios are selected by the UI message text:
|
|
|
|
- normal text: successful chat
|
|
- `[fixture:fail]`: persistent HTTP 503
|
|
- `[fixture:retry] unique-id`: one HTTP 503 followed by success on provider retry
|
|
- `[fixture:embedding-fail]` and `[fixture:embedding-retry] unique-id`: matching embedding paths
|
|
- `[fixture:skill]`: activate the first bound Skill and read its first reference
|
|
|
|
For the disabled path, clear the Copilot provider in SuperAdmin and confirm the
|
|
Playground unavailable response. Restore by saving the same fixture URL/model
|
|
and sentinel key shown in `compose.acceptance.yaml`; a normal message must then
|
|
succeed. Use a new suffix for each retry scenario, since retries are counted by
|
|
the exact request body. The preflight rejects persisted database settings that
|
|
would silently override the fixture.
|
|
|
|
To prepare the authorized SKILL/SOUL assets without touching their source:
|
|
|
|
```bash
|
|
GANBING_SOURCE=/path/to/read-only-assets \
|
|
./scripts/stage_captain_assets.sh /private/path/gochat-captain-stage
|
|
```
|
|
|
|
In Captain UI, create `ganbing-local-acceptance`, paste
|
|
`captain-skill/instructions.md`, add only files under
|
|
`captain-skill/references/` using their filename stem as `reference_key`, then
|
|
publish and add it to the test assistant. Paste `assistant-instructions.md`
|
|
into the assistant's Additional instructions field. Files under `quarantine/`
|
|
exceed the current 8 KB per-request Skill runtime budget when combined with the
|
|
Skill instructions; do not import them without a content-owner-approved split.
|
|
The staging script never truncates or rewrites source content.
|
|
|
|
## Useful Commands
|
|
|
|
```bash
|
|
# Follow all logs
|
|
docker compose logs -f
|
|
|
|
# Restart GoChat only
|
|
docker compose restart gochat
|
|
|
|
# Stop without deleting data
|
|
docker compose down
|
|
|
|
# Reset all local data
|
|
docker compose down -v
|
|
```
|
|
|
|
## Notes
|
|
|
|
- GoChat runs migrations automatically on startup with `GOCHAT_DATABASE_RUN_MIGRATIONS=true`.
|
|
- The production image includes `/app/migrations`; GoChat runs them automatically on startup in this quickstart stack.
|
|
- Meilisearch uses the quickstart key from `.env`; change it before sharing this stack.
|
|
- Mailhog Web UI is available at `http://127.0.0.1:8025`.
|