Setting Up a Dev Environment

Make sure you have just and pixi installed.

pixi global install just

Quick Start

From the repo root, run the postinstall routine:

just postinstall

This will copy required .env files into apps/vxdata-api/deployments/dev/ and pre-populate them with sensible defaults. Adapt as needed (in particular HOST_URL and the S3 settings).

Then launch the local dev stack:

just deploy

This is a fully native stack - no Docker required. A process-compose supervisor starts a Postgres process and the FastAPI app directly from the project’s pixi env, using the same .env / .env.secrets files. Postgres data is stored under apps/vxdata-api/deployments/dev/.runtime/.

Services become available at the ports configured in .env (HOST_API_PORT, HOST_POSTGRES_PORT).

Common Commands

just deploy                  # start native API + Postgres
just cleanup                 # stop the stack and wipe the local Postgres data
just import-backup-file ...  # restore a pg_dump into the local Postgres

Loading Data from Backup

For a realistic local dev experience, you can inject a backup dump of the real production vxData postgres into your local postgres. Download it from the backup location, and point the import-backup-file command to the file:

just import-backup-file --path=./my-backup.dump

Configuring the S3 backend

The dev stack runs a local MinIO in Docker (the minio process) and creates every bucket listed in S3_BUCKETS. The defaults in .env.example point at it:

# in apps/vxdata-api/deployments/dev/.env
S3_BUCKETS='{"default": "dataplatform-dev", "buckets": {"dataplatform-dev": {"endpoint": "http://127.0.0.1:12304", "access_key_env": "S3_ACCESS_KEY", "secret_key_env": "S3_SECRET_KEY"}}}'

# in apps/vxdata-api/deployments/dev/.env.secrets
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin

Each bucket names the env vars holding its keys; default receives new uploads. S3_BUCKETS replaced S3_ENDPOINT/S3_BUCKET. just deploy only copies the examples when .env is missing, so an older .env needs S3_BUCKETS added (or re-copy .env.example); without it the API refuses to start.