mere-analytics

module

v0.1.1 Latest Latest Go to latest Published: Jun 5, 2026 License: AGPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/jjdinho/mere-analytics

Links

Open Source Insights

README ¶

mere

The self-hostable open core version of Mere Analytics. A small analytics server: one Go binary, two databases (PostgreSQL + ClickHouse), no SaaS layer. You run it; you own the data.

Prefer not to operate it yourself? A cloud-hosted version is available for $9/month at usemere.com.

mere does three things:

Ingest events from anywhere — a browser snippet, a server SDK, a CLI, an agent — over a simple HTTP endpoint.
Store them in ClickHouse, scoped per project.
Expose them through a stable, versioned HTTP API, an MCP endpoint (so an LLM can query your analytics directly), and a small web UI with a SQL playground.

Self-hosters get the whole product. There is no "cloud-only" tier.

What's in the box

Ingest API — POST /api/v1/ingest/events, authenticated by a per-project public token. Batches of events land in ClickHouse via an in-process buffered pipeline with a Postgres dead-letter queue for transient outages.
Query API — POST /api/v1/projects/{id}/query runs arbitrary read-only ClickHouse SQL, scoped to one project. Tenant isolation is enforced by ClickHouse's additional_table_filters setting, not by rewriting your SQL.
Schema API — GET /api/v1/projects/{id}/schema returns the queryable table/column catalog.
MCP endpoint — /mcp exposes query and schema tools so an MCP client (e.g. Claude) can explore a project's analytics.
OAuth 2.1 server — PKCE authorization-code flow issues the bearer tokens for the query/schema/MCP surface. Lives in-process at /oauth/*.
Web UI — login, teams, projects, invite links, per-project ingest token, and a SQL query playground. Server-rendered (templ + htmx), no SPA.

Quickstart (local)

Requires Go 1.25+ and Docker.

git clone https://github.com/jjdinho/mere-analytics && cd mere-analytics
./scripts/dev          # brings up Postgres + ClickHouse, runs the server on :8080

scripts/dev starts the compose stack in docker/docker-compose.yml and boots the server with dev-friendly env (plaintext-cookie mode). There is no public signup — create the first user against the dev database:

psql "postgresql://mere:devpass@127.0.0.1:55432/mere" \
  -v email=you@example.com -v password=change-me-please \
  -f scripts/operator/create-user.sql

Then open http://localhost:8080/login.

Deploying

mere deploys with Kamal: a fresh VPS reaches a working, TLS-terminated deployment (app + Postgres + ClickHouse) from a single kamal setup. You build and push the image from your own machine with kamal deploy — there is no CI image pipeline and no pre-built public image to pull.

See docs/self-host.md for the from-zero walkthrough, the environment reference, operator actions, backups, and migration recovery.

Documentation

docs/api.md — the public HTTP + MCP API reference.
docs/self-host.md — how to run it in production.
docs/architecture.md — how it's built and why.
docs/extending.md — the extension seams and how to build your own binary that injects custom behavior without forking.

CLI

A companion command-line client lives in its own repo: mere-analytics-cli. Use it to send events and run queries against any mere server from your terminal.

Contributing

Pull requests are welcome. Every commit must be signed off (git commit -s), and submitting a contribution grants the maintainers the dual-licensing rights the hosted build depends on. See CONTRIBUTING.md for the sign-off requirement and the contribution license grant before you open a PR.

License

AGPL-3.0-or-later. Self-host, modify, and run mere freely — a self-hoster's rights are unrestricted. The network-copyleft (AGPL §13) means anyone who offers a modified mere as a network service must share their modifications. A separately-run hosted version is offered for those who'd rather not operate it themselves.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
app Package app is the importable composition root: the single exported entry point that builds and runs the fully-wired mere application.	Package app is the importable composition root: the single exported entry point that builds and runs the fully-wired mere application.
cmd
maintenance command Command mere-maintenance sweeps expired oauth_codes, oauth_access_tokens, and sessions rows out of Postgres.	Command mere-maintenance sweeps expired oauth_codes, oauth_access_tokens, and sessions rows out of Postgres.
server command Command mere-server is the analytics application binary.	Command mere-server is the analytics application binary.
extension Package extension holds the core's in-process extension seams: the small, stable set of interfaces (plus no-op defaults) a wrapper can implement to add behavior without modifying the core.	Package extension holds the core's in-process extension seams: the small, stable set of interfaces (plus no-op defaults) a wrapper can implement to add behavior without modifying the core.
internal
auth Package auth owns the application's authentication primitives: bcrypt password hashing, CSRF token generation, and the session lifecycle (create / lookup / touch / destroy).	Package auth owns the application's authentication primitives: bcrypt password hashing, CSRF token generation, and the session lifecycle (create / lookup / touch / destroy).
clickhouse Package clickhouse opens the application's ClickHouse connection pools (admin + readonly) and exposes a golang-migrate driver constructor.	Package clickhouse opens the application's ClickHouse connection pools (admin + readonly) and exposes a golang-migrate driver constructor.
config
idgen Package idgen is the single source of truth for ID generation across the app.	Package idgen is the single source of truth for ID generation across the app.
ingest Package ingest implements the analytics write path: POST /api/v1/ingest/events → validated batch → in-memory channel → flusher → ClickHouse events_raw_v1.	Package ingest implements the analytics write path: POST /api/v1/ingest/events → validated batch → in-memory channel → flusher → ClickHouse events_raw_v1.
maintenance Package maintenance sweeps expired rows out of operational Postgres tables that would otherwise grow monotonically: oauth_codes, oauth_access_tokens, and sessions.	Package maintenance sweeps expired rows out of operational Postgres tables that would otherwise grow monotonically: oauth_codes, oauth_access_tokens, and sessions.
mcp Package mcp exposes the analytics read surface (query + schema) as Model Context Protocol tools behind a single /mcp endpoint.	Package mcp exposes the analytics read surface (query + schema) as Model Context Protocol tools behind a single /mcp endpoint.
migrate Package migrate is the shared migration runner used by both Postgres and ClickHouse.	Package migrate is the shared migration runner used by both Postgres and ClickHouse.
oauth Package oauth implements a hand-rolled OAuth 2.1 authorization server for the analytics API + MCP surfaces.	Package oauth implements a hand-rolled OAuth 2.1 authorization server for the analytics API + MCP surfaces.
postgres Package postgres opens the application's Postgres connection pool and exposes a golang-migrate driver constructor for use by internal/migrate.	Package postgres opens the application's Postgres connection pool and exposes a golang-migrate driver constructor for use by internal/migrate.
postgres/db
query Package query owns the analytics read path.	Package query owns the analytics read path.
static Package static owns the embedded static-asset filesystem.	Package static owns the embedded static-asset filesystem.
testhelpers Package testhelpers provides shared testcontainers-go setup for PG and CH used by per-package integration tests and the e2e boot test.	Package testhelpers provides shared testcontainers-go setup for PG and CH used by per-package integration tests and the e2e boot test.
views templ: version: v0.3.1020	templ: version: v0.3.1020
web Package web wires the application's HTTP surface.	Package web wires the application's HTTP surface.
migrations Package migrations exposes the application's SQL migration files as embedded filesystems.	Package migrations exposes the application's SQL migration files as embedded filesystems.