Local Development

The fastest way to develop against HatiData locally. Docker runs infra (Postgres, MinIO, Redis), while the proxy and control plane run natively on your machine for instant recompile.

Quick Setup (Recommended)

# 1. Start infrastructure (Postgres, MinIO, Redis, Qdrant, embedding sidecar)
cd dev && make up-native

# 2. Load environment variables
set -a && source dev/.env.native && set +a

# 3. Run control plane (Terminal 1)
cargo run -p hatidata-control-plane

# 4. Run proxy (Terminal 2)
cargo run -p hatidata-proxy

# 5. Run dashboard (Terminal 3, optional)
cd dashboard && npm run dev

Incremental recompile is ~15 seconds. No Docker Rust builds.

Well-Known Dev API Key

A pre-seeded API key works for both SQL proxy and V2 REST endpoints:

hd_test_marviy_local_dev_00000000000000

SQL Proxy

PGPASSWORD=hd_test_marviy_local_dev_00000000000000 \
  psql -h localhost -p 5439 -U admin -c "SELECT 1"

V2 REST Endpoints

# List tasks
curl http://localhost:8080/v2/runtime/tasks \
  -H "Authorization: ApiKey hd_test_marviy_local_dev_00000000000000"

# Create a task
curl -X POST http://localhost:8080/v2/runtime/tasks \
  -H "Authorization: ApiKey hd_test_marviy_local_dev_00000000000000" \
  -H "Content-Type: application/json" \
  -d '{"kind": "test", "metadata": {}}'

Ports

Service	Port	URL
SQL Proxy	5439	psql -h localhost -p 5439 -U admin
Control Plane API	8080	http://localhost:8080/health
Dashboard	3000	http://localhost:3000
MinIO Console	9001	http://localhost:9001
Prometheus Metrics	9090	http://localhost:9090/metrics

V2 Runtime

V2 endpoints are enabled by default in the local dev environment (HATIDATA_V2_RUNTIME_ENABLED=true in .env.native).

# Check V2 is enabled
curl http://localhost:8080/v2/runtime/tasks \
  -H "Authorization: ApiKey hd_test_marviy_local_dev_00000000000000"
# Should return [] (empty task list), not 404

Full Docker Setup (Alternative)

Builds Rust inside Docker — slower (~15 min first build), needs 8GB+ RAM:

cd dev && make up       # Full stack in Docker
cd dev && make down     # Stop all

Troubleshooting

"No proxy endpoint configured" in Schema Browser

The environment needs proxy_endpoint set. For native mode:

-- Connect to CP Postgres
psql -h localhost -p 5433 -U hatidata -d hatidata

-- Set proxy endpoint
UPDATE environments
SET proxy_endpoint = 'localhost:5439'
WHERE proxy_endpoint IS NULL;

V2 endpoints return 404

Check that HATIDATA_V2_RUNTIME_ENABLED=true is in your .env.native file. Restart the control plane after changing.