Skip to content
Back to search

openanalytics

Open-source, privacy-first and cookieless web analytics with revenue attribution and an MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openlabs-so--openanalytics/badge.svg)](/listings/openlabs-so--openanalytics)

HTML

<a href="/listings/openlabs-so--openanalytics"><img src="/api/listings/openlabs-so--openanalytics/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 194 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OpenAnalytics
  2. <a href="https://vercel.com/open-source-program">
  3. <img alt="Vercel OSS Program" src="https://vercel.com/oss/program-badge-2026.svg" />
  4. </a>
  5. Privacy-first web analytics. One lightweight tracker script, no
  6. cookies, no cross-site profiles, aggregate-only reads — self-hostable on your
  7. own hardware under AGPL-3.0.
  8. A hosted instance runs at **[getopen.so](https://getopen.so)**, operated by the
  9. authors: the same code, someone else's servers.
  10. <a href="https://neon.com"><img src="docs/images/neon-logo.svg" alt="Neon" width="180"></a>
  11. **Sponsored by the [Neon Open Source Program](https://neon.com).** Neon is the
  12. managed Postgres behind getopen.so and the one we recommend for self-hosting —
  13. see [Deploying with Neon](infra/selfhost/NEON.md).
  14. ![The Overview screen: visitors, pageviews, bounce rate, average visit and
  15. revenue across a day, with top pages, referrers and revenue
  16. underneath](docs/images/dashboard.png)
  17. ▶ **[Watch the dashboard in motion](https://www.youtube.com/watch?v=qS_yALtcreI)**,
  18. a tour of these same screens on YouTube.
  19. ## What is in this repository
  20. The product, as one pnpm monorepo:
  21. | App | Role |
  22. | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
  23. | `apps/tracker` | The browser snippet — a few KiB, with a byte budget CI enforces |
  24. | `apps/collector` | Ingest: validates, sanitizes, rate-limits, enqueues |
  25. | `apps/worker` | Drains the queue into ClickHouse; sessions, rollups, exports, mail, deletions |
  26. | `apps/api` | Control plane: auth, sites, keys, sharing, event definitions, funnels, widgets, revenue, AI assistant, MCP |
  27. | `apps/query-gateway` | The only process allowed to read ClickHouse; verifies signed query envelopes |
  28. | `apps/realtime` | The SSE stream behind the live dashboard |
  29. | `apps/web` | The dashboard (Next.js) |
  30. | `apps/cli` | `oa` — site setup, stats, device-flow login |
  31. | `packages/*` | domain, postgres (+migrations), clickhouse (+migrations), redis, auth, contracts (OpenAPI), observability, integrations, migrations, testkit |
  32. Stores: **Postgres** (control plane), **ClickHouse** (events and rollups),
  33. **Valkey ×2** (one durable event queue, one losable realtime cache).
  34. What it does, in one list: page views, custom and attribute-driven events,
  35. sessions, web vitals, funnels, per-site retention, embeddable widgets, public
  36. share links, revenue analytics from _your_ Stripe account, CSV/JSON import and
  37. export, an MCP server, and a CLI.
  38. **Who is on the site now**, from a presence cache rather than a table scan.
  39. Names are generated per visitor and mean nothing outside the day they were
  40. minted.
  41. ![The realtime screen: five visitors online with the page each is on, and
  42. everyone seen in the last 24 hours below them](docs/images/realtime.png)
  43. **Where one visitor went**, session by session. The identity behind a trail is
  44. a salted hash that rotates every night, so the trail is as long as a visit and
  45. never as long as a person.
  46. ![One visitor's trail: two visits, one arrived direct and one from X, each
  47. listing the pages opened inside it](docs/images/visitor-journey.png)
  48. **Where they are**, at city level and only when a site opts in. The lookup runs
  49. against a database on your own disk and never leaves the host.
  50. ![A globe with visitors placed on it, one each in eastern Europe, north Africa,
  51. the Middle East and South America](docs/images/live-globe.png)
  52. Architecture rules CI enforces, not conventions:
  53. - `apps/web` may import only `packages/contracts` — the OpenAPI document is the
  54. single seam between frontend and backend.
  55. - ClickHouse is reachable only through the query gateway, which verifies
  56. Ed25519-signed query envelopes minted by the api.
  57. - The tracker has a hard byte budget; a change that exceeds it fails CI.
  58. - The Postgres schema this repository builds contains no billing tables, and a
  59. CI job asserts that against a real database rather than a file list.
  60. ## Self-hosting
  61. **[SELF-HOSTING.md](SELF-HOSTING.md)** is the guide: a generator script, one
  62. `docker compose up -d`, automatic TLS, and an explanation of every secret and
  63. every failure mode. Requirements are a Linux host with Docker, four DNS records,
  64. about 4 GB of RAM and 25 GB of free disk.
  65. **Installing is a pull, not a build.** A release publishes ten images to
  66. `ghcr.io/openlabs-so/openanalytics`, so a fresh host is a few minutes and needs
  67. no toolchain on it.
  68. **Point four names at the host before you start.** Certificates are issued on
  69. the first boot and issuance fails without them, half an hour later and nowhere
  70. near the cause:
  71. ```
  72. app.example.com api.example.com c.example.com rt.example.com
  73. ```
  74. ```sh
  75. git clone https://github.com/OpenLabs-so/openanalytics
  76. cd openanalytics
  77. git checkout "$(git tag -l 'v*' --sort=-v:refname | sed '/-/d' | head -1)" # newest release, not main
  78. cd infra/selfhost
  79. ./generate-secrets.sh --domain example.com --email you@example.com --with-geoip
  80. docker compose pull && docker compose up -d
  81. # then open https://app.example.com and create the first account
  82. ```
  83. **The checkout is where the version is chosen, and it is chosen once.** The
  84. generator reads the tag back out of the tree it is standing in and points `.env`
  85. at that release's images, printing which it picked and why; on a branch, on
  86. `main`, or with no git at all it writes the build defaults instead. That is not
  87. a convenience — the compose file, the env templates and the migrations ship
  88. _with_ the images, so a release's images against another tree is a configuration
  89. nobody has tested.
  90. **Postgres can live on Neon instead of on the host.** The stack bundles a
  91. Postgres container, and [Neon](https://neon.com) is the managed option we
  92. recommend: four environment variables and one line in `.env`, and Postgres
  93. backups and point-in-time restore become Neon's job.
  94. **[infra/selfhost/NEON.md](infra/selfhost/NEON.md)** walks through it, including
  95. moving an existing install across.
  96. Images are amd64. On arm64, or to run a branch, build the ten here instead:
  97. same compose file, one flag, about ten minutes and swap on a 4 GB box. Later,
  98. `./upgrade.sh` moves between releases and takes the snapshot `./rollback.sh`
  99. needs, because **migrations do not go down**: the way back is a restore, and a
  100. restore discards what arrived after the upgrade. It tells you that before it
  101. starts, not at rollback time when you no longer have a choice.
  102. [RELEASING.md](RELEASING.md) is what a version number here means.
  103. To run it from source instead — for development, or to slot the services into
  104. infrastructure you already have — follow
  105. [Running from source](SELF-HOSTING.md#running-from-source). **The order matters
  106. and one obvious order does not work:** the migration runners are compiled
  107. output, so `pnpm run build` comes before `pnpm run migrate:postgres`.
  108. `infra/selfhost/env/*.env.example` documents every variable each service reads,
  109. and there is one file per service on purpose — the environment schema forbids
  110. some keys to some services, so a single shared `.env` cannot be correct. The
  111. AI assistant (`OPENAI_API_KEY`) and object storage are optional: unset, those
  112. surfaces disable themselves and everything else runs.
  113. Run the test suite the way CI does:
  114. ```sh
  115. pnpm run test # unit + contract + tracker, no infrastructure needed
  116. pnpm run verify # everything CI checks, including boundaries and the size budget
  117. ```
  118. ## Privacy model
  119. No cookies, no fingerprinting, no cross-site identifiers. Visitor identity is a
  120. daily-rotating salted hash; raw IP addresses are never stored. Do Not Track and
  121. Global Privacy Control are honored at the collector, before anything is written.
  122. City-level geolocation is opt-in per site.
  123. Geolocation is resolved locally against a database on your own disk — no lookup
  124. ever leaves the host. None is bundled (a 60 MB download, and stale within a month);
  125. `infra/selfhost/geoip/fetch-dbip.sh` downloads one.
  126. > IP Geolocation by DB-IP — [https://db-ip.com](https://db-ip.com) — used under
  127. > [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
  128. ## Contributing
  129. **Pull requests are merged here, with your name on the commit.** This
  130. repository used to receive periodic exports from a private monorepo, and a
  131. merged PR was flattened by the next one; that ended in August 2026. A bot asks
  132. you to sign the [CLA](CLA.md) once — it is not an assignment, you keep your
  133. copyright — and there is no DCO sign-off on top of it.
  134. [CONTRIBUTING.md](CONTRIBUTING.md) has the setup, the ground rules CI enforces,
  135. and where to start.
  136. [Discussions](https://github.com/OpenLabs-so/openanalytics/discussions) are for
  137. questions and for ideas worth talking through first.
  138. Security reports: [SECURITY.md](SECURITY.md) — please not a public issue.
  139. ## License and trademark
  140. Code: [AGPL-3.0](LICENSE). If you run a modified OpenAnalytics as a network
  141. service, the AGPL requires you to offer your modified source to its users.
  142. The browser tracker is the exception: `apps/tracker/` and the `oa.js` it builds
  143. are [MIT](apps/tracker/LICENSE), because it is the one file that runs on your
  144. site, not on the server. Embedding it creates no obligation under the AGPL.
  145. The "OpenAnalytics" name and the hosted service's domain identify the instance
  146. its authors operate and are **not** part of the license grant. A self-hosted
  147. instance runs the software, not the brand.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.