From c1daef64111fe5d780e0f9aef7164273a1ff5b48 Mon Sep 17 00:00:00 2001 From: Joel Salmon Date: Tue, 16 Jun 2026 21:59:24 -0500 Subject: [PATCH] docs: add top-level "Running" quick-reference to README Surface run info up front: prerequisites, one-command Docker start + manage, access-URL table, no-browser API check, and test commands (local + in-container), with links to the detailed sections. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/README.md b/README.md index 2a9046f..a8a7d27 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,52 @@ The service presents a lightweight browser flow, stores the user's narrative answers in SQLite, sends those answers to Anthropic for structured extraction, persists the resulting profile, and displays a plain-language profile page. +## Running (quick reference) + +Prerequisites: Docker with the `docker compose` plugin, and a `.env` +(`cp .env.example .env`, then set `ANTHROPIC_API_KEY`; add `GOOGLE_*`, +`JWT_SECRET`, `IMPACTFLOW_API_KEY` for browser auth; `COOKIE_SECURE=false` for +local http). + +```bash +docker compose up -d --build discovery # build + start (migrations run on startup) +docker compose logs -f discovery # follow logs +docker compose down # stop +``` + +Access: + +| Where | URL | +| --- | --- | +| Deployed (HTTPS) | `https://impactflow.teamci.org:8011` | +| Local, from Windows | `http://localhost:8011` (→ discovery flow) | +| Local, from WSL | `http://192.168.245.52:8011` (`localhost` forwards from Windows only) | +| Health | `http://localhost:8011/health` | + +User journey (all served from `/static`): discovery → profile → reflect → +coaching → dashboard → visuals. + +Quick API check without a browser (machine auth): + +```bash +KEY=$(grep '^IMPACTFLOW_API_KEY=' .env | cut -d= -f2 | tr -d '\r') +curl -s http://localhost:8011/health +curl -s -H "X-API-Key: $KEY" http://localhost:8011/api/me +``` + +Run the tests (all AI calls mocked — no key/network needed): + +```bash +.venv/Scripts/python.exe -m pytest # local venv (Windows) +# or in-container, if the local toolchain is unavailable: +docker build -t ifd-test . && docker run --rm -v "$PWD:/app" --entrypoint python ifd-test -m pytest -q +``` + +Details below: [Quick Start With Docker](#quick-start-with-docker), +[Local Development](#local-development), [Tests And Verification](#tests-and-verification), +and the production deployment + weekly-check-in scheduler notes under +[Configuration](#configuration). + ## Quick Explanation For AI Assistants If you need to explain this app in detail, use this mental model: