# 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 |