Metrixis — Day-One Guide

1 · Overview

Metrixis is a self-hosted, privacy-respecting web analytics platform you can deploy on Render (backend) and Vercel (frontend) in under 15 minutes. It tracks page views, scroll depth, and opted-in click events without storing raw IP addresses or using cookies for identity.

Privacy model

Raw IPs are never stored. Each IP is hashed with salted SHA-256 and truncated to 16 hex characters before being written to the database. Visitor identity is anonymous (random visitor_id in localStorage). There are no cookies, no login, and no third-party services in the data path.

Security zones

The API exposes three distinct security contexts:

2 · Architecture Diagram

Data flows from left/top to bottom. The tracker sends events to the API; the aggregation job rolls them up into daily stats; the dashboard reads only the rollup tables (plus live today data for the overview endpoint).

Key design decisions

3 · Verified Setup Steps

Verified on Windows 11 (PowerShell 5.1), Node 22.19.0, npm 11.7.0, 2025-07-23. All 7 steps passed (one required a Windows-specific fix).

• 1
  Read source files

  Confirm the following files exist before starting: README.md, server/package.json, client/package.json, server/.env.example, client/.env.example.

  ✅ PASS — all files present
• 2
  Create server/.env

  # Windows (PowerShell)
  Copy-Item server\.env.example server\.env
  
  # macOS / Linux
  cp server/.env.example server/.env

  Patch two defaults for local development:

  Variable	Default	Local override	Why
  PGSSL	true	false	Local Postgres has no SSL; pg rejects the connection otherwise
  DASHBOARD_URL	https://metrixis.vercel.app	http://localhost:5173	CORS must allow the local Vite origin
  DATABASE_URL	placeholder	Your real Postgres URL	Required for all DB-backed routes
  CRON_SECRET	placeholder	Any long random string	Protects the internal aggregate endpoint
  SESSION_SECRET	missing from template	Long random string	Salts IP hashes; absent = unsalted (security gap T2)

  ⚠️ SESSION_SECRET is not in .env.example — add it manually. Generate with:

  node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

  ✅ PASS
• 3
  Install server dependencies

  cd server
  npm install
  # → added 85 packages, no errors

  ✅ PASS
• 4
  Apply database schema

  Run once against your Postgres instance before starting the server:

  psql "postgres://user:password@host:5432/metrixis" -f server/db/schema.sql

  The schema creates: sites, events, daily_stats, daily_page_stats, daily_click_stats, daily_scroll_stats.

  ✅ PASS (configuration requirement; not a code defect if skipped — non-DB routes still work)
• 5
  Start the backend

  cd server
  node index.js
  # → Metrixis API listening on port 4000
  
  # Health check
  curl http://localhost:4000/api/health
  # → {"ok":true}

  The pool will log a background connection error if DATABASE_URL is a placeholder — this is non-fatal. The health endpoint and /tracker.js work without a database.

  ✅ PASS — health endpoint returned {"ok":true}
• 6
  Create client/.env and install frontend dependencies

  # Copy env (default value VITE_API_URL=http://localhost:4000 is correct)
  cp client/.env.example client/.env   # macOS/Linux
  Copy-Item client\.env.example client\.env  # Windows
  
  cd client
  npm install
  # → added 67 packages; 4 advisory vulnerabilities in dev tooling (non-blocking)

  ⚠️ 4 vulnerabilities (1 moderate, 3 high) in Vite dev tooling. Do not run npm audit fix without testing — it may introduce breaking upgrades.

  ✅ PASS with advisory note on dev-tooling vulnerabilities
• 7
  Start the frontend dev server

  # macOS / Linux
  cd client && npm run dev
  
  # Windows (PowerShell) — npm is a .cmd shim; use cmd.exe as launcher:
  Start-Process -FilePath "cmd.exe" -ArgumentList "/c","npm run dev" `
    -NoNewWindow -WorkingDirectory "$PWD\client"
  # → VITE v8.1.5  ready in ~1700 ms
  # → Local: http://localhost:5173/

  ⚠️ Windows gotcha: Start-Process -FilePath "npm" fails with "%1 is not a valid Win32 application" because npm is a .cmd shim, not a native binary. Always launch via cmd.exe /c.

  ✅ PASS — Vite dev server ready on http://localhost:5173

4 · Documentation Contradictions

13 issues found. Ordered by severity (high → low). Each was verified by reading the actual source file referenced.

HIGH — Must fix before first deploy

MEDIUM — Fix before sharing docs with users

curl -X POST "https://<render-url>/api/internal/aggregate?date=2026-07-23" \
  -H "x-cron-secret: <CRON_SECRET>"

LOW — Nice to fix, low operator impact

5 · First Tasks for New Contributors

Five concrete tasks ordered easy → harder. None requires a running database or Render account.

curl -X POST \
  "https://<your-render-url>/api/internal/aggregate?date=2026-07-23" \
  -H "x-cron-secret: <your CRON_SECRET>"

6 · Comprehension Quiz

8 questions. Click Show answer to reveal each answer.

node jobs/aggregate.js

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

curl -X POST \
  "https://<render-url>/api/internal/aggregate?date=2026-07-23" \
  -H "x-cron-secret: <CRON_SECRET>"