-
-
+ Open-source, self-hosted web analytics. Your data. Your server. No Google. +
-- [Simple, fast routing engine](https://laravel.com/docs/routing). -- [Powerful dependency injection container](https://laravel.com/docs/container). -- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage. -- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent). -- Database agnostic [schema migrations](https://laravel.com/docs/migrations). -- [Robust background job processing](https://laravel.com/docs/queues). -- [Real-time event broadcasting](https://laravel.com/docs/broadcasting). +
+ 
+ Features • + Quick Start • + Installation • + Tracking Setup • + API • + Contributing +
-## Learning Laravel +--- -Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out [Laravel Learn](https://laravel.com/learn), where you will be guided through building a modern Laravel application. +## What is LibreMetrics? -If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library. +LibreMetrics is a full-featured, self-hosted web analytics platform built with Laravel 11. It gives you the depth of Google Analytics without handing your visitors' data to a third party — and without the per-pageview pricing of SaaS alternatives like Plausible or Fathom. -## Laravel Sponsors +Install it on a $5 VPS, point your tracking snippet at it, and get real-time dashboards, goal tracking, funnels, segments, custom alerts, and a REST API — all on infrastructure you own and control. -We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com). +**Why self-host?** +- 🔒 **Privacy by design** — visitor data never leaves your server, GDPR-compliant out of the box +- 💰 **One price: $0** — unlimited websites, unlimited pageviews, no per-seat fees +- 🔧 **Full control** — extend it, customize it, integrate it with anything +- 🚫 **No cookie banners needed** — no cross-site tracking, no third-party scripts -### Premium Partners +--- -- **[Vehikl](https://vehikl.com)** -- **[Tighten Co.](https://tighten.co)** -- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)** -- **[64 Robots](https://64robots.com)** -- **[Curotec](https://www.curotec.com/services/technologies/laravel)** -- **[DevSquad](https://devsquad.com/hire-laravel-developers)** -- **[Redberry](https://redberry.international/laravel-development)** -- **[Active Logic](https://activelogic.com)** +## ✨ Features -## Contributing +### Core Analytics +- **Real-time dashboard** — see active visitors right now with a live counter +- **Key metrics** — page views, unique visitors, sessions, bounce rate, avg. session duration, pages/session +- **Comparison mode** — compare any period vs the previous one, with delta percentages on every card +- **Visitors & page views chart** — daily or hourly granularity, with sessions overlay -Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions). +### Audience Reports +- 🌍 **Geographic** — visitors by country, region, and city with a world map visualization +- 💻 **Technology** — browser, OS, device type, screen resolution breakdown +- 🌐 **Language** — browser language distribution +- 🔄 **New vs. Returning** — segment first-time vs. repeat visitors -## Code of Conduct +### Acquisition Reports +- **Traffic sources** — direct, organic, referral, and social split +- **Campaigns (UTM)** — group sessions by `utm_source`, `utm_medium`, `utm_campaign` +- **Referrers** — top referring domains and full URLs -In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct). +### Behavior Reports +- **Top pages** — views, unique views, avg. time on page, bounce rate per path +- **Landing pages** — entry pages with session count and bounce rate +- **Exit pages** — where visitors are leaving -## Security Vulnerabilities +### Events & Goals +- **Custom event tracking** — fire events from your frontend with category, label, and value +- **Events report** — grouped by name/category, with drill-down and trending chart +- **4 goal types:** + - URL destination (exact, starts-with, contains, regex) + - Event match (name + optional category) + - Session duration (> N seconds) + - Pages per session (≥ N pages) +- **Conversions report** — completion count, conversion rate, goal value totals, sparklines on dashboard -If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed. +### Advanced Features +- **Funnels** — define multi-step sequences and visualize drop-off at each step +- **Segments** — filter any report by visitor attributes (device, country, browser, etc.) +- **Custom dashboards** — pin widgets to a personal overview page +- **Alerts** — get notified by email when traffic spikes, drops, or a goal hits a threshold +- **Annotations** — add notes to specific dates that appear on charts +- **Data export** — export any report to CSV +- **UTM builder** — generate campaign URLs with UTM parameters right in the app -## License +### Developer Features +- **REST API** — pull any metric programmatically with token authentication +- **API token management** — create and revoke tokens from the dashboard +- **Async ingestion pipeline** — collection endpoint returns instantly; processing is queued +- **Bot filtering** — known crawlers are silently rejected +- **1×1 tracking pixel** — no-JavaScript fallback for email or restricted environments +- **Ad-blocker resistant endpoints** — alternate `/cdn/` paths for the tracker script and collection -The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). +### Performance & Scale +- **Daily aggregation** — raw data is pre-aggregated nightly for fast dashboard queries +- **Hybrid query strategy** — aggregates for history, raw tables for today's live data +- **Configurable data retention** — set per-website retention from 30 days to forever +- **Purge command** — automatically clean up raw data beyond the retention window +- **Performance indexes** — all date-range + website_id query paths are indexed + +--- + +## 🚀 Quick Start + +The fastest path to a running instance: + +```bash +git clone https://github.com/yourusername/libremetrics.git +cd libremetrics +composer install +cp .env.example .env +php artisan key:generate +php artisan migrate +npm install && npm run build +composer run dev +``` + +Open `http://localhost:8000`, register an account, add your first website, and copy the tracking snippet. Done. + +> **`composer run dev`** starts four processes in parallel: web server, queue worker, log viewer, and Vite dev server. + +--- + +## 📦 Installation + +### Requirements + +| Requirement | Version | +|---|---| +| PHP | 8.2+ | +| Composer | 2.x | +| Node.js | 18+ | +| Database | SQLite (dev) / MySQL 8+ / PostgreSQL 14+ | +| Queue | Database (dev) / Redis (production) | + +### Step-by-step + +**1. Clone and install dependencies** + +```bash +git clone https://github.com/yourusername/libremetrics.git libremetrics +cd libremetrics +composer install +npm install +``` + +**2. Configure environment** + +```bash +cp .env.example .env +php artisan key:generate +``` + +Edit `.env` for your environment. Minimum required changes: + +```env +APP_URL=https://analytics.yourdomain.com + +# Database (SQLite works great for small installs) +DB_CONNECTION=sqlite + +# Or for MySQL/PostgreSQL: +# DB_CONNECTION=mysql +# DB_HOST=127.0.0.1 +# DB_DATABASE=libremetrics +# DB_USERNAME=your_user +# DB_PASSWORD=your_password + +# Mail (for alerts and email verification) +MAIL_MAILER=smtp +MAIL_HOST=your-smtp-host +MAIL_PORT=587 +MAIL_USERNAME=your@email.com +MAIL_PASSWORD=your-password +MAIL_FROM_ADDRESS=analytics@yourdomain.com +``` + +**3. Run migrations and build assets** + +```bash +php artisan migrate +npm run build +``` + +**4. Start the application** + +```bash +# Development (all-in-one): +composer run dev + +# Production — use a process supervisor for these: +php artisan serve # or configure Nginx + PHP-FPM +php artisan queue:work database --tries=3 # REQUIRED: processes tracking events +php artisan schedule:work # REQUIRED: aggregation, purge, alerts +``` + +> ⚠️ The queue worker and scheduler are **critical**. Without the queue worker, tracking events are dropped. Without the scheduler, reports slow down over time and alerts never fire. + +--- + +### Production Setup (Nginx + PHP-FPM) + +Point your Nginx document root to the `public/` directory: + +```nginx +server { + listen 443 ssl http2; + server_name analytics.yourdomain.com; + root /var/www/libremetrics/public; + + index index.php; + + location / { + try_files $uri $uri/ /index.php?$query_string; + } + + location ~ \.php$ { + fastcgi_pass unix:/var/run/php/php8.2-fpm.sock; + fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; + include fastcgi_params; + } +} +``` + +**Supervisor config for the queue worker:** + +```ini +[program:libremetrics-queue] +command=php /var/www/libremetrics/artisan queue:work database --tries=3 --timeout=60 +autostart=true +autorestart=true +user=www-data +numprocs=2 +redirect_stderr=true +stdout_logfile=/var/www/libremetrics/storage/logs/queue.log +``` + +**Cron entry for the scheduler:** + +```cron +* * * * * cd /var/www/libremetrics && php artisan schedule:run >> /dev/null 2>&1 +``` + +--- + +## 🎯 Tracking Setup + +### 1. Add a website + +Register, go to **Websites → Add Website**, enter your site's name and domain. You'll get a tracking ID like `TA-XXXXXXXXXX`. + +### 2. Install the snippet + +Paste this into your HTML before ``: + +```html + +``` + +That's it. Page views, sessions, and visitor data start flowing immediately. + +### 3. Track custom events + +```javascript +// Track a button click +ta('event', 'signup_click', { + category: 'engagement', + label: 'hero_cta', + value: 1 +}); + +// Track a purchase +ta('event', 'purchase', { + category: 'ecommerce', + label: 'checkout', + value: 49.99 +}); +``` + +### 4. Single-page application support + +The tracker automatically detects route changes via `history.pushState` and `popstate`. For manual control: + +```javascript +ta('pageview'); // manually fire a page view +``` + +### 5. No-JS fallback (tracking pixel) + +```html ++ Made with ❤️ — if LibreMetrics saves you money or headaches, consider giving it a ⭐ +