femtostats

Femtostats is a lightweight, tiny, privacy-focused web statistics provider with no RDBMS requirement.

Why?

• Self-hostable
• Easy setup with a single <script> tag
• Simple pageview and session tracking
• Arbitrary client-side event tracking
• Realtime visitor count
• No external database requirement (uses SQLite)
• Not blocked by common ad blockers and browsers
• No storage of personally-identifable data (PII)
• Collection of client-side performance stats and screen width
• Geographic tracking with a free Maxmind account signup
• Optional cookieless operation to abide by privacy laws

Why not use ........?

What	Why not?
Google Analytics	Blocked by ad blockers and feeds your site's data into the Google data machine
CloudFlare Web Analytics	Blocked by ad blockers
Plausible	Self-hosting requires both additional Postgres and Clickhouse databases
Fathom Lite	The project is in maintenance-only mode and requires a Fathom account
Server logs	Doesn't record client information or sessions
CloudFront logs + S3 + Athena	Logs only get dumped once per day and querying requires writing raw SQL

Getting Started

1. Host the image ghcr.io/statico/femtostats wherever you want.
   • Check out the docker-compose.yml file in this repo as an example.
   • See below instructions on creating a Maxmind account to resolve geographic location at the country level.
   • Set a PASSWORD env var to protect your dashboard behind a password (the username is admin).
   • Set a DATA_DIR env var to store the SQLite database and Maxmind database. (Default is /tmp.)
2. Run pnpm knex:migrate to initialize the database.
3. Include the tag <script defer src="https://your-femtostats.com/data.js"></script> on the pages you want to track.
4. For custom event tracking, call window.femtostats('event name')

Enabling Country Resolution

To record which country the user has originated from, you need a geoip database. Femtostats will automatically download a free one from Maxmind and refresh it once a week if you do the following:

1. Go to https://www.maxmind.com/ and register for a free account
2. Under "Manage License Keys", get a license key
3. Under "Download Files", scroll to the "GeoLite2 Country" row and click "Get Permalinks". Get the database URL (it will look like https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=YOUR_LICENSE_KEY&suffix=tar.gz) and replace YOUR_LICENSE_KEY with your license key.
4. Set this URL as an environment variable MAXMIND_GEOLITE2_COUNTRY_URL

Disabling Cookies

By default, Femtostats stores a simple cookie on the client to count unique users and user sessions. You can disable the use of cookies entirely by adding data-cookies="false" to the <script> tag you embed on your site. Sessions will still show in the dashboard, but without cookies, the definition of a session changes from "a user's browser session" to "a single page view."

Other notes

The script tag instructions used to reference script.js, but uBlock appears to be blocking that.

Development

Requires Node.js 16+ and pnpm. Run pnpm and pnpm install.

The default database location is /tmp/stats.db. Run pnpm knex:seed to populate the database with some sample data.

This project uses Next.js, React, SWR, Recoil, Chakra UI, and Chart.js.

Future Ideas

• Use the better-sqlite3 driver
• Support other databases, maybe, I dunno
• Support UTM campaigns