Runbook

Local-first with a low-cost AWS deployment. Bedrock is invoked only on demand.

Production

What	Where
App	https://ocean.helioiot.com — Lambda (scales to zero) behind CloudFront
Docs	https://docs.ocean.helioiot.com — S3 + CloudFront
Deploys	Push to main → GitHub Actions → SAM stack helio-ocean (us-east-1, Helio AWS account)
Data refresh	Every deploy re-runs the pipeline and bakes a fresh DB into the Lambda bundle

Prerequisites

• Python 3.12+ with uv
• Node 18+ (PDF tooling and this docs site)
• Google Chrome (PDF printing)
• AWS credentials with Bedrock access (optional — the app degrades to labeled offline mode without them)

First-time setup

cd helio-ocean
uv sync
cp .env.example .env        # set AWS_REGION for Bedrock (us-east-1)

Run the pipeline

uv run python scripts/run_pipeline.py            # live Sentinel-2 + ground sources
uv run python scripts/run_pipeline.py --offline  # skip the satellite pull

The run report (per-source counts + live/fixture provenance) is stored with the data and feeds the app's Data panel and every briefing.

Run the app

uv run uvicorn helio_ocean.api.main:app --port 8600
# open http://localhost:8600

Run this docs site

cd docs-site
npm install     # first time
npm start       # http://localhost:8601 — syncs spec markdown automatically

Spec documents are canonical in docs/specs/; scripts/sync_docs.py copies them here with front matter on every start/build. Edit the specs, not the synced copies.

Tests

uv run pytest -m "not network"   # offline acceptance tests (AC-keyed)
uv run pytest                    # includes the live STAC search test

Generate deliverables

# Branded PDF from any markdown (pandoc + headless Chrome + Mermaid)
python3 tools/pdfgen/generate_pdf.py docs/specs/00-prd.md --title "Helio Ocean — PRD" -o docs/pdf/helio-ocean-prd.pdf

# Post-storm situation briefing (markdown + PDF from the live database)
uv run python scripts/make_briefing.py post

Real data drops

Source	Drop location	Effect
NOAA MDMAP export	data/raw/noaa_mdmap_export.csv	Used automatically on next pipeline run; provenance flips to LIVE
Debris Tracker export	data/raw/debris_tracker_export.csv	Same
Copernicus Data Space	future adapter slot (FS-1 / AC-1.5)	Credentials in .env when built