Self-hosted, cookieless, privacy-first web analytics for personal sites and small teams.
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.
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.
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 -dOpen http://localhost:3000 and sign in with the admin password.
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 startSee .env.example for every configuration variable.
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 startDemo 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.
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"}'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.
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.
{"status": "ok", "version": "1.0.0", "sites": 2, "uptimeSeconds": 123}
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.
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.
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
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.
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.
MIT. See LICENSE.