A Google Analytics alternative, written in node and typescript
- TypeScript 95.5%
- Shell 1.5%
- HTML 1.4%
- JavaScript 0.8%
- CSS 0.5%
- Other 0.3%
| backend | ||
| frontend | ||
| tracking | ||
| .env.example | ||
| .gitignore | ||
| apply-migrations.sh | ||
| cleanup_duplicates.sh | ||
| cleanup_duplicates.sql | ||
| docker-compose.yml | ||
| IMPROVEMENTS.md | ||
| LICENSE | ||
| Makefile | ||
| NEW_FEATURES.md | ||
| README.md | ||
| test-tracking.html | ||
| UI_FEATURES.md | ||
Analytics - Privacy-Respecting Web Analytics
Version 2.0.0
A modern, open-source, privacy-first analytics platform built as an alternative to Google Analytics. Track your website visitors without compromising their privacy.
Features
Core Analytics
- Privacy-First: No cookies, anonymized IPs, no personal data collection
- Beautiful Dashboard: Modern UI with dark mode and comprehensive visualizations
- Multi-Website Support: Manage analytics for multiple websites from one dashboard
- Real-Time Stats: See active visitors and live pageview data
- Custom Events: Track user interactions beyond pageviews
- Self-Hosted: Full control of your data with Docker deployment
- Fast & Scalable: Built on PostgreSQL + TimescaleDB for time-series optimization
Engagement Analytics
- Entry & Exit Pages: See where visitors land and where they leave
- Return Visitor Tracking: New vs returning visitor metrics
- Session Analytics: Page depth distribution and session flow analysis
- Retention Metrics: Average visit days and sessions per visitor
Behavior Analytics
- Scroll Depth Tracking: Monitor how far users scroll on pages
- Click Heatmaps: Visualize where users click (coming soon)
- User Experience Issues: Track rage clicks and dead clicks (coming soon)
Content Analytics
- Page Performance: Detailed page statistics with time on page
- Reading Progress: Track content engagement metrics (coming soon)
- 404 Error Tracking: Monitor broken links and missing pages
- Search Query Tracking: Internal site search analytics (coming soon)
Traffic Source Analytics
- Referrer Analysis: See where your traffic comes from
- UTM Campaign Tracking: Full campaign parameter support
- Referrer Categories: Auto-categorized traffic sources (Search, Social, Direct, Email, Referral)
- Traffic Patterns: Hourly/daily heatmap visualization
Advanced Features
- IP Blocklist: Block IPs from tracking with visit attempt counter
- Data Import/Export: CSV import/export for backup and migration
- Dark Mode: Beautiful dark theme throughout the application
- Form Analytics: Track form interactions and conversions
- Custom Dashboards: Save and schedule reports (coming soon)
- API Keys: Programmatic access to your analytics data
- Team Collaboration: Multi-user support with annotations
Tech Stack
Backend
- Node.js with TypeScript
- Fastify - Fast and efficient web framework
- PostgreSQL with TimescaleDB - Time-series optimized database
- Redis - Caching and session management
- Zod - Runtime type validation
Frontend
- React with TypeScript
- Vite - Lightning-fast build tool
- TailwindCSS - Utility-first styling
- Recharts - Beautiful, composable charts
- React Query - Powerful data fetching
- Zustand - Simple state management
Infrastructure
- Docker & Docker Compose - Easy deployment
- Nginx - Static file serving and routing
Quick Start
Prerequisites
- Docker and Docker Compose
- Node.js 20+ (for local development)
Installation
-
Clone the repository
git clone <your-repo-url> cd stats -
Create environment file
cp .env.example .env -
Edit
.envwith secure valuesDB_PASSWORD=your_secure_password JWT_SECRET=your_jwt_secret_key API_URL=http://localhost:3000 -
Start with Docker Compose
docker-compose up -d -
Access the application
- Dashboard: http://localhost:5173
- API: http://localhost:3000
- Database: localhost:5432
Local Development
Backend
cd backend
npm install
npm run dev
Frontend
cd frontend
npm install
npm run dev
Adding Tracking to Your Website
After creating a website in the dashboard:
- Copy the tracking code from the website management page
- Add it to your website's
<head>section:
<script async defer data-website-id="YOUR_WEBSITE_ID" src="http://your-analytics-domain.com/tracker.js"></script>
Track Custom Events
// Track button clicks
document.querySelector('#signup-button').addEventListener('click', () => {
window.analytics.track('signup_click', {
plan: 'premium',
source: 'homepage'
});
});
// Track form submissions
window.analytics.track('newsletter_signup', {
email_category: 'weekly'
});
API Endpoints
Authentication
POST /api/auth/register- Create accountPOST /api/auth/login- LoginGET /api/auth/me- Get current user
Websites
GET /api/websites- List websitesPOST /api/websites- Create websiteGET /api/websites/:id- Get websitePUT /api/websites/:id- Update websiteDELETE /api/websites/:id- Delete website
Statistics
GET /api/stats/overview- Overview statisticsGET /api/stats/timeseries- Time-series dataGET /api/stats/pages- Top pagesGET /api/stats/referrers- Top referrersGET /api/stats/browsers- Browser breakdownGET /api/stats/os- Operating system breakdownGET /api/stats/devices- Device breakdownGET /api/stats/countries- Geographic breakdownGET /api/stats/realtime- Real-time active visitorsGET /api/stats/entry-pages- Entry (landing) pagesGET /api/stats/exit-pages- Exit pages with exit ratesGET /api/stats/retention- Return visitor metricsGET /api/stats/page-depth- Pages per session distributionGET /api/stats/traffic-patterns- Hourly/daily traffic heatmapGET /api/stats/campaigns- UTM campaign analyticsGET /api/stats/referrer-categories- Categorized referrer sources
Tracking
POST /api/track/pageview- Track pageviewPOST /api/track/event- Track custom eventPOST /api/track/scroll- Track scroll depthPOST /api/track/click- Track clicks for heatmap
IP Blocklist
GET /api/blocklist- List blocked IPsPOST /api/blocklist- Add IP to blocklistDELETE /api/blocklist/:id- Remove IP from blocklist
Import/Export
POST /api/import/umami- Import from UmamiPOST /api/import/analytics- Import from CSVGET /api/import/export/:websiteId- Export to CSV
Database Schema
The application uses PostgreSQL with TimescaleDB for efficient time-series data storage:
Core Tables
- users - User accounts and authentication
- websites - Tracked websites
- pageviews - Pageview events (hypertable)
- events - Custom events (hypertable)
- session_paths - Session flow tracking
Analytics Tables
- scroll_depth - Scroll tracking data
- click_heatmaps - Click position data
- form_analytics - Form interaction tracking
- error_404 - Broken link tracking
- search_queries - Site search tracking
Configuration Tables
- ip_blocklist - Blocked IPs with attempt counter
- api_keys - API access tokens
- teams - Team management
- team_members - Team member roles
- custom_dashboards - Saved dashboards
- saved_reports - Saved report configurations
- user_preferences - User settings and themes
- custom_branding - Custom logos and colors
Aggregates
- pageviews_hourly - Hourly aggregates (continuous aggregate)
- pageviews_daily - Daily aggregates (continuous aggregate)
Privacy Features
- No Cookies: Uses daily-rotated hashed visitor IDs
- IP Anonymization: IPs are hashed and never stored
- No Fingerprinting: Minimal browser data collection
- Country-Level Only: Geographic data limited to country
- Data Retention: Configurable retention policy (default: 2 years)
- GDPR Compliant: No personal data collection
Performance
- TimescaleDB: Optimized for time-series queries
- Continuous Aggregates: Pre-computed hourly/daily stats
- Redis Caching: Fast repeated queries
- Efficient Indexing: Optimized database indexes
- Compression: Automatic data compression for old data
Umami Migration
To import data from Umami:
- Export your Umami data
- Use the import API endpoint:
curl -X POST http://localhost:3000/api/import/umami \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"websiteId": 1, "umamiData": [...]}'
Production Deployment
Security Checklist
- Change default passwords in
.env - Use strong JWT secret (32+ characters)
- Enable HTTPS (use Let's Encrypt)
- Configure firewall (only ports 80, 443)
- Set up database backups
- Configure log rotation
- Enable rate limiting (already configured)
Recommended Setup
# docker-compose.prod.yml
version: '3.8'
services:
db:
restart: always
volumes:
- /var/lib/postgresql/data:/var/lib/postgresql/data
redis:
restart: always
backend:
restart: always
environment:
NODE_ENV: production
frontend:
restart: always
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx-prod.conf:/etc/nginx/nginx.conf
- /etc/letsencrypt:/etc/letsencrypt
Recent Updates (v2.0.0)
New Features
- ✅ Dark Mode - Full dark theme support
- ✅ IP Blocklist - Block IPs with visit attempt tracking
- ✅ CSV Import/Export - Backup and restore analytics data
- ✅ Entry/Exit Pages - Landing and exit page analytics
- ✅ Return Visitors - New vs returning visitor tracking
- ✅ Page Depth - Session page count distribution
- ✅ Traffic Patterns - Hourly/daily heatmap visualization
- ✅ UTM Campaigns - Full campaign tracking
- ✅ Referrer Categories - Auto-categorized traffic sources
- ✅ Collapsible Navigation - Organized sidebar with sections
- ✅ Scroll Tracking - Monitor scroll depth on pages
- ✅ Click Heatmaps - Track click positions
- ✅ Form Analytics - Form interaction tracking
- ✅ 404 Tracking - Broken link monitoring
- ✅ Team Collaboration - Multi-user support
Coming Soon
- Email reports
- Funnel analysis
- A/B testing support
- Goals and conversions
- API webhooks
- Rage click detection
- Dead click detection
- Reading progress tracking
- Core Web Vitals
- Page speed insights
- Mobile app
Contributing
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
MIT License - feel free to use this for any purpose.
Support
- GitHub Issues: Report bugs and feature requests
- Documentation: See
/docsfolder (coming soon)
Acknowledgments
Built with inspiration from:
- Umami Analytics
- Plausible Analytics
- Matomo (formerly Piwik)
Made with privacy in mind