Documentation

Everything you need to install Mini Metrics on your own server, connect your websites and read your numbers. This guide covers version 1.1.0.

Requirements

  • PHP 7.4 or newer with the PDO SQLite extension (most hosts have it switched on)
  • Apache or Nginx, including ordinary shared hosting
  • HTTPS is recommended

You don't need a separate database server, Composer, Node or a build step. All data is kept in a single SQLite file, analytics.db.

Install

Mini Metrics works best on its own subdomain, such as analytics.example.com. It also works in a subfolder, such as example.com/analytics/.

  1. Upload the files

    Unzip the download and upload everything to the web root of your analytics site, for example /var/www/analytics.example.com/public_html/:

    public_html/
    assets/         styles and scripts for the dashboard
    CHANGELOG.md    release notes
    config.php      your settings
    favicon.png
    index.php       the dashboard
    README.md
    track.js        the tracking script for your websites
    track.php       receives the page views
  2. Set your password

    Open config.php and change the default password changeme; the dashboard won't let you log in until you do. You can change the username too.

    config.php
    define('DASHBOARD_USERNAME', 'admin');
    define('DASHBOARD_PASSWORD', 'a-long-unique-password');
  3. Make the data folder writable

    By default the database is created one folder above the web root, so nobody can download it. With the example above, that's /var/www/analytics.example.com/analytics.db. PHP must be able to write to that folder:

    Terminal
    chown www-data /var/www/analytics.example.com
    chmod 755 /var/www/analytics.example.com

    Replace www-data with the user PHP runs as on your server. On shared hosting the folder is usually writable already.

  4. Log in and add your domains

    Open your analytics site, e.g. https://analytics.example.com/, and log in. The first time, Mini Metrics asks which websites you want to track. Enter one domain per line, such as example.com. See Domains.

  5. Add the tracking script to your website

    The next section explains how. Then visit your website, open Recent activity at the bottom of the dashboard and check that your page view is there.

Add the tracking script

Put this line before the closing </head> tag on every page you want to count, using the address of your own Mini Metrics installation:

your-website.html
<script src="https://analytics.example.com/track.js" defer></script>

The exact line for your installation is under Setup guide in the dashboard header, with a Copy code button. For WordPress or other site builders, paste it into the theme's header or the "custom code in head" setting.

  • The script is about 5 KB. It sets no cookies and loads nothing else.
  • Single-page apps (React, Vue, Next.js and others) are tracked automatically when the URL changes.
  • Query strings and #fragments are ignored, and /about/ counts as /about.
  • Back and forward navigation counts too, and pages the browser preloads only count once someone opens them.
  • If Mini Metrics is unreachable, your website keeps working normally. Tracking fails silently.

Configure

All settings live in config.php. Upgrades never overwrite this file.

SettingDefaultWhat it does
DASHBOARD_USERNAMEadminUsername for the dashboard login.
DASHBOARD_PASSWORDchangemePassword for the dashboard login. Change it before you go live.
ALLOWED_DOMAINS[]Websites that may send page views. Usually managed from the dashboard (see Domains).
DB_PATHOne folder above the web rootWhere analytics.db is stored. Keep it outside the web root.
DATA_RETENTION_MONTHS18Page views older than this are deleted automatically.
TIMEZONEEurope/StockholmYour time zone, used for "today", the date filters, Recent activity and the CSV export. Use a PHP time zone name, such as America/New_York.

For example, to keep data for two years and use New York time:

config.php
define('DATA_RETENTION_MONTHS', 24);
define('TIMEZONE', 'America/New_York');

To store the database somewhere else, give the full path to the file and make sure PHP can write to its folder:

config.php
define('DB_PATH', '/home/me/data/analytics.db');

Domains

Mini Metrics only accepts page views from the domains you list. Other sites can't fill your statistics with fake visits.

  • Add a domain: in the dashboard, open Domains, enter the domain name without http:// or a path (for example shop.example.com) and click Add.
  • www is included: example.com also covers www.example.com.
  • Subdomains are separate: add blog.example.com on its own line if you track it.
  • Remove a domain: click Remove next to it. This also permanently deletes all page views recorded for that domain.

The dashboard saves the list to ALLOWED_DOMAINS in config.php, so PHP needs write access to that file. If it doesn't have write access, edit the list by hand:

config.php
define('ALLOWED_DOMAINS', [
    'example.com',
    'blog.example.com',
]);

An empty list ([]) accepts page views from any website. This is fine for testing but not recommended in production.

Use the dashboard

Want to see it before installing? Try the live demo.

What you're looking at

The header always shows the site and the period you're looking at. Above the numbers, one sentence spells it out, for example "All 3 sites combined, last 30 days (Oct 13 – Nov 11), compared with Sep 13 – Oct 12". With All sites, the numbers, chart and lists add up the data of all your domains; pick one domain in the site menu to see only that site. Active filters are listed right below as chips.

The numbers

  • Unique visitors: different visitors per day, counted without cookies (see Privacy). Someone who comes back on another day counts again.
  • Pageviews: every page that was loaded or opened in a single-page app.
  • Views per visitor: pageviews divided by unique visitors, so how many pages a visitor opens on average.
  • Pageviews today: since midnight in your time zone, for the selected site and filters, whatever period you picked.

The first three always cover the period you picked and show the change against the previous period of the same length, for example "↑ 12% vs previous 30 days". The chart shows page views per day, including days without visits, with the previous period as a dashed grey line. Hover over the chart to compare two days side by side.

Site, period and filters

  • Site: the menu next to the logo. Choose one of your domains or All sites. Switching sites keeps your period and filters.
  • Period: click the period button next to it for Today, Yesterday, Last 7 days, Last 30 days, This month, Last month, Last 12 months or a custom date range. Without a period, the dashboard shows the last 30 days.
  • Filters: click Add filter above the numbers, or search in the period panel, for a page, country, city or referrer. You can also click any row in the Pages, Countries, Cities or Referrers lists to show only that one.

Each filter shows as a chip above the numbers: click it to remove it, or click Clear filters. When no filter is active, the dashboard says so. Every view has its own URL, so you can bookmark it.

Top lists

Each list shows the top 10 with their views and their share of all page views in the current view.

  • Pages: the most viewed paths. With All sites and more than one domain, each page shows its domain, so the home pages of different sites aren't mixed up.
  • Referrers: other websites that sent visitors to you. Links between your own pages aren't counted.
  • Countries and cities: based on the visitor's IP address (see Privacy).

When a list is empty because of your period or filters, it says so, so you can tell it apart from a setup problem.

Recent activity

The latest 20 page views for the current site, period and filters, with their time, page (and site, with All sites) and location. Use it to check that tracking works.

Export to CSV

In the period panel, Download CSV exports the page views for the current site, period and filters, with date, time, site, page, referrer, country, city and region. The file opens in Excel, Numbers and Google Sheets.

Privacy and what's counted

  • No cookies. Mini Metrics doesn't store anything in your visitors' browsers, so it doesn't need a cookie banner.
  • No raw IP addresses. Each IP address is hashed together with the date before it's saved. A visitor counts once per day and can't be followed across days.
  • Location: the country and city are looked up once per IP address with the free GeoJS service (get.geojs.io). The result is cached in your database for 7 days. Private network addresses are never looked up.
  • Bots aren't counted: search engine crawlers, uptime monitors, link previews and scripts are ignored.
  • Your data stays on your server. We never see it.

Upgrade

When a new version is out, you get an email with a download link. To upgrade:

  1. Back up

    Copy analytics.db and your config.php somewhere safe.

  2. Replace the files

    Upload all files from the new zip except config.php, and replace the whole assets/ folder. Keep your own config.php. New settings always have safe defaults, so you never have to edit it to upgrade.

  3. Open the dashboard

    Database changes are applied automatically. The version number is shown in the dashboard footer. The changelog (also CHANGELOG.md in the zip) lists what changed and any notes for that release.

Troubleshooting

The Get help link in the dashboard footer brings you to this page.

No page views show up

Check that the domain is listed under Domains exactly as your website is named. Open your website, press F12 and check the Network tab for track.php (it may be listed as type "ping" or "beacon"). A 403 response means the domain isn't on the list. If the request is missing, an ad blocker or the script URL may be the cause. Your own visit only counts if your browser isn't identified as a bot.

"Database directory not writable" or a blank dashboard

PHP can't create analytics.db. Make the folder above your web root (or the folder in DB_PATH) writable for the PHP user, and check that the PDO SQLite extension is enabled. You can check with php -m | grep -i sqlite.

"Too many failed attempts"

After 5 wrong passwords, logins from that IP address are blocked for 15 minutes. Each further 5 wrong passwords block it longer: 1 hour, 4 hours, up to 24 hours. Wait, then try again. If you forgot the password, set a new one in config.php; changing the password also lifts every block right away.

Blocked although you typed the right password? Your dashboard probably runs behind a reverse proxy or load balancer, so every login seems to come from the proxy's address and shares one limit. Let your web server pass the real visitor IP (Apache mod_remoteip, Nginx real_ip). Cloudflare's header is recognised automatically.

"The login form expired"

The login page was open for more than an hour, or your browser didn't keep the session cookie. Reload the page and log in again. On plain HTTP, check that cookies aren't blocked.

"Set your own DASHBOARD_PASSWORD in config.php first"

Mini Metrics refuses the default password changeme and an empty password. Set your own in config.php (see Install).

Block password guessers with fail2ban

Every failed login is written to PHP's error log as Mini Metrics: failed login from 203.0.113.7. To block those addresses at the firewall, point a fail2ban filter at that log with failregex = Mini Metrics: failed login from <HOST>.

Adding a domain doesn't work

The dashboard couldn't write to config.php. Make the file writable for PHP, or add the domain to ALLOWED_DOMAINS by hand.

Times or "today" look off by a few hours

Set TIMEZONE in config.php to your own time zone.

Countries or cities are empty

Your server must be able to make outgoing HTTPS requests to get.geojs.io, using the PHP curl extension or allow_url_fopen. If it can't, page views are still counted, just without a location. Behind a proxy or Cloudflare, make sure the real visitor IP is passed on (Mini Metrics reads CF-Connecting-IP and X-Forwarded-For).

See what the tracker receives

Set $DEBUG = true; at the top of track.php and check your PHP error log. To log from the browser, set var DEBUG = true; in track.js and open the console. Switch both back off afterwards.

Still stuck? Email [email protected] and we'll help you out.