Skip to content

About

Self-hosted, cookieless, privacy-first web analytics with a DuckDB storage engine

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

PulseBoard

Self-hosted, cookieless, privacy-first web analytics for personal sites and small teams.

CI License: MIT Node

PulseBoard answers the questions a small site actually asks: how many pageviews, roughly how many visitors, which pages, where from, and on what browsers and devices. It runs as a single Node.js process with an embedded DuckDB database file. There is nothing else to operate: no external database server, no queue, no cloud account.

The privacy model

PulseBoard is built so that it cannot leak what it never collects.

Never collected or stored:

  • No cookies for visitors of tracked sites. The tracker sets nothing and reads nothing. (The dashboard login for the site owner uses one signed session cookie; that cookie only exists on the PulseBoard admin pages, never on your tracked site.)
  • No raw IP addresses. An event's IP is used in memory for a fraction of a second to compute a hash, then discarded. There is no IP column in the database, and a test enforces that.
  • No raw user agent strings. The user agent is parsed at ingest into coarse buckets (browser family, OS family, device class) and only the buckets are stored.
  • No full referrer URLs. Only the referrer's host name is kept, so query strings and tokens in referrer URLs are never persisted.
  • No localStorage, no canvas, no fingerprinting of any kind.

How unique visitors work, honestly: each event stores a 128-bit hash computed as sha256(dailySalt | ip | userAgent | siteId), where dailySalt = sha256(serverSecret | UTC date). The salt rotates every UTC day, so the same visitor produces a different hash tomorrow and cannot be followed across days. The trade-off is real and stated wherever the number appears: "unique visitors" is a per-day estimate. The same person counts once per day per site, and a multi-day total counts visitor-days, not people. If that estimate is not good enough for a decision, PulseBoard is the wrong tool for that decision.

Quickstart

Docker (recommended)

git clone https://github.com/RahilSahu/pulseboard.git
cd pulseboard
cat > .env <<'EOF'
PULSEBOARD_ADMIN_PASSWORD=a-long-random-password
PULSEBOARD_VISITOR_SECRET=another-long-random-value
PULSEBOARD_SITES=example.com
EOF
docker compose up -d

Open http://localhost:3000 and sign in with the admin password.

Node.js directly

Requires Node.js 20 or newer.

git clone https://github.com/RahilSahu/pulseboard.git
cd pulseboard
npm ci
npm run build
PULSEBOARD_ADMIN_PASSWORD=a-long-random-password \
PULSEBOARD_VISITOR_SECRET=another-long-random-value \
PULSEBOARD_SITES=example.com \
npm start

See .env.example for every configuration variable.

Try the demo data

The seed inserts clearly synthetic traffic for two demo sites (demo.example and blog.example, about 7,800 events over 30 days) so a fresh install shows a populated dashboard:

npm run build
export PULSEBOARD_ADMIN_PASSWORD=demo-password
export PULSEBOARD_VISITOR_SECRET=demo-secret
npm run seed
npm start

Demo sites are flagged in the database and the dashboard labels them "Demo site: the data below is synthetic seed data, not real traffic." Seed IPs come from the RFC 5737 documentation ranges reserved for examples.

Add the tracker to a website

Register the site first (admin API, or PULSEBOARD_SITES at boot), then add one script tag to every page:

<script async src="https://analytics.example.com/tracker.js" data-site="example.com"></script>

Replace the host with your PulseBoard address and data-site with the registered site id. The script is 693 bytes, sends one beacon per pageview with navigator.sendBeacon (fetch with keepalive as a fallback), and works without any further setup. If PulseBoard is served from the same origin as the site, the endpoint is derived from the script URL automatically; data-host can override it.

Server-side posting works too, for non-browser traffic:

curl -X POST https://analytics.example.com/api/collect \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:133.0) Gecko/20100101 Firefox/133.0' \
  -d '{"site":"example.com","path":"/pricing","title":"Pricing"}'

Dashboard

One page per site, with a site picker when several sites are registered and 24h / 7d / 30d ranges: stat cards for pageviews, unique visitors (estimate), views per visitor and tracked pages; a daily or hourly traffic chart (hand-rolled SVG, no chart library); top pages and top referrers tables; and browser, OS and device breakdowns. The whole UI is server-rendered HTML with one stylesheet and no frontend build step.

Login is rate limited per client IP: 5 attempts per 15 minutes by default, after which the login route answers 429 until the window passes. Attempts are counted whether they succeed or fail, so a correct password also waits out an exhausted window; that is the deliberate trade-off of an attempt budget. The counters live in memory and reset when the server restarts. Tune them with PULSEBOARD_LOGIN_MAX_ATTEMPTS and PULSEBOARD_LOGIN_WINDOW_MINUTES. Event collection is never throttled.

API reference

POST /api/collect (public)

Records one pageview. Body (JSON):

Field Type Required Notes
site string yes A registered site id, for example example.com
path string yes Must start with /, max 2048 chars
title string no Page title, truncated at 512 chars
referrer string no Full referrer URL; only the host is stored
screenWidth integer no 1 to 10000
language string no For example en-US, truncated at 35 chars

Responses: 200 {"ok": true} on success. 400 with {"error": "invalid event", "details": [...]} for malformed events, and 400 for an unregistered site. The user agent, IP address and accept time come from the request itself, never from the body.

GET /api/health (public)

{"status": "ok", "version": "1.0.0", "sites": 2, "uptimeSeconds": 123}

GET /api/stats?site=example.com&range=7d (admin session required)

Returns the same aggregates the dashboard renders: totals, a zero-filled time series (hourly for 24h, daily for 7d and 30d), top pages, top referrers, and browser, OS and device breakdowns with view shares. range is one of 24h, 7d, 30d (default 7d). All windows are UTC. Without a session: 401. With no sites registered: 404.

GET /api/sites and POST /api/sites (admin session required)

List registered sites, or register one: {"id": "blog.example.com", "name": "My blog"} returns 201, or 409 when the id already exists. Site ids are domain-like slugs.

Architecture notes

Why DuckDB. Analytics queries are aggregations over append-only events, which is exactly what a columnar engine is good at. DuckDB is embedded, so the whole product stays one process and one file, while still answering 30-day aggregations over millions of rows faster than a row store would. Storage lives in a single file (path from PULSEBOARD_DB_PATH, default ./data/pulseboard.duckdb) on a real disk. PulseBoard deliberately does not run on serverless hosts: an embedded file database needs durable local storage, so the supported run stories are Docker or Node on a machine you control.

Why a daily salt. Counting unique visitors without storing anything identifying is the central design problem of privacy-first analytics. The rotating salt bounds the lifetime of every visitor pseudonym to one day by construction, not by a cleanup job that might not run. The cost is the per-day estimate described above.

Stack. TypeScript on Node 24, Fastify for HTTP, @duckdb/node-api (the current official DuckDB Node client; the legacy duckdb package is unmaintained), Vitest for tests. The user agent parser is hand-written and intentionally coarse: it recognises mainstream browsers, operating systems and device classes, and long-tail agents land in "Unknown". A full UA database would be more precise and much heavier; the buckets are all the dashboard shows.

Layout.

src/
  config.ts     environment configuration
  privacy.ts    daily salt and visitor hash
  ua.ts         hand-written user agent parser
  validate.ts   collect payload validation
  db.ts         DuckDB wrapper, schema, inserts
  stats.ts      aggregation queries for the dashboard
  views.ts      server-rendered dashboard HTML and SVG chart
  server.ts     Fastify app: routes, auth, static files
  seed.ts       synthetic demo data generator
  main.ts       entry point
public/
  tracker.js    the 693-byte tracking snippet
  app.css       dashboard stylesheet
tests/          unit, storage, aggregation and HTTP API tests

Tests

58 tests across six suites: user agent parsing (a table of real UA strings), the privacy module (hash rotation plus a storage test that proves neither a raw IP nor a raw UA lands in the database), payload validation, aggregation logic against a seeded temporary DuckDB, HTTP API integration (collect to stats roundtrips, auth, error cases), and tracker guarantees (under 1 KB, no cookies or storage APIs). Run them with npm test. CI also runs the strict TypeScript typecheck, ESLint and a production build.

Roadmap

Ideas, in no promised order. None of these exist in v1.0.0:

  • Event types beyond pageviews (outbound clicks, custom events), with the same minimisation rules.
  • Data retention controls (drop events older than N days).
  • CSV export of aggregates.
  • A second storage view for real-time (last hour) traffic.

License

MIT. See LICENSE.

About

Self-hosted, cookieless, privacy-first web analytics with a DuckDB storage engine

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages