Understand how people use your product: where they come from, what they do, and where they drop off. Use that insight to decide what to build or improve next.
- Building a product? Try hosted Databuddy or follow the tracker setup guide.
- Running your own stack? Start with self-hosting below.
- Want to help build Databuddy? Read the contributor guide. Bug reports and docs fixes count too.
Run Databuddy on your server with Docker Compose. It sets SELFHOST=true, so
events go straight to ClickHouse, while hosted billing and Databuddy's own telemetry are disabled.
Email and AI are optional; see optional services.
These steps need a release with the databuddy-init image. None is published yet;
check releases before starting.
You'll need Git and Docker Compose for this setup.
git clone https://github.com/databuddy-analytics/Databuddy.git
cd Databuddy
git checkout YOUR_RELEASE_TAG
cp selfhost.env.example .envIn .env, set:
IMAGE_TAGto the release you checked out.POSTGRES_PASSWORD,CLICKHOUSE_PASSWORD, andREDIS_PASSWORDto URL-safe passwords.BETTER_AUTH_SECRETandDATABUDDY_ENCRYPTION_KEYto separate random secrets.
The template includes local URLs. Compose supplies database connections,
SELFHOST, and browser settings; you don't need to repeat them in .env.
Generate each password and secret separately with openssl rand -hex 32.
Then start Databuddy:
# 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 --buildOpen your dashboard URL, create an account, and add your first website.
The stack includes the dashboard, API, Basket event collector, and short-link
service (port 2500). Ports are configurable in docker-compose.selfhost.yml.
For a public instance, replace the template's local URLs with your HTTPS URLs.
Keep the dashboard and API on the same parent domain. Set BETTER_AUTH_COOKIE_DOMAIN, such as .example.com,
to share login across subdomains. Leave it empty for localhost. Rebuild the
dashboard after changing public URLs; they're part of its browser bundle.
-
Email: For resets, invitations, and alerts, set
RESEND_API_KEYand anEMAIL_FROMsender on your verified domain, such asDatabuddy <[email protected]>. LeaveALERTS_EMAIL_FROMempty to use the same sender. Recreate the services after changes. -
Insights: Set
AI_GATEWAY_API_KEYandCOMPOSE_PROFILES=insightsin.env, then rerundocker compose -f docker-compose.selfhost.yml up -d --build. Website research also needsFIRECRAWL_API_KEY. -
Status pages: Deploy the status app separately with Node, Bun, and dependencies. From the repo root, set your API and status URLs before building:
export NEXT_PUBLIC_SELFHOST=true export NEXT_PUBLIC_API_URL=https://api.example.com export NEXT_PUBLIC_STATUS_URL=https://status.example.com NODE_ENV=production bun run --cwd apps/status build NODE_ENV=production bun run --cwd apps/status start
The app listens on port
3002. Set the matchingSTATUS_URLin your Compose.envand rebuild the dashboard to enable public links. -
DQL: Requires separate setup: a restricted
dql_userandCLICKHOUSE_DQL_URLpassed to the API in Compose. Use HTTPS outside loopback and never use the application's admin credentials. See the DQL setup script.
Self-hosting is still evolving. If you get stuck, tell us what happened or ask in Discord.
Back up your databases and .env, check out the new release in the same directory,
and update IMAGE_TAG.
Keep your existing DATABUDDY_ENCRYPTION_KEY so stored data stays readable.
Pull the images, then apply PostgreSQL changes so you can review any prompts:
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:pushIf you decline a change, stop the upgrade. After accepting the changes, create any missing ClickHouse tables and views:
docker compose -f docker-compose.selfhost.yml run --rm init bun --cwd packages/db src/clickhouse/setup.tsThis creates missing objects; it doesn't update existing ones. Apply any extra
migrations in the release notes before starting the updated apps with
docker compose -f docker-compose.selfhost.yml up -d --build.
Docs · Discord · GitHub issues · Email
Found a security issue? Please follow SECURITY.md.
AGPL-3.0. Copyright (c) 2025 Databuddy Analytics, Inc.
