Files
Bike-Tinder/docs/DEVELOPMENT.md
2026-11-18 00:40:21 -04:00

2.7 KiB

Development and deployment

Run these commands from the repo root. The container uses Python 3.14. Use a scratch database and a different port from any running instance; the example binds only to localhost.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
mkdir -p data/dev-img

# Optional: seed a development catalog from motorcycle-hunt snapshots.
.venv/bin/python -m app.importer --state-dir /path/to/hunt-snapshots --db data/dev.sqlite3

# Local app and read-only deck preview.
.venv/bin/python -m app.serve --host 127.0.0.1 --port 9454 --db data/dev.sqlite3 --img-dir data/dev-img
.venv/bin/python -m app.deck --db data/dev.sqlite3 --top 15

# Run separately from the dev server.
.venv/bin/python -m app.selfcheck

data/ and .venv/ are local and ignored by Git. The app.imgfetch CLI can cache images for a development catalog; use --help for options. The nightly process in the live stack imports the catalog, refreshes the taste profile, and backs up SQLite.

For an offline taste-profile pass, run app.agentpass --mock against a development database with swipe history. To inspect the inputs without writing a profile, use --print-summary --dry-run. The optional live provider is configured outside the repo. Never use the running instance's DB for test writes; use SQLite's backup API if you need a consistent copy of a database in use. The legacy browser walks (app.fe_walk_b1, app.fe_walk_v11) need Playwright, Chromium, and staged scratch fixtures; inspect their fixture paths before running them.

API entry points

Area Routes
Status GET /api/health, GET /api/stats
Browse GET /api/section, GET /api/list, GET /api/listing/{id}
Decide POST /api/swipe, DELETE /api/swipe/{id}
Refresh POST /api/import, POST /api/section/forge, POST /api/agent/run
Preferences POST /api/prefs, POST /api/badge/seen
Display GET /api/trends, GET /img/{id}?i=n

For data contracts, see Data model, Ranking, and the UI spec.

Deployment

The Podman Compose definition runs the app and a Tailscale sidecar for private access. The systemd user unit owns the running containers. Keep deployment-specific configuration outside Git and retain independent backups of the SQLite data. Do not expose the single-user app directly to the public internet.

Development lands on dev, verified changes move to main, and the running stack follows release. Build the candidate image before restarting the service. After cutover, check /api/health and confirm that the HTTP shell matches the intended revision. Keep the previous image for rollback.