`README.md`

42 lines
# rentv-826-tracker

Server-side **time-on-server** tracker for the `/826/` client area
("RENTV — Steve Bloom Concepts") on **rentv.agentabrams.com**.

`/826/` is a static nginx location (`alias /var/www/rentv-826/`) behind its own
Basic-Auth realm (`/etc/nginx/.htpasswd-826`). This service reads the nginx access
log, sessionizes it, and records every visit + accumulated time into the per-client
Postgres DB **`rentv_826`**. **No changes are made to the client's pages** — tracking
is 100% server-side, attributed to the Basic-Auth user (`$remote_user`, e.g. `boomer`).

## Data model (`rentv_826`)
- `clients` — one row per client (`boomer` → Steve Bloom `sbloom@rentv.com`). General
  per-client DB: this is the home for the /826/ portal's client data, time-tracking first.
- `sessions` — one row per visit session (start, last-seen, duration, hit count, login, ip).
- `page_hits` — every request within a session.
- `ingest_state` — resumable log offset/inode + a one-time backfill marker.

## Sessionization
A session = a run of authenticated `/826/` requests by the same `(login, ip)` with no
gap longer than `SESSION_GAP_MIN` (default 30 min). `duration = last_seen − started`
(dwell on a session's final page is unknowable from logs — accepted approximation).
Only **authenticated** hits count (401 pre-auth noise and bots are ignored).

## Run
```
npm install
cp .env.example .env   # fill DATABASE_URL
node tracker.js            # backfill (once) + live-tail
node tracker.js --backfill-only
node report.js [client]    # time-on-server report
```
Deployed on Kamatera under pm2 as `rentv-826-tracker`.

## nginx
**No nginx config change is required.** The tracker reads the existing server-level
`rentv.access.log` and filters `/826/` authenticated lines itself. In single-source
mode (`LIVE_LOG == BACKFILL_LOG`) the first offset-0 pass backfills all history, then it
tails the delta (offset + inode tracked in `ingest_state`, so it survives restarts and
log rotation). A dedicated `access_log` in the `/826/` location is an optional future
optimization, not a dependency.