openanalytics README

The project's README from github.com/OpenLabs-so/openanalytics. As one markdown file: README.md.

OpenAnalytics

Open-source, privacy-first web analytics. One lightweight tracker script, no cookies, no cross-site profiles, aggregate-only reads — self-hostable on your own hardware under AGPL-3.0.

A hosted instance runs at getopen.so, operated by the authors: the same code, someone else's servers.

The Overview screen: visitors, pageviews, bounce rate, average visit and revenue across a day, with top pages, referrers and revenue underneath

▶ Watch the dashboard in motion, a tour of these same screens on YouTube.

What is in this repository

The product, as one pnpm monorepo:

App Role
apps/tracker The browser snippet — a few KiB, with a byte budget CI enforces
apps/collector Ingest: validates, sanitizes, rate-limits, enqueues
apps/worker Drains the queue into ClickHouse; sessions, rollups, exports, mail, deletions
apps/api Control plane: auth, sites, keys, sharing, event definitions, funnels, widgets, revenue, AI assistant, MCP
apps/query-gateway The only process allowed to read ClickHouse; verifies signed query envelopes
apps/realtime The SSE stream behind the live dashboard
apps/web The dashboard (Next.js)
apps/cli oa — site setup, stats, device-flow login
packages/* domain, postgres (+migrations), clickhouse (+migrations), redis, auth, contracts (OpenAPI), observability, integrations, migrations, testkit

Stores: Postgres (control plane), ClickHouse (events and rollups), Valkey ×2 (one durable event queue, one losable realtime cache).

What it does, in one list: page views, custom and attribute-driven events, sessions, web vitals, funnels, per-site retention, embeddable widgets, public share links, revenue analytics from your Stripe account, CSV/JSON import and export, an MCP server, and a CLI.

Who is on the site now, from a presence cache rather than a table scan. Names are generated per visitor and mean nothing outside the day they were minted.

The realtime screen: five visitors online with the page each is on, and everyone seen in the last 24 hours below them

Where one visitor went, session by session. The identity behind a trail is a salted hash that rotates every night, so the trail is as long as a visit and never as long as a person.

One visitor's trail: two visits, one arrived direct and one from X, each listing the pages opened inside it

Where they are, at city level and only when a site opts in. The lookup runs against a database on your own disk and never leaves the host.

A globe with visitors placed on it, one each in eastern Europe, north Africa, the Middle East and South America

Architecture rules CI enforces, not conventions:

Self-hosting

SELF-HOSTING.md is the guide: a generator script, one docker compose up -d, automatic TLS, and an explanation of every secret and every failure mode. Requirements are a Linux host with Docker, four DNS records, about 4 GB of RAM and 25 GB of free disk.

Installing is a pull, not a build. A release publishes ten images to ghcr.io/openlabs-so/openanalytics, so a fresh host is a few minutes and needs no toolchain on it.

Point four names at the host before you start. Certificates are issued on the first boot and issuance fails without them, half an hour later and nowhere near the cause:

app.example.com   api.example.com   c.example.com   rt.example.com

git clone https://github.com/OpenLabs-so/openanalytics
cd openanalytics
git checkout "$(git tag -l 'v*' --sort=-v:refname | sed '/-/d' | head -1)"   # newest release, not main
cd infra/selfhost
./generate-secrets.sh --domain example.com --email [email protected] --with-geoip
docker compose pull && docker compose up -d
# then open https://app.example.com and create the first account

The checkout is where the version is chosen, and it is chosen once. The generator reads the tag back out of the tree it is standing in and points .env at that release's images, printing which it picked and why; on a branch, on main, or with no git at all it writes the build defaults instead. That is not a convenience — the compose file, the env templates and the migrations ship with the images, so a release's images against another tree is a configuration nobody has tested.

Images are amd64. On arm64, or to run a branch, build the ten here instead: same compose file, one flag, about ten minutes and swap on a 4 GB box. Later, ./upgrade.sh moves between releases and takes the snapshot ./rollback.sh needs, because migrations do not go down: the way back is a restore, and a restore discards what arrived after the upgrade. It tells you that before it starts, not at rollback time when you no longer have a choice. RELEASING.md is what a version number here means.

To run it from source instead — for development, or to slot the services into infrastructure you already have — follow Running from source. The order matters and one obvious order does not work: the migration runners are compiled output, so pnpm run build comes before pnpm run migrate:postgres.

infra/selfhost/env/*.env.example documents every variable each service reads, and there is one file per service on purpose — the environment schema forbids some keys to some services, so a single shared .env cannot be correct. The AI assistant (OPENAI_API_KEY) and object storage are optional: unset, those surfaces disable themselves and everything else runs.

Run the test suite the way CI does:

pnpm run test          # unit + contract + tracker, no infrastructure needed
pnpm run verify        # everything CI checks, including boundaries and the size budget

Privacy model

No cookies, no fingerprinting, no cross-site identifiers. Visitor identity is a daily-rotating salted hash; raw IP addresses are never stored. Do Not Track and Global Privacy Control are honored at the collector, before anything is written. City-level geolocation is opt-in per site.

Geolocation is resolved locally against a database on your own disk — no lookup ever leaves the host. None is bundled (a 60 MB download, and stale within a month); infra/selfhost/geoip/fetch-dbip.sh downloads one.

IP Geolocation by DB-IP — https://db-ip.com — used under CC BY 4.0.

Contributing

Pull requests are merged here, with your name on the commit. This repository used to receive periodic exports from a private monorepo, and a merged PR was flattened by the next one; that ended in August 2026. A bot asks you to sign the CLA once — it is not an assignment, you keep your copyright — and there is no DCO sign-off on top of it.

CONTRIBUTING.md has the setup, the ground rules CI enforces, and where to start. Discussions are for questions and for ideas worth talking through first.

Security reports: SECURITY.md — please not a public issue.

License and trademark

Code: AGPL-3.0. If you run a modified OpenAnalytics as a network service, the AGPL requires you to offer your modified source to its users.

The "OpenAnalytics" name and the hosted service's domain identify the instance its authors operate and are not part of the license grant. A self-hosted instance runs the software, not the brand.

openanalytics (OpenLabs-so/openanalytics)

Searching Database…

630 ·GitHub
Openanalytics
What is this?OpenAnalytics is an open-source, privacy-first, cookieless web analytics platform with revenue attribution and a built-in MCP server. You can self-host it under AGPL-3.0 or use the hosted instance the authors run at getopen.so.
Is this one app or a bunch of services?It's a pnpm monorepo of several services: a tracker script, collector, worker, api, query-gateway, a realtime SSE stream, a Next.js dashboard, and a CLI called 'oa', backed by Postgres, ClickHouse, and two Valkey instances.
How do I get it running?Follow SELF-HOSTING.md: run the generator script, then 'docker compose up -d'. A release publishes ten prebuilt images to ghcr.io so you don't need a build toolchain, and TLS certificates are issued automatically on first boot.
What do I need before self-hosting it?A Linux host with Docker, four DNS records pointed at that host before you start, roughly 4 GB of RAM, and 25 GB of free disk.
Does the prebuilt install work on any machine?The published release images are amd64 only. On arm64, or if you want to run a branch instead of a tagged release, you have to build the ten images yourself from the same compose file, which takes about ten minutes.
Where can I run this?It's designed for self-hosting on a Linux host via Docker, with a Next.js web dashboard; the authors also run a hosted version so you don't have to run anything yourself.
How does it avoid tracking visitors the way Google Analytics does?There are no cookies or fingerprinting. Visitor identity is a salted hash that rotates every night, raw IP addresses are never stored, and Do Not Track / Global Privacy Control signals are honored at the collector before anything is written.
What happens if I modify it and run it as a hosted service?The code is AGPL-3.0, so running a modified version as a network service requires offering your modified source to its users. The 'OpenAnalytics' name and the getopen.so domain are trademarks of the authors, not part of the license grant.
What can the MCP server do?It lets AI assistants and agents query your analytics data directly through the Model Context Protocol, alongside a built-in AI assistant surface in the dashboard.
How does the revenue attribution feature work?It pulls revenue analytics straight from your connected Stripe account, so you can see which traffic sources actually drove paying customers.
Can I try it without hosting it myself?Yes — the authors run a hosted instance at getopen.so, the same code running on their own servers.
Is there a command-line way to manage sites?The included 'oa' CLI handles site setup, viewing stats, and device-flow login, without needing the web dashboard.
What are similar projects?analytics, umami, documenso, lago, rybbit, mission-control, rankme.fast, bisibility
Which topics is it in?valkey, web-analytics, stripe, sse, clickhouse, openapi, privacy-first, analytics, nextjs, agpl, postgresql, docker-compose
Creator
OpenLabs-so
Size
8.7 MB
Stars
630
Updated
CommitSep 29Releasev0.8.0Sep 19
Age
2mo
Commits · 90 Days