Databuddy

A comprehensive analytics and data management platform built with Next.js, TypeScript, and modern web technologies. Databuddy provides real-time analytics, user tracking, and data visualization capabilities for web applications.

🌟 Features

• 📊 Real-time analytics dashboard
• 👥 User behavior tracking
• 📈 Advanced data visualization // Soon
• 🔒 Secure authentication
• 📱 Responsive design
• 🌐 Multi-tenant support
• 🔄 Real-time updates // Soon
• 📊 Custom metrics // Soon
• 🎯 Goal tracking
• 📈 Conversion analytics
• 🔍 Custom event tracking
• 📊 Funnel analysis
• 📈 Cohort analysis // Soon
• 🔄 A/B testing // Soon
• 📈 Export capabilities
• 🔒 GDPR compliance
• 🔐 Data encryption
• 📊 API access

📚 Table of Contents

1. How do I get started? Follow the Getting Started guide.

• Contributing
• Security
• FAQ
• Support
• License

Prerequisites

• Bun 1.3.4+
• Node.js 20+

🏠 Self-Hosting

Databuddy can be self-hosted using Docker Compose. The repo includes two compose files:

File	Purpose
docker-compose.yaml	Development only — starts infrastructure (Postgres, ClickHouse, Redis) for local dev
docker-compose.selfhost.yml	Production / self-hosting — full stack with all application services from GHCR images

Quick Start

# 1. Configure environment
cp .env.example .env
# Edit .env — at minimum set BETTER_AUTH_SECRET and BETTER_AUTH_URL

# 2. Start everything
docker compose -f docker-compose.selfhost.yml up -d

# 3. Initialize databases (first run only)
docker compose -f docker-compose.selfhost.yml exec api bun run db:push
docker compose -f docker-compose.selfhost.yml exec api bun run clickhouse:init

Services started:

• API → localhost:3001
• Basket (event ingestion) → localhost:4000
• Links (short links) → localhost:2500
• Uptime monitoring is optional — uncomment in the compose file and set QStash keys.

All ports are configurable via env vars (API_PORT, BASKET_PORT, etc.). See the compose file comments for the full env var reference.

Troubleshooting

If the init job fails and Postgres logs show password authentication failed for user "databuddy", the Postgres volume was likely initialized with an older password.

Changing POSTGRES_PASSWORD or DATABASE_URL in your environment does not update the password stored inside an existing Postgres data volume.

To keep the existing data, update the password inside the running Postgres container to match your current environment and redeploy:

docker exec -it databuddy-postgres psql -U databuddy -d databuddy

Then inside psql:

ALTER USER databuddy WITH PASSWORD 'your-current-postgres-password';

Make sure the password in DATABASE_URL matches the same value.

If you do not need to preserve the database, remove the existing volume and start fresh so Postgres initializes with the current environment values:

docker compose -f docker-compose.selfhost.yml down -v
docker compose -f docker-compose.selfhost.yml up -d

🤝 Contributing

See CONTRIBUTING.md for guidelines.

🔒 Security

See SECURITY.md for reporting vulnerabilities.

❓ FAQ

General

1. What is Databuddy? Databuddy is a comprehensive analytics and data management platform.

2. How do I get started? Follow the Getting Started guide.

3. Is it free? Check our pricing page.

Technical

1. What are the system requirements? See Prerequisites.

2. How do I deploy? See the deployment documentation in our docs.

3. How do I contribute? See Contributing.

💬 Support

• Documentation
• Discord
• Twitter
• GitHub Issues
• Email Support

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.

Copyright (c) 2025 Databuddy Analytics, Inc.