dev-setup

# First-Time Dev Environment Setup Run this once. After completion, switch to the `dev-lifecycle` skill for daily development. ## 1. System Dependencies Verify these tools are installed: ```bash python3 --version # 3.12+ uv --version # Python package manager gh --version # GitHub CLI (optional, for PR/issue ops) docker --version # Container builds + Kind cluster kind --version # Local K8s cluster (sandbox dev only) kubectl version --client # K8s CLI helm version --short # Helm chart deployment hurl --version # E2E testing (HTTP request runner) ``` Install missing tools (macOS): ```bash curl -LsSf https://astral.sh/uv/install.sh | sh brew install kind kubectl helm hurl ``` ## 2. Install Repo Dependencies ```bash make install ``` This installs Python dependencies with `uv`, installs web dependencies with `pnpm`, and configures git hooks. ## 3. Configure Database (Neon) The project uses [Neon](https://neon.tech) Serverless PostgreSQL — no local Postgres needed. For local API development (`make dev-api`), start from: ```bash cp .env.example .env ``` Edit `.env` and set at least: ``` TREADSTONE_DATABASE_URL=postgresql+asyncpg://neondb_owner:xxx@ep-xxx.ap-southeast-1.aws.neon.tech/neondb?sslmode=require TREADSTONE_JWT_SECRET=CHANGE_ME ``` The URL scheme must be `postgresql+asyncpg://` (not `postgresql://`). Keep `?sslmode=require`. For local Kubernetes deployment (`make local`), also prepare: ```bash cp .env.example .env.local ``` Then set: ``` TREADSTONE_DATABASE_URL=postgresql+asyncpg://... TREADSTONE_JWT_SECRET=CHANGE_ME TREADSTONE_LEADER_ELECTION_ENABLED=true ``` ## 4. Apply Database Migrations ```bash make migrate ``` Expected: `INFO [alembic.runtime.migration] Context impl PostgresqlImpl.` with migration details listed. ## 5. Verify Environment ```bash make test ``` Expected: all tests pass (integration tests are excluded by default). If tests pass, the environment is ready. Optional API sanity check: ```bash make dev-api # In another terminal: curl http://localhost:8000/health ``` ## 6. Local K8s Cluster (Sandbox Development) For sandbox-related features that require a real Kubernetes cluster, follow `deploy/README.md` — use **`make local`** (and **`make destroy-local`** to tear down) so the Makefile runs context checks before Helm; smoke testing end-to-end. Quick start: ```bash kubectl config use-context kind-treadstone # or your Kind context name make local # One-command: Kind cluster + build + deploy curl -sf http://api.localhost/health # API via Ingress (Web UI: http://app.localhost) make test-e2e # default BASE_URL=http://api.localhost ``` Pure API development (`make dev-api`) does not require a K8s cluster. --- ## Troubleshooting **`uv sync` fails:** - Confirm Python 3.12+: `python3 --version` - Try: `uv python install 3.12` **Database connection fails (`could not connect`):** - Check the connection string in `.env` - Confirm the URL uses `postgresql+asyncpg://` not `postgresql://` - Neon free-tier projects auto-suspend; first connection may be slow (~1s cold start) **`alembic upgrade head` reports `authentication failed`:** - Confirm `.env` exists in the project root - URL-encode special characters in the password **`make local` fails before app startup:** - Confirm `.env.local` exists - Confirm `TREADSTONE_JWT_SECRET` is set - Confirm `TREADSTONE_LEADER_ELECTION_ENABLED=true` for the K8s environment - Optional: set `TREADSTONE_PROD_CONTEXT` so `destroy-local` is refused while kubectl points at prod; `make local` runs the context check **after** Kind setup and **before** Helm (see `deploy/README.md`). If Kind already exists but kubectl still points at prod, switch with `kubectl config use-context kind-treadstone`