Skip to main content

​
Golden Path: Local Setup to First Run

​
Purpose

Provide the shortest, repeatable path from local environment setup to a successful first end-to-end run.

​
Prereqs

  • Access to this repository and required cloud credentials.
  • python3 and pip available locally.
  • Node/npm available for dashboard and docs preview.
  • Required environment variables/secrets configured for local development.

​
Step-by-step checklist

  1. Clone repo and install backend dependencies. 
    python3 -m pip install -r requirements.txt
  2. Install frontend/docs dependencies as needed. 
    npm install
  3. Configure local environment variables and verify target project/tenant context.
  4. Run backend locally and confirm health endpoint.
  5. Run frontend locally and confirm dashboard routes load.
  6. Execute a minimal ingestion/test flow to verify first successful run.
  7. Confirm logs show expected tenant-scoped behavior and no blocking errors.

​
Common failure modes

  • Missing env vars/secrets → endpoints fail auth or cannot reach data services.
  • Wrong GCP project context → queries hit unexpected datasets.
  • Dependency drift → install fails or runtime import errors.
  • Port conflicts → backend/frontend fail to start.
  • Stale local artifacts → inconsistent results until cache/build cleanup.