query-orchestration/docs/ai.generated/05-getting-started.md

Getting Started Guide

Prerequisites

• Devbox
• Docker
• Go 1.24.x (provided by devbox)
• Task (task)

Local Setup

git clone <repository-url>
cd query-orchestration.2
touch .env
devbox shell

Verify Tooling

go version
docker --version
task --version
task --list

Common Tasks

Generate and Build

task generate
task build

Full Test/Validation Suite

task fullsuite

Local Compose Lifecycle

task compose:up
task compose:down
task compose:clean

Linting

task lint

Useful Focused Tasks

task openapi:generate
task db:generate
task db:lint
task test:functional
task test:race

Key Local Ports

• queryAPI: 8080
• storeEventRunner: 8081
• docInitRunner: 8082
• docSyncRunner: 8083
• docCleanRunner: 8084
• clientSyncRunner: 8089
• prometheus: 9091
• postgres: 5432
• localstack: 4566
• permit_pdp: 7766

Deprecated compatibility services (still present in compose in some environments)

• docTextRunner: 8085
• querySyncRunner: 8087
• queryRunner: 8088
• queryVersionSyncRunner: 8090

Minimal .env Example

PGUSER=postgres
PGPASSWORD=password
PGDATABASE=queryorchestration
PGHOST=localhost
PGPORT=5432
DB_NOSSL=true

AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
AWS_SESSION_TOKEN=test
AWS_ENDPOINT_URL=http://localhost:4566
AWS_S3_USE_PATH_STYLE=true

DISABLE_AUTH=true
LOG_LEVEL=DEBUG
BUCKET=<your-bucket-name>

# Chatbot (required+notEmpty for queryAPI to start). See
# `.env.example` and the Chatbot Guide for the full reference.
CHATBOT_SERVICE_URL=http://chatbot.local:8000
CHATBOT_API_KEY=replace_me
# Optional with defaults:
# CHATBOT_REQUEST_TIMEOUT_SECONDS=60
# CHATBOT_MAX_TURN_CHARS=2000
# CHATBOT_RECENT_TURNS=5

To enable the chatbot endpoints, set CHATBOT_SERVICE_URL and CHATBOT_API_KEY in your environment; the queryAPI process will fail to start without them. See Chatbot Guide for the full operator reference.

Troubleshooting

# Validate compose files
task compose:lint

# Check migrations/codegen
task db:generate
task openapi:generate

# Recreate local containers/volumes
task compose:clean
task compose:up