Kavosh/DEPLOYMENT.md

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