Skip to main content

Self-Hosting Overview

Run Ovyxa on your own infrastructure for complete control, data sovereignty, and unlimited events.

Why Self-Host?​

Full Data Control​

  • Data sovereignty: All analytics data stays on your infrastructure
  • No third parties: Zero data shared with external services
  • Regulatory compliance: Meet strict data residency requirements
  • Complete privacy: Perfect for sensitive industries (healthcare, finance, government)

Cost Efficiency​

  • Unlimited events: No per-event pricing
  • Scale economics: Better value at high volumes
  • Fixed costs: Predictable infrastructure expenses

Customization​

  • Code access: Modify and extend functionality
  • Custom integrations: Build proprietary features
  • White-label: Remove branding, use your own domain
  • Direct database access: Advanced analytics and custom reports

When to Self-Host?​

Good Fit​

  • High traffic sites: >1M events/month (cost savings)
  • Strict compliance: HIPAA, SOC 2, government regulations
  • Data residency: Must keep data in specific countries
  • Custom needs: Require code modifications or proprietary features
  • Technical capacity: Have DevOps/infrastructure team

Consider Cloud First​

  • Low traffic: Less than 10k events/month (free tier covers you)
  • No DevOps team: Prefer managed service
  • Quick start: Need analytics running today
  • Standard features: Existing features meet all needs

The cloud version is fully-featured and privacy-compliant. Only self-host if you have specific requirements.

Architecture Overview​

Ovyxa self-hosted stack consists of:

┌─────────────────────────────────────────┐
│         Client (Browser/App)            │
│  ┌───────────────────────────────────┐  │
│  │ Ovyxa Tracking Script (2KB) │  │
│  └───────────────────────────────────┘  │
└────────────────┬────────────────────────┘
                 │ HTTPS POST /e
                 ▼
┌─────────────────────────────────────────┐
│          Ingestion API (Node.js)        │
│  - Validates events                     │
│  - Normalizes data                      │
│  - Parses UA, geolocates IP             │
│  - Writes to ClickHouse                 │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│         ClickHouse (Analytics DB)       │
│  - Event storage                        │
│  - Aggregations                         │
│  - High-performance reads               │
└─────────────────────────────────────────┘
                 ▲
                 │
┌────────────────┴────────────────────────┐
│           Stats API (Node.js)           │
│  - Queries ClickHouse                   │
│  - Returns aggregated stats             │
│  - Powers dashboard & public API        │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│       Web Dashboard (Next.js)           │
│  - Overview, pages, sources             │
│  - Real-time stats                      │
│  - Goals & conversions                  │
└─────────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────┐
│       PostgreSQL (Metadata)             │
│  - User accounts                        │
│  - Site settings                        │
│  - API keys                             │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│          Redis (Caching)                │
│  - Session cache                        │
│  - Rate limiting                        │
│  - Daily unique estimation              │
└─────────────────────────────────────────┘

System Requirements​

Minimum (Dev/Testing)​

  • CPU: 2 cores
  • RAM: 4GB
  • Disk: 20GB SSD
  • Traffic: Up to 100k events/day
  • CPU: 4+ cores
  • RAM: 8GB+
  • Disk: 100GB+ SSD (grows with retention period)
  • Traffic: 1M+ events/day

High Volume (Enterprise)​

  • CPU: 8+ cores
  • RAM: 16GB+
  • Disk: 500GB+ NVMe SSD
  • Traffic: 10M+ events/day

Storage Estimation​

  • Raw events: ~500 bytes per event (compressed)
  • 1M events/month: ~6GB/year (12 month retention)
  • 10M events/month: ~60GB/year (12 month retention)
  • 100M events/month: ~600GB/year (12 month retention)

Plus overhead for aggregations, indexes, and PostgreSQL (~20% additional).

Deployment Options​

Best for:

  • Single-server deployments
  • Small to medium traffic
  • Simple management

Pros:

  • Easiest setup (5 minutes)
  • All services bundled
  • Good for most use cases

Cons:

  • Single point of failure
  • Manual scaling

Docker Compose Guide →

2. Kubernetes/Helm​

Best for:

  • Large-scale deployments
  • High availability requirements
  • Auto-scaling needs
  • Multi-region setups

Pros:

  • High availability
  • Auto-scaling
  • Rolling updates
  • Production-grade

Cons:

  • Complex setup
  • Requires K8s expertise

Kubernetes Guide →

3. Manual Installation​

Best for:

  • Custom requirements
  • Existing infrastructure
  • Learning/debugging

Configuration Guide →

Software Requirements​

Required​

  • Docker 24+ (if using Docker Compose)
  • Docker Compose 2.x (if using Docker Compose)
  • PostgreSQL 14+ (metadata storage)
  • ClickHouse 23+ (analytics storage)
  • Redis 7+ (caching, rate limiting)
  • Node.js 18+ (API servers)

Optional​

  • Kubernetes 1.25+ (if using Helm)
  • Nginx/Caddy (reverse proxy)
  • Let's Encrypt (SSL certificates)

Network Requirements​

Ports​

  • 443: HTTPS (public ingress)
  • 80: HTTP (optional, redirect to HTTPS)
  • 3000: API server (internal)
  • 3001: Web dashboard (internal)
  • 5432: PostgreSQL (internal)
  • 8123: ClickHouse HTTP (internal)
  • 9000: ClickHouse native (internal)
  • 6379: Redis (internal)

Only ports 80/443 need to be public. All other ports should be internal or firewalled.

DNS​

Set up DNS records pointing to your server:

  • analytics.yourdomain.com → Your server IP
  • cdn.yourdomain.com → Your server IP (optional, for script hosting)

Security Considerations​

SSL/TLS​

Required for production:

  • Use Let's Encrypt (free, automated)
  • Or provide your own certificates
  • Enforce HTTPS only (no HTTP)

Firewall​

Restrict access to internal services:

# Example: ufw (Ubuntu)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw deny 3000/tcp  # Block external API access
sudo ufw deny 5432/tcp  # Block external DB access
sudo ufw enable

Secrets Management​

  • Use strong passwords (generated, 32+ characters)
  • Store secrets in environment variables, not code
  • Rotate secrets regularly
  • Use secret management tools (Vault, AWS Secrets Manager) for production

Updates​

  • Subscribe to security announcements
  • Update regularly (monthly recommended)
  • Test updates in staging first

Support & Community​

Documentation​

Getting Help​

  • GitHub Issues: Bug reports, feature requests
  • Community Forum: Questions, discussions
  • Email: selfhosted@ovyxa.com

Enterprise Support​

For production deployments, we offer:

  • Architecture review
  • Installation assistance
  • Custom integrations
  • Priority support
  • SLA guarantees

Contact: enterprise@ovyxa.com

Licensing​

Ovyxa self-hosted is available under:

  • AGPLv3 (Community Edition)
  • Commercial License (with additional features and support)

See LICENSE.md for details.

Next Steps​

  1. Choose your deployment method:
  2. Review configuration options
  3. Set up backups
  4. Install and test

Self-hosting gives you complete control while maintaining Ovyxa' privacy-first principles.