74 lines
3.4 KiB
Markdown
74 lines
3.4 KiB
Markdown
# Kavosh
|
||
|
||
Self-hosted dashboard that ingests Apache/LiteSpeed access logs and turns
|
||
them into three sections — Overview, SEO & Bot Behavior, and Suspicious
|
||
Requests/IP History — engineered to run inside a constrained cPanel
|
||
shared-hosting account (4 CPU cores, 60 entry processes, 2GB RAM, 1,024
|
||
IOPS, 16MB/s I/O, 150 processes, 150 DB connections).
|
||
|
||
Stack: Flask (application factory + blueprints) + HTMX/Alpine.js +
|
||
Tailwind + Chart.js + Grid.js, served via Passenger, SQLite in WAL mode.
|
||
No cron job is required — uploads process automatically in the
|
||
background, with light/dark mode and live progress bars for both the
|
||
upload and analysis phases.
|
||
|
||
## Project docs
|
||
- `DEPLOYMENT.md` — cPanel deployment checklist + local dev setup (no cron needed)
|
||
- `docs/api-contract-final.md` — consolidated route table + envelope audit
|
||
- `.env.example` — every environment variable the app reads
|
||
- `migrations/versions/0001`–`0006` — schema history, in order
|
||
|
||
## Layout
|
||
```
|
||
app/
|
||
blueprints/ overview, seo, security, uploads, auth, api (routes)
|
||
models/ SQLAlchemy models — one file per table
|
||
services/ log parsing, bot/threat classification, aggregation,
|
||
background.py (no-cron auto-processing)
|
||
static/src Tailwind/JS source (built via Vite -> static/dist)
|
||
templates Jinja base + HTMX partials
|
||
migrations/ Alembic schema history
|
||
tests/ pytest suite (parser + classifier + route smoke tests,
|
||
real log-file fixtures under tests/fixtures/)
|
||
```
|
||
|
||
## Quick start (local dev)
|
||
```
|
||
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
|
||
```
|
||
|
||
Visit `/` — it redirects to `/overview` if you're logged in, or `/login`
|
||
otherwise. Upload a log file and it starts analyzing immediately; no
|
||
cron job or manual CLI command required (see `DEPLOYMENT.md` if you want
|
||
the optional cron fallback anyway). The Overview page also lists every
|
||
uploaded file with select-and-delete — deleting a file removes its raw
|
||
data and correctly recomputes any shared date rollups, rather than just
|
||
subtracting the file's contribution naively (see `app/services/
|
||
file_deletion.py`).
|
||
|
||
## Design system
|
||
- Colors/fonts are defined as Tailwind tokens in `tailwind.config.js`
|
||
(`paper`/`surface`/`ink`/`muted`/`accent`/`danger`/`warn`/`ok`, each
|
||
with a `-dark` counterpart) — not hardcoded `slate-*` classes.
|
||
- Three type roles: `font-display` (Space Grotesk, headings), `font-sans`
|
||
(Public Sans, UI chrome), `font-data` (JetBrains Mono, every number/IP/
|
||
path/timestamp — the app's one deliberate signature touch, since the
|
||
whole product is "raw log lines turned into a readout").
|
||
- Dark mode toggles a `.dark` class on `<html>`, persisted in
|
||
`localStorage`, set synchronously in `base.html`'s `<head>` to avoid a
|
||
flash of the wrong theme on load.
|
||
|
||
## Notes on how this was built
|
||
Built chapter-by-chapter against a 12-chapter project spec, then extended
|
||
per project-owner follow-up requests (removing the cron requirement,
|
||
dark mode, upload/analysis progress bars, root-URL auth redirect). Where
|
||
an implementation choice extended or deviated from the original spec, it's
|
||
marked inline with a comment — search for "flagged", "ASSUMPTION", or
|
||
"TRADEOFF" to find every one of them.
|