Files
faceclaw/stats-server/README.md
T

65 lines
2.6 KiB
Markdown

# stats.faceclaw.org
Receives the opt-in analytics reports the phone app sends (format:
PROTOCOL.md) and stores them in Postgres. A small Node server with no
framework, behind nginx on the `cumulus` VPS.
src/server.ts HTTP server: POST /v1/report, GET /healthz
src/report.ts report validation
src/db.ts storing a report
schema.sql tables and views (idempotent, applied on every deploy)
deploy.sh deploy from this working tree
deploy/ systemd unit, nginx site, env and one-time setup script
Node runs the TypeScript directly (type stripping, Node 22.18 or later), so
there is no build step. `npm run check` type-checks; `npm test` runs the
tests. The database test needs a scratch database:
`STATS_TEST_DATABASE=<name> npm test`, with the other `PG*` variables
pointing at its server.
## Deploying
./deploy.sh
copies this directory to `~/faceclaw-stats` on the server, installs the
dependencies, applies `schema.sql` and restarts the service. The first
time, it stops after copying, and the one-time root setup must be run there:
ssh -t cumulus 'sudo bash ~/faceclaw-stats/deploy/setup-server.sh'
That creates a Postgres role named after the deploy user and the
`faceclaw_stats` database on the Postgres 16 cluster (port 5433; the older
14 cluster on 5432 is left alone), installs and starts
`faceclaw-stats.service`, adds the nginx site, and gets its certificate
with certbot. It is safe to rerun. The nginx site is only installed the first
time, since certbot edits it afterwards, so later changes to
`deploy/nginx-site.conf` have to be made on the server too.
The service runs as the deploy user with `Restart=always`, so `deploy.sh`
restarts it by ending the process, without needing root.
## Privacy
nginx keeps no access log for this site and the server stores only the
report body, so the database has no IP addresses. Reports carry a random
install id that the phone deletes when analytics is turned off.
## Looking at the data
ssh cumulus psql -p 5433 faceclaw_stats
Views:
- `daily_counters`: counter totals per day, split by version, platform and
build, with how many installs reported each.
- `latest_reports`: each install's most recent report.
- `latest_snapshot_values`: snapshot values across installs' latest reports.
For example, installs and connection failures per version over the last
week:
select app_version, name, sum(total) as total, max(installs) as installs
from daily_counters
where day > current_date - 7 and name like 'g2.failure.%'
group by 1, 2 order by 1, 3 desc;