Install Pulse

Requirements

• Node.js 20.11 or newer (tested on Node 22 and 26). Check with node --version.
• About 30 MB of disk for the code and 250–350 bytes per stored event.
• A persistent directory for data/. Docker and PaaS filesystems are ephemeral unless you mount a volume.
• For public deployments: a domain, TLS (Caddy, Nginx, a load balancer or platform ingress) and a strong ADMIN_TOKEN.

Quick start

1. Get the code and start the server.

   cd pulse-analytics
   npm start

   The console prints listening http://localhost:4000 and the data directory in use.
2. Open the dashboard. Visit http://localhost:4000. On a fresh install the dashboard has no events yet, and shows the snippet to install.
3. Add a site. Edit sites.json (created on first run), then restart the server. See Add your site.
4. Install the tracker. Paste the snippet into your site's <head> and deploy. A pageview appears in the Live panel within seconds.
5. Set an admin token before going public.

   # macOS / Linux
   ADMIN_TOKEN="$(openssl rand -hex 24)" npm start
   
   # Windows PowerShell
   $env:ADMIN_TOKEN = -join ((48..57) + (97..102) | Get-Random -Count 48 | % {[char]$_})
   npm start

Windows notes

The commands in this guide use POSIX syntax. In PowerShell, set environment variables with $env:NAME = "value" for the current session, or use setx NAME "value" for future sessions. Quote paths that contain spaces. Stop the server with Ctrl+C; Pulse flushes pending events on shutdown.

Load demo data

To explore the dashboard before installing the tracker, generate 90 days of deterministic demo events for the two starter sites:

npm run seed -- --days 90 --reset
npm start

The seed writes directly into data/events/. It refuses to add duplicates unless --reset is passed. Use --days 30 for a smaller dataset.

Add your site

Pulse identifies each site with a short public ID. Edit sites.json in the project root (or the file pointed to by SITES_FILE):

{
  "sites": [
    { "id": "demo", "name": "Acme Studio", "domain": "acme.example" },
    { "id": "docs", "name": "Acme Docs", "domain": "docs.acme.example" }
  ]
}

• id — 2–32 characters: lowercase letters, digits, _ or -. It is embedded in the snippet and is not a secret.
• name — label shown in the dashboard switcher.
• domain — used to treat links from your own domain as direct traffic instead of referrals.

Restart the server after editing the file. Then add this to every page, before </head>:

<script defer src="https://stats.example.com/t.js" data-site="demo"></script>

The tracker derives the collector origin from its own src. If you serve t.js from a CDN, point it at the collector explicitly:

<script
  defer
  src="https://cdn.example.com/t.js"
  data-site="demo"
  data-endpoint="https://stats.example.com"
></script>

Snippet options

Test the install locally

The repository includes an instrumented static page and a tiny file server:

npm start        # collector on :4000
npm run example  # example site on :8080

Open http://localhost:8080 and click a button. The example uses data-dev="true" because Pulse ignores localhost by default. Verify the API directly:

curl http://localhost:4000/api/v1/health
curl "http://localhost:4000/api/v1/stats?site=demo&range=24h"

Custom events and opt-out

The tracker exposes a small global API. Call it after the script has loaded (for example from your own deferred script):

pulse.track('signup', { plan: 'pro', seats: 3 });
pulse.track('cta_click', { cta: 'hero' });

pulse.pageview(); // force a pageview after a client-side route change
pulse.optOut();   // stop tracking in this browser
pulse.optIn();    // resume tracking

Names may contain letters, digits, _, ., : and - (max 64 chars). Up to 10 properties are stored: keys max 40 chars, strings max 120, numbers and booleans accepted. Event names appear in the Custom events panel; properties stay in the JSONL data.

A privacy-friendly opt-out control can be a plain button:

<button type="button" onclick="pulse.optOut()">Opt out of analytics</button>

Configuration

All settings are environment variables. Defaults are suitable for local use.

Default geo headers: cf-ipcountry,x-vercel-ip-country,x-country-code,x-geo-country. Cloudflare and Vercel send the first two automatically. Without a CDN, run npm run geoip to look countries up locally from the free DB-IP database; only the country code is stored.

Authentication

When ADMIN_TOKEN is set, the dashboard asks for it and exchanges it for an HttpOnly, SameSite=Lax cookie valid for seven days. Collection stays public because the tracker cannot hold a secret.

# Scripts and CI can use a Bearer token
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://stats.example.com/api/v1/stats?site=demo&range=7d"

• Login attempts are limited to 10 per minute per IP.
• Changing ADMIN_TOKEN or SALT_SECRET invalidates existing sessions.
• In open mode (no token) the dashboard and read APIs are public. Never expose that to the internet.
• The editor can write files; always run it with ADMIN_TOKEN set on a public host.

Page editor

Pulse includes a small WYSIWYG editor for static HTML pages. It edits the body content of existing files in CONTENT_DIR; head tags, styles, scripts and body attributes are preserved.

1. Point CONTENT_DIR at a folder of .html files. The default is examples/static-site.
2. Open the dashboard and choose Page editor in the sidebar.
3. Pick a file, click into the page and edit. Use the toolbar for headings, lists, links and emphasis, or switch to View source for raw HTML.
4. Press Ctrl+S or Save page. The previous revision is written to file.html.bak.

Details and limits:

• Only .html/.htm files are listed, up to 200 files, three folders deep and 2 MB each. Dotfiles, symlinks and common vendor folders are skipped.
• Editing happens in a sandboxed same-origin preview; page scripts are blocked there, but they remain in the saved file.
• Saves are atomic (temp file + rename) and keep one .bak revision per page.
• The preview loads assets from /content/, which requires the admin session. The editor is disabled with EDITOR=0.
• Files are edited in place. If the folder is inside a container without a volume, edits disappear when the container is replaced.

Reverse proxy and TLS

Run Pulse behind a TLS-terminating proxy and set TRUST_PROXY=1, so rate limiting and visitor hashing see real client IPs. Without it, every visitor behind the proxy looks like the proxy's IP.

Caddy

stats.example.com {
    reverse_proxy 127.0.0.1:4000
}

Nginx

server {
    listen 443 ssl;
    server_name stats.example.com;

    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Start Pulse bound to localhost:

ADMIN_TOKEN="a-long-random-value" TRUST_PROXY=1 HOST=127.0.0.1 node server.js

If the proxy overwrites X-Forwarded-For (the Nginx config above appends), keep TRUST_PROXY=1 limited to that trusted hop. Do not enable it when clients can set forwarding headers themselves.

Docker

The repository includes a Dockerfile and docker-compose.yml. The image runs as the unprivileged node user, stores data in a named volume and exposes a health check.

cp .env.example .env
# edit .env and set a long ADMIN_TOKEN
docker compose up -d --build

The compose file points SITES_FILE at /data/sites.json; the first run creates the starter registry. Replace it with your own and restart:

docker compose cp ./sites.json pulse:/data/sites.json
docker compose restart pulse

Check logs and health:

docker compose logs -f pulse
curl http://localhost:4000/api/v1/health

To edit a host folder with the page editor, mount it into the container and point CONTENT_DIR at the mount, for example:

services:
  pulse:
    environment:
      CONTENT_DIR: /content
    volumes:
      - pulse-data:/data
      - ./examples/static-site:/content

On Linux, the container user (uid 1000) needs write permission on the mounted folder. The default image does not persist edits made inside /app; always mount the content directory if you use the editor.

Run as a service

Create /etc/systemd/system/pulse.service:

[Unit]
Description=Pulse analytics
After=network.target

[Service]
Type=simple
User=pulse
WorkingDirectory=/opt/pulse-analytics
Environment=PORT=4000
Environment=HOST=127.0.0.1
Environment=TRUST_PROXY=1
Environment=ADMIN_TOKEN=replace-with-a-long-random-value
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now pulse
sudo journalctl -u pulse -f

Keep the token out of world-readable unit files on shared systems; use EnvironmentFile= with mode 0600 instead. The data/ directory must be writable by the service user.

Backups and retention

Everything that matters lives in DATA_DIR:

• events/events-YYYY-MM-DD.jsonl — one append-only file per UTC day.
• .salt — the secret used for daily visitor hashes and admin cookies. Treat it as a credential.

For a consistent backup, stop Pulse (or accept losing up to the last 500 ms of events) and copy the folder:

tar -czf pulse-backup-$(date +%F).tar.gz data/

Restore by placing the folder back and starting the server. Files older than RETENTION_DAYS are deleted automatically at startup and once a day; adjust retention before restoring if you need older data. Backups are outside Pulse's control — delete them according to your own policy.

Troubleshooting

Health and diagnostics:

curl http://localhost:4000/api/v1/health

The response includes the store size, pending writes, write errors, loaded files and version. Logs are written to stdout for requests under /api/ and /t.js.

API reference

Read endpoints require auth when ADMIN_TOKEN is set. Collection is always public and CORS-enabled.

CSV datasets: pages, entry, exit, events, outbound, sources, countries, devices, browsers, os.

Privacy notes

• No cookies. The tracker uses sessionStorage for a 30-minute session and localStorage only for the opt-out flag.
• Raw IPs and user agents are hashed with a server secret and the current UTC day, then discarded. The 16-character pseudonym rotates at UTC midnight.
• Referrers are reduced to a source label and hostname. Country comes from CDN headers. Full referring URLs are not stored.
• DNT and GPC are honored by default, and bots, prefetches and prerenders are dropped at ingest.
• Retention is bounded by RETENTION_DAYS, and all data stays on your server.

Cookie-free does not automatically mean consent-free in every jurisdiction. Confirm your legal basis and retention policy for your context.