Ultralytics

Self-hosted analytics for web applications. Track user behavior on your websites without sending data to third parties.

Why Ultralytics?

• Privacy-first: All data stays on your servers - no third-party tracking
• Lightweight client: ~3kb gzipped JavaScript library
• Framework integrations: React, Vue, Svelte, and vanilla JavaScript
• Production-ready: Docker, Kubernetes, and comprehensive monitoring
• Full control: Open source, self-hosted, and fully customizable

Quick Start

Docker (Recommended)

git clone https://github.com/aibubba/ultralytics.git
cd ultralytics
docker-compose up -d

Ultralytics is now running on http://localhost:3000. For detailed setup instructions, see the Getting Started Guide.

Installation

Install the client library from npm:

npm install ultralytics

Add to Your Website

<script src="https://your-server.com/ultralytics.min.js"></script>
<script>
  Ultralytics.init({
    endpoint: 'https://your-server.com',
    apiKey: 'your-api-key'
  });
</script>

Track Events

// Track page views
Ultralytics.trackPageView();

// Track custom events
Ultralytics.track('button_click', {
  buttonId: 'signup-button',
  page: '/pricing'
});

// Identify users
Ultralytics.identify('user-123', {
  email: '[email protected]',
  plan: 'premium'
});

Framework Integrations

All framework integrations are included in the main package:

npm install ultralytics

React

import { useUltralytics } from 'ultralytics/react';

function App() {
  const { track, identify } = useUltralytics({
    endpoint: 'https://your-server.com',
    apiKey: 'your-api-key',
    autoTrackPageViews: true
  });

  return (
    <button onClick={() => track('cta_clicked')}>
      Get Started
    </button>
  );
}

Vue

<script setup>
import { useUltralytics } from 'ultralytics/vue';

const { track } = useUltralytics({
  endpoint: 'https://your-server.com',
  apiKey: 'your-api-key'
});
</script>

Svelte

<script>
import { createUltralytics } from 'ultralytics/svelte';

const analytics = createUltralytics({
  endpoint: 'https://your-server.com',
  apiKey: 'your-api-key'
});
</script>

Features

Event Tracking

Track page views, user interactions, and custom events with rich metadata.

Session Management

Automatic session tracking with configurable timeout (default: 30 minutes).

User Identification

Associate events with authenticated users for cross-session analysis.

Analytics Queries

Built-in endpoints for funnels, cohorts, and time-series analysis.

Data Export

Export your data in CSV or JSON format for external analysis.

Privacy Controls

GDPR-compliant data deletion and anonymization capabilities.

Prometheus Metrics

Built-in /metrics endpoint for monitoring with Prometheus/Grafana.

Documentation

• Getting Started - Quick start guide
• Configuration - All configuration options
• API Reference - Complete REST API documentation
• Privacy - Privacy features and GDPR compliance
• Architecture - System design overview
• SSL Setup - HTTPS configuration

Deployment Options

Docker Compose

For development and simple deployments:

docker-compose up -d

Docker Compose (Production)

For production with nginx and SSL:

docker-compose -f docker-compose.prod.yml up -d

Kubernetes

For scalable production deployments:

kubectl apply -f k8s/

See Production Deployment for detailed instructions.

Development

Prerequisites

• Node.js 18+
• PostgreSQL 12+

Setup

npm install
cp .env.example .env
# Edit .env with your database credentials
npm run migrate:up
npm start

Running Tests

npm test

Building the Client

npm run build

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

Apache 2.0 - See LICENSE for details.

Support

• GitHub Issues - Bug reports and feature requests
• Documentation - Detailed guides and references