Quickstart

Five minutes from clean clone to a working API + dev console + first query. The dev infrastructure (Postgres+PostGIS, Redis, NATS JetStream) is dockerised; the FastAPI app and the Next.js console run on your host.

1 · Prerequisites

Python 3.13+ via uv (the astral.sh installer handles it)
Docker or Podman (Postgres + Redis + NATS run as containers)
Node 20+ with npm (just for the dev console)
Optional: eccodes on your host if you want the materialise worker to decode real GRIB2 (brew install eccodes on macOS)

2 · Bring up the dev infrastructure

From the repo root:

make up         # Postgres :5432, Redis :6379, NATS :4222
make migrate    # apply Alembic migrations to the dev DB

make up uses docker-compose.yml with the official PostGIS image so geospatial alert queries work out of the box. make logs tails container logs if anything looks wrong.

3 · Run the API

make dev        # uvicorn aeroza.main:app --reload :8000

Confirm it answers:

$ curl https://aerozasdk-production.up.railway.app/health
{"status":"ok","version":"0.1.0"}

Open the auto-generated Swagger UI at https://aerozasdk-production.up.railway.app/docs for an interactive request builder over every public route.

4 · Run the dev console

cd web && npm install && npm run dev

The console serves at localhost:3000/console. It exercises every endpoint live — alerts SSE stream, MRMS file catalog, materialised grids, point sample, and polygon reduction.

5 · Populate some data

On a fresh database the catalogs are empty. Two background workers fill them; either runs as a one-shot for cron-friendly testing.

# Pull the most recent NWS alerts (US-wide, ~hundreds of rows).
uv run aeroza-ingest-alerts --once

# Discover MRMS files on the AWS Open Data bucket and persist the catalog.
uv run aeroza-ingest-mrms --once

# Materialise the latest few files into Zarr grids.
# Requires eccodes on your host; skip if you only want metadata.
uv run aeroza-materialise-mrms --once

6 · Your first query

Sample the latest reflectivity grid at a (lat, lng):

$ curl 'https://aerozasdk-production.up.railway.app/v1/mrms/grids/sample?lat=29.76&lng=-95.37'
{
  "type": "MrmsGridSample",
  "value": 39.19,
  "matchedLatitude": 29.8,
  "matchedLongitude": -95.4,
  ...
}

Or reduce a polygon (max value over a region):

$ curl 'https://aerozasdk-production.up.railway.app/v1/mrms/grids/polygon?polygon=-95.7,29.5,-95.0,29.5,-95.0,30.0,-95.7,30.0&reducer=max'

From here, Concepts explains the data model; API reference lists every route.