--- title: Getting Started product: tide doc_type: tutorial version: master source: git2docs (code-derived, validation-filtered) canonical: https://git2docs.com/wabam/docs/tide/tide-capital-pressure-observatory/getting-started --- # Getting Started _Local setup from zero to a running dashboard_ ## Overview This page walks you through setting up TIDE — Capital Pressure Observatory on your local machine, from cloning the repository to opening a live dashboard in your browser. By the end, you will have a running four-tier composite dashboard pulling real data from FRED, Yahoo Finance, the CFTC, and other free sources, with a 252-business-day history chart and a healthcare watchlist. Getting the initial setup right matters because TIDE's backend and frontend are separate processes that share a single DuckDB file — understanding that structure helps you troubleshoot confidently if anything goes wrong. ## Prerequisites Before you begin, make sure you have the following: - **FRED API key** — Register for a free key at [fred.stlouisfed.org/docs/api/api_key.html](https://fred.stlouisfed.org/docs/api/api_key.html). TIDE uses FRED to pull M2 money supply, the Fed balance sheet, HY credit spreads, NFCI, and bank credit totals. Without this key, the backend cannot fetch any FRED series and `make ingest-all` will fail. - **Python ≥ 3.10** (the backend `pyproject.toml` requires ≥ 3.11 in practice — use 3.11 or newer to be safe) - **Node.js and npm** — Required to install and run the SvelteKit frontend - **make** — All developer workflows are exposed through the Makefile - **Internet connection** — TIDE pulls live data from FRED, Yahoo Finance chart API, CFTC, AAII, SqueezeMetrics, and Treasury TIC on first run No paid data subscriptions are needed. Every data source TIDE uses is free-tier. ## Troubleshooting **Issue: `make ingest-all` fails with an authentication or API key error** - **Symptom:** The command exits with an error mentioning `FRED_API_KEY`, `401`, or `Bad Request` from a FRED endpoint. - **Cause:** The `FRED_API_KEY` variable is missing from `.env`, is set to the placeholder value, or the `.env` file was not created. - **Fix:** Confirm `.env` exists at the project root and contains `FRED_API_KEY=`. You can verify with `grep FRED_API_KEY .env`. If the file does not exist, run `cp .env.example .env` and add your key. --- **Issue: `make ingest-all` hangs or retries several times on the AAII step** - **Symptom:** The ingest process pauses for 20–60 seconds and logs retry warnings before eventually succeeding or failing. - **Cause:** AAII's server uses bot-detection logic that cycles between returning 200 and 403 responses to the same headers, sometimes minutes apart. This is a known upstream behavior. - **Fix:** Wait — the AAII client retries up to 4 times with backoff and validates the downloaded file's OLE2 magic bytes. If all 4 retries fail, re-run `make ingest-all` after a few minutes. The other 14 live metrics will be skipped quickly because they already have fresh data (the command is idempotent). --- **Issue: `make dev-api` starts but the dashboard shows no data or all indicators show as stale** - **Symptom:** The frontend loads at `localhost:5173` but the composite score is blank, or every metric card shows a very old as-of date. - **Cause:** Either `make ingest-all` was not run before starting the servers, or `make backfill-composite` was skipped. - **Fix:** Stop the servers, run `make ingest-all`, `make ingest-watchlist`, and `make backfill-composite` in order, then restart both servers. --- **Issue: Frontend cannot reach the backend — network error or blank dashboard** - **Symptom:** The browser console shows a fetch error, or the SvelteKit page server logs a connection refused error to port 8765. - **Cause:** The FastAPI backend (`make dev-api`) is not running, crashed, or is listening on a different port than the frontend expects. - **Fix:** Confirm `make dev-api` is running in a separate terminal and that its output shows `Uvicorn running on http://127.0.0.1:8765`. If you started the backend on a custom port with `PORT=9000`, the frontend's server-side fetch will still target 8765 unless you have also updated the API base URL in the frontend configuration. --- **Issue: `make init-db` fails with a file or permission error** - **Symptom:** The command exits with an error such as `PermissionError`, `FileNotFoundError`, or a DuckDB lock error. - **Cause:** Either the project directory is not writable, or a previous TIDE process has the DuckDB file open and locked. - **Fix:** Ensure no other `make dev-api` or `tide-ingest` process is running before calling `make init-db`. DuckDB allows only one writer at a time; stop all TIDE processes, then retry. --- **Issue: `make install` fails because the virtual environment does not exist** - **Symptom:** `pip: command not found` or `No such file or directory: '/home/murali/sandbox/envs/tideenv/bin/pip'` - **Cause:** The default `VENV` path (`~/sandbox/envs/tideenv`) does not exist on your machine. - **Fix:** Create the virtual environment first (`python3 -m venv ~/sandbox/envs/tideenv`), then run `make install`. Alternatively, point `VENV` to any existing environment: `make install VENV=./backend/.venv` (creating it first with `python3 -m venv ./backend/.venv`). --- **Issue: Watchlist sparklines or relative returns are missing** - **Symptom:** The watchlist section loads but sparklines are empty or relative return values are all zero. - **Cause:** `make ingest-watchlist` was not run, or the Yahoo Finance chart API request failed for one or more tickers. - **Fix:** Run `make ingest-watchlist` and check the output for HTTP errors. TIDE fetches Yahoo Finance data by hitting `query1.finance.yahoo.com/v8/finance/chart/` directly over HTTP — not via yfinance. If you see connection errors, verify your internet connection and retry. --- **Issue: Four indicators always show as stubbed or have no reading** - **Symptom:** `ici_etf_flows`, `buyback_yield`, `put_call`, and `uvol_dvol` always appear without a live reading. - **Cause:** This is expected behavior. These four metrics are intentionally stubbed — they are registered in the MetricDefinition registry with metadata but have no `ingest_fn` because their free data sources are gated or unavailable. They are not a setup error. - **Fix:** No action needed. The per-tier `__init__.py` docstrings in the backend source document the paths to unblocking each stubbed metric if you want to contribute an implementation.