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.
140 lines
2.7 KiB
Markdown
140 lines
2.7 KiB
Markdown
# quotesdb — Local Development Guide
|
|
|
|
## Prerequisites
|
|
|
|
- [Nix](https://nixos.org/download/) with Flakes enabled
|
|
- `direnv` (optional, for auto-loading the dev shell)
|
|
|
|
Enter the dev shell from the repo root:
|
|
|
|
```sh
|
|
nix develop
|
|
```
|
|
|
|
This gives you: `cargo`, `rustc`, `rust-analyzer`, `trunk`, `wasm-bindgen-cli`, `tofu`, `wrangler`, `jq`.
|
|
|
|
## Running the API server
|
|
|
|
```sh
|
|
# From quotesdb/
|
|
cargo run
|
|
```
|
|
|
|
The server listens on `http://localhost:3000`. The SQLite database is created at `./quotesdb.sqlite` on first run.
|
|
|
|
Override the database path:
|
|
|
|
```sh
|
|
DATABASE_URL=/tmp/test.sqlite cargo run
|
|
```
|
|
|
|
## Running the UI dev server
|
|
|
|
```sh
|
|
# From quotesdb/
|
|
trunk serve
|
|
```
|
|
|
|
Opens `http://localhost:8080`. The Trunk proxy forwards `/api/*` to the native API server on port 3000.
|
|
|
|
Run both together:
|
|
|
|
```sh
|
|
# Terminal 1
|
|
cargo run
|
|
|
|
# Terminal 2
|
|
trunk serve
|
|
```
|
|
|
|
## Environment variables
|
|
|
|
Copy `.env.example` to `.env` and adjust as needed:
|
|
|
|
```sh
|
|
cp .env.example .env
|
|
```
|
|
|
|
`.env` is gitignored — never commit it.
|
|
|
|
## Running tests
|
|
|
|
```sh
|
|
# From quotesdb/
|
|
cargo test
|
|
```
|
|
|
|
Integration tests in `tests/` spin up a real API server against a temporary SQLite database.
|
|
|
|
## D1 schema migrations
|
|
|
|
Migrations are SQL files applied via `wrangler d1 execute`. The schema lives at `infra/schema.sql`.
|
|
|
|
### Apply to local D1 (development)
|
|
|
|
```sh
|
|
wrangler d1 execute quotesdb --file infra/schema.sql --local
|
|
```
|
|
|
|
### Apply to remote D1 (production)
|
|
|
|
```sh
|
|
wrangler d1 execute quotesdb --file infra/schema.sql --remote
|
|
```
|
|
|
|
Requires `CLOUDFLARE_API_TOKEN` to be set (or `wrangler login`).
|
|
|
|
### First-time D1 setup
|
|
|
|
D1 must be created before the Worker can bind to it:
|
|
|
|
```sh
|
|
# Create D1 via OpenTofu (run once)
|
|
cd infra/
|
|
tofu init
|
|
tofu apply -target=cloudflare_d1_database.quotesdb
|
|
|
|
# Apply schema
|
|
wrangler d1 execute quotesdb --file schema.sql --remote
|
|
```
|
|
|
|
After D1 exists, run `tofu apply` without the `-target` flag to apply the full plan.
|
|
|
|
## Building the WASM API binary
|
|
|
|
```sh
|
|
cargo build --release --bin api --target wasm32-unknown-unknown
|
|
```
|
|
|
|
Output: `target/wasm32-unknown-unknown/release/api.wasm`
|
|
|
|
## Building the WASM UI
|
|
|
|
```sh
|
|
trunk build --release
|
|
```
|
|
|
|
Output: `dist/`
|
|
|
|
## Cloudflare Turnstile CAPTCHA
|
|
|
|
The submit form includes a Cloudflare Turnstile CAPTCHA widget. In production,
|
|
the API verifies tokens using the `TURNSTILE_SECRET_KEY` environment variable.
|
|
|
|
**Local development**: The API server skips CAPTCHA verification when
|
|
`TURNSTILE_SECRET_KEY` is not set. You can submit quotes without completing
|
|
the CAPTCHA challenge.
|
|
|
|
To test CAPTCHA locally, set the secret key:
|
|
|
|
```sh
|
|
export TURNSTILE_SECRET_KEY="your-secret-key"
|
|
cargo run
|
|
```
|
|
|
|
Obtain the secret key from:
|
|
|
|
```sh
|
|
cd infra && tofu output -raw turnstile_secret_key
|
|
```
|