start project

2026-08-07 21:17:17 +03:30
commit ea1e1eead6
121 changed files with 8108 additions and 0 deletions
@@ -0,0 +1,77 @@
+# Kavosh — cPanel Deployment Checklist
+
+No cron job is required to run Kavosh. Log parsing starts automatically
+in the background as soon as a file is uploaded, and any file left
+incomplete (e.g. a worker process recycled mid-parse) resumes the next
+time the Overview tab is loaded. See "Optional: cron" at the bottom if
+you'd still like the extra resilience of a scheduled fallback.
+
+1. **Setup Python App** (cPanel) — create the app; note the virtualenv
+   path and set the startup file to `passenger_wsgi.py`.
+2. Activate the generated virtualenv and install dependencies:
+   ```
+   pip install -r requirements.txt
+   ```
+   (Dev-only tools — `pytest` etc. — live in `requirements-dev.txt` and
+   are NOT installed on the host, per Ch02 factor 5's build/release/run
+   separation.)
+3. Set every variable in `.env.example` via the Python App's
+   **Environment Variables** UI — never a committed `.env` in production.
+4. Create the schema:
+   ```
+   flask db upgrade
+   ```
+5. Bootstrap the single admin account (interactive password prompt keeps
+   the raw credential out of process env/config):
+   ```
+   flask create-admin --email you@example.com
+   ```
+6. Build frontend assets **locally or in CI**, not on the host:
+   ```
+   npm install && npm run build
+   ```
+   Deploy only the resulting `app/static/dist/` output alongside the
+   Python app — Node never runs on the server (Chapter 05).
+7. Configure static file mapping (`.htaccess` or the panel's static-file
+   rule) so `app/static/dist/*` bypasses Python entirely (Chapter 03).
+8. Verify `GET /healthz` returns `{"data": {"status": "ok"}, ...}`, then
+   log in and upload a file — it should start analyzing within a second
+   or two, with no further setup needed.
+
+## Optional: cron
+
+Two commands remain available for anyone who wants the extra resilience
+of a scheduled fallback instead of relying solely on automatic/on-visit
+processing:
+
+```
+*/5 * * * * cd /home/YOURUSER/kavosh && /home/YOURUSER/virtualenv/kavosh/3.11/bin/flask process-logs >> /home/YOURUSER/logs/kavosh-process-logs.log 2>&1
+0 3 * * *   cd /home/YOURUSER/kavosh && /home/YOURUSER/virtualenv/kavosh/3.11/bin/flask cleanup      >> /home/YOURUSER/logs/kavosh-cleanup.log 2>&1
+```
+
+`cleanup` enforces the Chapter 06 retention policy (below) — nothing in
+the UI depends on it having run; without it, old raw data simply
+accumulates instead of being pruned. `process-logs` is a fallback for
+the rare case a background thread dies before finishing (see
+`app/services/background.py` for why that can happen and how the app
+recovers without cron anyway).
+
+## Local development
+```
+cp .env.example .env          # fill in real values
+pip install -r requirements.txt -r requirements-dev.txt
+npm install && npm run build  # or `npm run dev` while iterating on frontend
+flask db upgrade
+flask create-admin --email you@example.com
+flask run
+pytest                        # run the test suite
+```
+
+## Retention policy enforced by `flask cleanup` (Chapter 06/12, optional)
+| Table | Retention |
+|---|---|
+| `log_entries` | ~30 days |
+| `request_stats_hourly` | ~90 days (daily rollup already retained indefinitely) |
+| `ip_path_stats_daily` / `ip_status_stats_daily` | ~30 days |
+| Raw uploaded log files | deleted once `status="done"` |
+| Everything else (`request_stats_daily`, `bot_hits`, `suspicious_events`, `referrer_stats_daily`, `browser_stats_daily`, `human_path_stats_daily`, `blocklist_suggestions`) | indefinite — small, bounded-cardinality row counts |