# 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`.