gochat/deploy/quickstart

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.