Skip to main content

​
Software Requirements

​
Runtime Environment

Databuddy requires Node.js version 20 or higher.
node --version
# Should output v20.0.0 or higher
Installation:
  • macOS/Linux: Use nvm
  • Windows: Download from nodejs.org
  • Docker: Node.js is included in container images

​
Database Systems

PostgreSQL 17

Purpose: User data, configuration, authenticationMinimum Version: PostgreSQL 15Recommended: PostgreSQL 17Stores relational data including users, organizations, websites, API keys, and application configuration.

ClickHouse 25.5+

Purpose: Analytics events and metricsMinimum Version: ClickHouse 24.0Recommended: ClickHouse 25.5.1 AlpineStores high-volume time-series analytics data, web vitals, errors, and custom events.
Redis 7 (Required)
  • Caching layer for query results
  • Session storage
  • Rate limiting
  • Background job queues

​
Optional Components

For high-scale deployments, Databuddy can use Redpanda for event ingestion:
  • Version: 25.2.9+
  • Purpose: Buffer analytics events before ClickHouse ingestion
  • Recommended for: 10M+ events/day
Redpanda is Kafka-compatible but lighter weight and easier to operate.
Docker simplifies deployment significantly:
  • Docker Engine 20.10+
  • Docker Compose v2.0+
See our Docker setup guide for details.

​
Hardware Requirements

Hardware needs vary based on your analytics volume. Here are recommended specifications:

​
Small Deployment

< 1 million events/day
​
CPU
4 cores
​
RAM
8 GB
​
Storage
100 GB SSD
​
Network
100 Mbps
Example Use Case: Small SaaS application, personal projects, staging environments

​
Medium Deployment

1-10 million events/day
​
CPU
8 cores
​
RAM
16 GB
​
Storage
500 GB SSD
​
Network
1 Gbps
Example Use Case: Growing SaaS products, e-commerce sites, content platforms

​
Large Deployment

10-100 million events/day
​
CPU
16+ cores
​
RAM
32+ GB
​
Storage
1+ TB NVMe SSD
​
Network
10 Gbps
Example Use Case: Enterprise applications, high-traffic platforms
For very large deployments (100M+ events/day), consider distributed ClickHouse clusters. Contact our team for architecture guidance.

​
Storage Considerations

ClickHouse Storage Estimates:
  • Average event size: ~1-2 KB compressed
  • 1M events/day = ~1.5 GB/day = ~45 GB/month
  • 10M events/day = ~15 GB/day = ~450 GB/month
Data Retention: 
-- ClickHouse automatically handles TTL for older data
-- Default retention periods:
Events: 1 year
Error spans: 90 days  
Web vitals: 1 year
Blocked traffic: 6 months
You can adjust TTL settings in your ClickHouse configuration.

​
Network Requirements

​
Ports

Ensure these ports are accessible:
ServicePortProtocolPurpose
PostgreSQL5432TCPDatabase connections
ClickHouse HTTP8123TCPHTTP interface
ClickHouse Native9000TCPNative protocol
Redis6379TCPCache connections
API Server3001TCPAPI endpoints
Dashboard3000TCPWeb interface

​
Firewall Rules

1

Allow application servers to databases

Your API servers need access to PostgreSQL (5432), ClickHouse (8123, 9000), and Redis (6379).
2

Expose API and Dashboard publicly

Make ports 3000 (dashboard) and 3001 (API) accessible from the internet or your internal network.
3

Restrict database access

PostgreSQL, ClickHouse, and Redis should NOT be directly accessible from the public internet. Use firewalls or security groups to restrict access to application servers only.

​
Operating System

Databuddy runs on any system supporting Node.js and Docker:
  • Linux: Ubuntu 22.04+, Debian 12+, RHEL 9+, Alpine Linux (recommended for containers)
  • macOS: macOS 12+ for development
  • Windows: Windows 10+ with WSL2 for development
Production Recommendation: Ubuntu 22.04 LTS or 24.04 LTS

​
Cloud Provider Recommendations

Databuddy works on any cloud provider or bare metal. Popular choices:

AWS

  • EC2 for compute
  • RDS for PostgreSQL
  • ECS/EKS for containers

Google Cloud

  • Compute Engine
  • Cloud SQL
  • GKE for Kubernetes

DigitalOcean

  • Droplets
  • Managed PostgreSQL
  • App Platform
Budget-Friendly Options:
  • Hetzner Cloud
  • Linode/Akamai Cloud
  • OVHcloud

​
Development Requirements

If you’re contributing to Databuddy or running from source: 
{
  "engines": {
    "node": ">=20"
  },
  "packageManager": "bun@1.3.4"
}
Additional Tools:
  • Git for version control
  • Turborepo (installed via Bun)
  • TypeScript 5.9+
  • Drizzle ORM for database migrations

​
Next Steps

Docker Setup

Ready to deploy? Continue with our Docker setup guide.