You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
74 lines
3.0 KiB
Markdown
74 lines
3.0 KiB
Markdown
---
|
|
# quotesdb-hord
|
|
title: Write docs/LOCAL_DEV.md — local dev quickstart (cargo run + trunk serve, rusqlite, DATABASE_URL)
|
|
status: completed
|
|
type: task
|
|
priority: normal
|
|
created_at: 2026-03-10T23:32:10Z
|
|
updated_at: 2026-03-10T23:32:17Z
|
|
blocked_by:
|
|
- quotesdb-td4l
|
|
---
|
|
|
|
<context>
|
|
The `quotesdb` API is built with Axum + Tokio, targeting Cloudflare Workers via `workers-rs`. It serves JSON at `/api/*` endpoints and persists data to Cloudflare D1 (production) or a local SQLite file (development).
|
|
|
|
TRIAGE 33ed29 resolved the local dev database strategy: **plain rusqlite with a local SQLite file**.
|
|
No Turso, no wrangler, no Cloudflare account required for local development.
|
|
|
|
Selection is **compile-time** via `cfg(target_arch = "wasm32")`:
|
|
- `wasm32` → workers-rs D1 bindings (production)
|
|
- native → `rusqlite` + `tokio-rusqlite` with a local `.sqlite` file (dev/test)
|
|
|
|
The native `main()` (see ticket 6e829e) reads `DATABASE_URL` from the environment, defaulting to
|
|
`./quotesdb.sqlite`, and calls `repo.run_migrations()` on startup to create tables if they don't exist.
|
|
</context>
|
|
|
|
<goal>
|
|
Write `docs/LOCAL_DEV.md` explaining how to set up and run the quotesdb project locally:
|
|
|
|
1. **Prerequisites** — Rust (via Nix flake), no Cloudflare account needed
|
|
2. **Running the API**:
|
|
- `cargo run` from the `quotesdb/` directory
|
|
- Listens on `localhost:3000`
|
|
- Creates `./quotesdb.sqlite` automatically on first run
|
|
- Override DB path: `DATABASE_URL=/path/to/db.sqlite cargo run`
|
|
3. **Running the UI**:
|
|
- `trunk serve` from the `quotesdb/` directory
|
|
- Listens on `localhost:8080`
|
|
- Proxies `/api/*` to `localhost:3000` (see Trunk.toml `[[proxy]]` block)
|
|
4. **Environment variables**:
|
|
- `DATABASE_URL` — path to SQLite file (optional, default: `./quotesdb.sqlite`)
|
|
- No other variables required for local dev
|
|
5. **Local dev workflow** (two terminals):
|
|
```sh
|
|
# Terminal 1 — API
|
|
cargo run
|
|
# Terminal 2 — UI
|
|
trunk serve
|
|
# Open http://localhost:8080
|
|
```
|
|
6. **No wrangler required** — `cargo run` uses the native Axum server with rusqlite directly.
|
|
Wrangler is only needed for Workers deployment (handled by CI/infra).
|
|
7. **Database notes**:
|
|
- Schema is applied automatically via `run_migrations()` on first `cargo run`
|
|
- Delete `./quotesdb.sqlite` to start fresh
|
|
- `sqlite3 ./quotesdb.sqlite` for manual inspection
|
|
</goal>
|
|
|
|
<decisions-reflected>
|
|
- TRIAGE 33ed29: rusqlite + local SQLite file (not Turso, not wrangler dev)
|
|
- TRIAGE a9534d: Trunk proxy for `/api/*` (not CORS middleware)
|
|
- TRIAGE e8a330: no SQLx, `cfg(target_arch)` split
|
|
</decisions-reflected>
|
|
|
|
<constraints>
|
|
- Do not document `.env` files directly — list the env vars and their defaults, but note that `.env` is gitignored.
|
|
- Cross-reference tickets 6e829e (api main.rs), dc3d2b (Trunk.toml), and 00aff0 (DB abstraction).
|
|
- Keep it concise — it's a quickstart, not exhaustive reference docs.
|
|
</constraints>
|
|
|
|
<commit>
|
|
`docs(quotesdb): write LOCAL_DEV.md — local dev quickstart for api and ui`
|
|
</commit>
|