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

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

## Verify Tooling

```bash
go version
docker --version
task --version
task --list
```

## Common Tasks

### Generate and Build

```bash
task generate
task build
```

### Full Test/Validation Suite

```bash
task fullsuite
```

### Local Compose Lifecycle

```bash
task compose:up
task compose:down
task compose:clean
```

### Linting

```bash
task lint
```

## Useful Focused Tasks

```bash
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

```bash
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](12-chatbot-guide.md) for
the full operator reference.

## Troubleshooting

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