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
cd deploy/quickstart
cp .env.example .env
docker compose up -d --build
Wait until GoChat is healthy:
docker compose ps
docker compose logs -f gochat
curl -fsS http://127.0.0.1:3000/health
Seed Demo Data
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):
{"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.
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:
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
# 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.