Databuddy: open-source cookieless product analytics on ClickHouse, PostgreSQL and Redis

Databuddy tracks visitors and events without cookies, using ClickHouse for analytics and PostgreSQL for app state

Databuddy is a TypeScript analytics platform aimed at startups. A single tracking script collects data on visitors, custom events, funnels and goals without using cookies, with optional error tracking and web vitals available as additional opt-in features. Databunny, the built-in AI analyst, answers questions about the collected data and shows the query it ran to produce each answer, so an analyst can verify what the system actually computed rather than trusting the output alone.

Three data stores make up the infrastructure. ClickHouse stores analytics events, and Databunny queries it to produce its answers. PostgreSQL stores application state including user accounts, websites and configuration. Redis handles background job queues. The development Docker Compose file pins specific versions: `postgres:17`, `clickhouse/clickhouse-server:25.5.1-alpine`, and `redis:7-alpine`. Redis runs with `--maxmemory 512mb --maxmemory-policy noeviction`, which means new writes fail when memory is full rather than silently evicting existing keys.

Beyond analytics, the same dashboard covers feature flags, short links and uptime monitoring. The repository topics include `gdpr`, `gdpr-compliant`, and `mcp`, indicating integrations with GDPR-focused deployments and the Model Context Protocol.

Self-hosting requires a published release with the databuddy-init image, which is not yet available

The self-hosting documentation opens with an explicit blocker: the `databuddy-init` image needed to initialize the databases has not been published yet. The README tells operators to check the releases page before starting, which means attempting the Docker Compose setup before that image exists will fail at the init step.

When a release is available, setup starts by cloning the repository and checking out the release tag.

git clone https://github.com/databuddy-analytics/Databuddy.git
cd Databuddy
git checkout YOUR_RELEASE_TAG
cp selfhost.env.example .env

`YOUR_RELEASE_TAG` is a placeholder that the README uses because no specific version is available to name. The latest published GitHub release is v0.1.0-beta.1, tagged on 2026-04-22. The first two releases, v0.0.1 and v0.0.0, both appeared on 2026-03-31. All three releases carry beta labeling. The README describes self-hosting as still evolving and asks operators who get stuck to file a GitHub issue or ask in Discord.

For those who want to avoid running their own infrastructure, the README points to the hosted version at `app.databuddy.cc`. Self-hosting and hosted are the two documented paths. No partial mode exists that sidesteps Docker Compose for operators who want to run individual components on existing infrastructure.

Six .env variables must be set before the first docker compose run, including two separate secrets

Before running the stack, the `.env` file needs at minimum six values. `IMAGE_TAG` must match the release tag you checked out. `POSTGRES_PASSWORD`, `CLICKHOUSE_PASSWORD`, and `REDIS_PASSWORD` must each be URL-safe strings so they can appear safely in database connection URLs. `BETTER_AUTH_SECRET` and `DATABUDDY_ENCRYPTION_KEY` must be separate random secrets and must not reuse each other's values.

The README recommends generating each secret independently with `openssl rand -hex 32`. The `DATABUDDY_ENCRYPTION_KEY` is the most consequential of the six: it controls encryption of stored data, and the upgrade documentation warns explicitly to preserve the same key across upgrades because replacing it after data exists makes that data unreadable.

With `.env` configured, starting the stack takes two commands.

# Start the databases and create their schemas
docker compose -f docker-compose.selfhost.yml run --rm init

# Build the dashboard for your URLs and start the apps
docker compose -f docker-compose.selfhost.yml up -d --build

The running stack includes the dashboard, API, Basket event collector, uptime worker and short-link service. The short-link service listens on port 2500 by default. All port assignments are configurable in `docker-compose.selfhost.yml`. For a public deployment, the README specifies replacing the template's local URLs with HTTPS URLs and keeping the dashboard and API on the same parent domain.

Dashboard public URLs bake into the browser bundle and require a rebuild after any URL change

The dashboard is a Next.js application whose public URL variables are compiled into the browser bundle at build time. The relevant variables are `NEXT_PUBLIC_APP_URL`, `NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_BASKET_URL`, `NEXT_PUBLIC_LINKS_URL`, and `NEXT_PUBLIC_STATUS_URL`. Changing any of these after the initial build has no effect until the dashboard is rebuilt by running `docker compose -f docker-compose.selfhost.yml up -d --build` again.

On a PaaS platform without a shared parent domain, such as `*.up.railway.app`, the cookie domain approach breaks down. The recommended path is to leave `BETTER_AUTH_COOKIE_DOMAIN` empty and set `API_PROXY_URL` on the dashboard to the API's internal URL, then rebuild. On such a platform, the prebuilt dashboard image cannot be used because its URLs are baked in; the dashboard must be compiled from `dashboard.Dockerfile`.

`MCP_URL` must be set to the dashboard's public URL on both the dashboard and the API so that MCP clients can locate OAuth sign-in on the correct origin. Omitting this setting means MCP clients will not find the authentication endpoint.

`BETTER_AUTH_COOKIE_DOMAIN` controls whether login sessions are shared across subdomains. Setting it to `.example.com` enables session sharing across all subdomains of that domain, while leaving it empty restricts each subdomain to its own session.

Upgrading means reviewing PostgreSQL schema prompts and running two separate ClickHouse migration commands

Upgrading an existing self-hosted instance follows a specific sequence. Backing up the databases and the `.env` file before starting is the first requirement, since the process involves schema changes that cannot be automatically reversed. After checking out the new release in the same directory and updating `IMAGE_TAG`, the commands pull updated images and run the PostgreSQL migration.

docker compose -f docker-compose.selfhost.yml pull --ignore-buildable
docker compose -f docker-compose.selfhost.yml pull init
docker compose -f docker-compose.selfhost.yml run --rm init bun run --cwd packages/db db:push

The `db:push` command may present prompts for schema changes. The README instructs operators to stop the upgrade rather than proceed if they decline any change, because running new application code against a partially applied schema would produce inconsistency. This decision point cannot be automated away by the tooling.

ClickHouse schema updates are additive only. Running the ClickHouse setup script adds missing tables, views, columns and indexes without touching objects that already exist.

docker compose -f docker-compose.selfhost.yml run --rm init bun --cwd packages/db src/clickhouse/setup.ts

With `CLICKHOUSE_CLUSTER` set, single-node column and index additions do not run automatically and must be applied by hand. Any extra migrations listed in the release notes must also be applied before restarting the updated services with `docker compose -f docker-compose.selfhost.yml up -d --build`.

Cookieless analytics versus cookie-based tracking: what the approach difference means in practice

Cookie-based analytics platforms, including Google Analytics, write persistent identifiers to the browser that enable cross-session user tracking. Under GDPR and related European privacy regulations, deploying such tools typically requires a cookie consent banner before the tracking script loads. If a visitor declines consent, no data is collected at all for that session.

Rather than writing a persistent identifier to the browser, Databuddy derives session and visitor data from request-level signals. The README and repository topics both use `gdpr-compliant` to describe this approach. Operators who adopt Databuddy for analytics may not need a cookie consent mechanism specifically for the analytics script, though the precise legal requirements depend on the specific data collected and the jurisdiction.

The practical trade-off is infrastructure cost. A hosted cookie-based analytics service requires no servers on the operator's side, while a self-hosted Databuddy instance requires three running data stores plus Docker Compose and ongoing maintenance. The hosted version at `app.databuddy.cc` removes the infrastructure requirement but moves data outside the operator's control. Self-hosting exists precisely for operators who need to control where the data resides.

AGPL-3.0 with two MIT exceptions, Bun 1.2.0 or later, and a dedicated dql_user required for DQL access

The licence is AGPL-3.0 for the main codebase. Two packages are MIT instead: `packages/scan` and `packages/pulumi`, each with their own `LICENSE` files. AGPL-3.0 requires making source code available to users who access the software over a network, which extends the disclosure obligation beyond binary distribution to SaaS-style deployments. For a startup running Databuddy only for internal analytics, this obligation applies to Databuddy itself. For any service where external users connect over a network and the code incorporates Databuddy, the source disclosure obligation applies to that deployed service and its modifications.

The `package.json` sets engine requirements at Node.js 20 or later and Bun 1.2.0 or later. The package manager is pinned at `[email protected]`. Several internal services run on Bun.

The `.env.example` file includes a prominent warning about DQL access: `CLICKHOUSE_DQL_URL` must point at a separately provisioned `dql_user` account and must never share the application or admin ClickHouse credentials. The README adds that the DQL connection should use HTTPS outside loopback. A setup script for the restricted user is at `packages/db/src/clickhouse/dql.ts`. Without this separation, a compromise of the DQL interface would expose the full ClickHouse admin account.

Editorial conclusion

Databuddy suits a startup that wants cookieless, GDPR-oriented product analytics in a single dashboard and has the capacity to operate PostgreSQL, ClickHouse and Redis. Skip it when you need a stable production release right now, since the self-hosting init image had not been published as of the last documented state. Before starting, check the releases page to confirm the `databuddy-init` image is available, generate `DATABUDDY_ENCRYPTION_KEY` with `openssl rand -hex 32` before the first run and preserve it unchanged across upgrades, and read the AGPL-3.0 terms if you plan to offer Databuddy-backed services to third parties.

Frequently asked questions

Official sources

1. databuddy-analytics/Databuddy on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases