theia

Theia – Privacy‑First Server‑Side Analytics Overview Theia provides website traffic statistics without any client‑side JavaScript. It watches nginx access logs in real time, parses each line to extract path, referrer, user‑agent, IP, status code and bytes sent, hashes IPs for privacy, and stores the results in a local SQLite database. Because all processing happens on the server, the data is immune to ad‑blockers and does not rely on third‑party services. Installation Quick install: download the install script with curl or wget and run it with sudo bash. The script detects the architecture, installs the binary to /usr/local/bin/theia, adds a custom nginx log format for multi‑domain tracking (optional), creates a systemd service and prepares /var/lib/theia for data storage. Manual install is also supported – clone the repository, build with go build, copy the binary, create the data directory and install the provided systemd unit. Running the daemon The daemon tails the nginx access log and writes parsed records to the SQLite database. Example command: sudo theia daemon --log-path /var/log/nginx/access.log --db-path /var/lib/theia/theia.db Key flags: --log-path (default /var/log/nginx/access.log) and --db-path (default ./theia.db). Command‑line statistics The stats sub‑command reads the database and prints a summary table or JSON output. Typical usage: theia stats --db-path /var/lib/theia/theia.db Options allow changing the look‑back period (--days), filtering by host (--host), choosing output format (--format json|table) and adjusting the number of top entries (--top). HTTP API service The serve command launches a bearer‑token protected HTTP/JSON (or CSV) API on 127.0.0.1:8081. It can be proxied through nginx to expose it externally. Authentication can be supplied via a token file, an environment variable, or a command‑line flag. Endpoints include: GET /api/v1/stats – time‑series data GET /api/v1/stats/paths – top paths GET /api/v1/stats/referrers – top referrers GET /api/v1/stats/status-codes – status‑code breakdown Common query parameters: host, from, to, format, group_by, top. Shell completion Running theia completion detects the current shell and offers to install completion scripts for bash, zsh or fish. Service management Theia runs as a systemd unit. Use standard systemctl commands to start, stop, restart, view status and follow logs. How it works internally 1. Tail nginx log file in real time. 2. Parse each line for relevant fields. 3. Hash IP + user‑agent + date to preserve anonymity. 4. Detect bots and static‑asset requests automatically. 5. Write records asynchronously to SQLite (WAL mode) allowing concurrent readers. 6. Periodic cleanup removes hourly stats older than 60 days. Security considerations The daemon needs root or sudo access to read nginx logs. The API token should be stored in a file rather than on the command line to avoid exposure via the process list. Rate‑limiting and fail2ban rules for noisy scanners are recommended (see docs/nginx-hardening.md). Limitations * Only page‑view counts are collected; no client‑side events. * Data loss possible on abrupt crashes. * No built‑in web dashboard – users can consume the CLI output, the HTTP API, or query SQLite directly. License Apache License 2.0.