Skip to main content

​
What is Iris Analytics?

Iris is a self-hosted, privacy-first web analytics platform. It consists of three independent layers that work together:

Client SDK

A lightweight TypeScript package (@bigchill101/iris) that runs in visitor browsers and tracks events automatically.

Backend Server

A fast Go + SQLite backend that ingests events and answers analytics queries.

Dashboard UI

A React dashboard that visualises pageviews, top pages, referrers, web vitals, and device breakdown.

​
Key features

No cookies

Identity is tracked anonymously using localStorage (visitor ID) and sessionStorage (session ID). No third-party cookies, ever.

Self-hosted

Deploy the entire stack — backend API and dashboard — in a single Docker container you control.

SPA-ready

Automatically detects route changes via history.pushState and popstate. Works with React, Next.js, Vue, and more.

Web Vitals

Captures LCP, INP, and CLS automatically using the web-vitals library.

Event batching

Queue events and flush them in a single request to reduce network overhead on high-traffic pages.

Custom events

Track any user action with iris.track("Event Name", { key: "value" }).

​
Architecture overview

The entire system flows from the visitor’s browser through the Go server to SQLite: 
Visitor Browser                Go Server :8080              SQLite
─────────────────              ────────────────             ───────
@bigchill101/iris  ──POST /api/event──▶  pkg/api/handler  ──▶  events
(web/src/index.ts)                        pkg/core/event         table
                                          pkg/db/sqlite
Dashboard Browser  ◀─ GET /api/stats ─── pkg/api/handler  ◀──  query
(dashboard/src)       GET /api/pages
                      GET /api/referrers
                      GET /api/vitals
                      GET /api/devices
                      GET /api/timeseries
                      GET /api/sites

​
Quick navigation

Quickstart

Get Iris running and tracking your first pageview in minutes.

SDK installation

Add the @bigchill101/iris client SDK to your website.

Self-hosting with Docker

Deploy the backend and dashboard using Docker Compose.

API Reference

Full reference for all backend HTTP endpoints.

Build docs developers (and LLMs) love

Get started for freeTalk to us