Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alexfernandez/librecounter

Free and open website statistics
https://github.com/alexfernandez/librecounter

Last synced: about 9 hours ago
JSON representation

Free and open website statistics

Awesome Lists containing this project

README 

        
Logo for librecounter



# LibreCounter Stats



Free, libre and open website statistics.

GDPR compliant: no cookies, no tracking done in the browser,

no IP addresses stored, no marketing or advertising done (or even possible).



LibreCounter provides website traffic analysis and statistics for free at 

[librecounter.org](https://librecounter.org/).



## How to Use



Simply add the following snippet to your website,

in all pages that you want analyzed:



```html



Logo for librecounter/>
<br /></a>
<br />```</p>

<p>After that stats will be collected for every page view,
<br />and users clicking on the logo will be taken to
<br />[https://librecounter.org/[site]/show](https://librecounter.org/[site]/show)
<br />replacing `[site]` with your domain name.
<br />Stats will be public for all your visitors to see.</p>

<p>![Example stats using LibreCounter.](https://github.com/alexfernandez/librecounter/assets/876570/b32839b4-369a-4e86-801e-ce034f2920f1)</p>

<p>That is it! No configuration needed on the server at all.
<br />You can see an example on [the author's blog](https://pinchito.es/).</p>

<p>Technical details: the `referrerPolicy` is added to make sure that the browser sends the whole page URL to the server,
<br />otherwise sometimes it only sends the website (as `https://example.org/`)
<br />so LibreCounter cannot know which page the user is visiting.</p>

<p>Keep in mind that stats are still open for anyone that knows that you are using it,
<br />by following the link to https://librecounter.org/[example.org]/show.
<br />There is currently no way to make the stats private.
<br />If you want to hide stats for a sensitive domain
<br />(like an integration domain you don't want to show),
<br />please let [the author](https://github.com/alexfernandez/)
<br />know to add it to the hide list so that stats are not stored at all.</p>

<p>There are a host of visualiation options on the [official website](https://librecounter.org/options).</p>

<p>## API</p>

<p>The API allows you to count visits and to get stats.</p>

<p>### `/count`</p>

<p>If you want to count a visit but don't want to add an image,
<br />or just cannot,
<br />you can use the endpoint `/count`. For instance:</p>

<p>    https://librecounter.org/count?url=http://example.org/mypage&userAgent=roboto/1.0</p>

<p>Invoking this endpoint will count as a visit to the site `example.org`, page `/mypage`,
<br />with userAgent `roboto/1.0`.
<br />You can in fact use whatever programming language to invoke the endpoint,
<br />even a simple `wget` will do:</p>

<p>```shell
<br />wget https://librecounter.org/count?url=http://example.org/mypage&userAgent=roboto/1.0
<br />```</p>

<p>Be sure to URL-encode the URL and user agent parameters or they will be chopped up as part of the query string.</p>

<p>### `/[site]/siteStats`</p>

<p>Get stats for your site. Replace `[site]` with the domain for your site like `example.org`.
<br />For instance:</p>

<p>    https://librecounter.org/example.org/siteStats</p>

<p>Parameters:</p>

<p>* `days`: number of last days to get, default 30.</p>

<p>### `/[site]/pageStats`</p>

<p>Deprecated and removed in v2.0: this API call was broken.</p>

<p>## The Project</p>

<p>It's a simple project with less than 1000 lines of code on 2024-01-14.
<br />It uses the free IP database from Maxmind via
<br />[`geoip-lite`](https://npmjs.com/package/geoip-lite),
<br />and the awesome package [`node-device-detector`](https://www.npmjs.com/package/node-device-detector).
<br />No data is leaked outside as all lookups are done locally.</p>

<p>### Server Installation</p>

<p>To run your own instance simply download the repo and install all dependencies:</p>

<p>```shell
<br />git clone https://github.com/alexfernandez/librecounter
<br />npm install
<br />npm start
<br />```</p>

<p>That should do it!
<br />For no-hassle use please use the [official website](https://librecounter.org/).</p>

<p>### Server Configuration</p>

<p>You can create a file `.env` and add it at the root of the project,
<br />with the following variables in the usual [dotenv format](https://www.npmjs.com/package/dotenv):</p>

<p>* `BACKEND_SQLITE_DB`: path to SQLite database to use, default value: `local.db`.
<br />* `BACKEND_DOMAIN_HIDELIST`: comma-separated list of domains to hide:
<br />not store or show stats at all. Default value: empty string.</p>

<p>## Analytics, Counter or Tracking?</p>

<p>LibreCounter is a small step beyond the old website counters
<br />that kept track of how many people had visited to your website.
<br />It stores analytics for those visitors:
<br />by day, page, country of origin, browser and OS.</p>

<p>LibreCounter performs **no tracking**: it does not keep track of what visitors did on your site,
<br />just counts independent visits to each page.
<br />Personal information is not correlated between page visits.
<br />In particular, user agents and IP addresses and user agents are not stored at all.
<br />(But see [Tracking](doc/tracking.md) for more specific info.)</p>

<p>## Data Stored</p>

<p>In case you want to audit what data is stored per page view,
<br />all technical details are in
<br />[the class `Counter`](https://github.com/alexfernandez/librecounter/blob/main/lib/core/counter.js):</p>

<p>* day of the view (as 2023-10-06),
<br />* country of origin (as read from the IP address by [geoip-lite](https://www.npmjs.com/package/geoip-lite)),
<br />* site and page visited,
<br />* type of device (desktop, smartphone, tablet..),
<br />* browser used (Chrome, Firefox, Safari...),
<br />* operating system (Windows, GNU/Linux, Android...),
<br />* and platform (x64, x32, amd...).</p>

<p>That is it!
<br />The package [geoip-lite](https://www.npmjs.com/package/geoip-lite)
<br />is used for reading the country locally: no data leaves the server.
<br />For device identification the package
<br />[node-device-detector](https://www.npmjs.com/package/node-device-detector)
<br />is used, again locally so no data leaves the server.</p>

<p>## Help Wanted</p>

<p>If you want the package to support your favorite feature please open a merge request.</p>

<p>## Known Limitations</p>

<p>Some characters can be modified in pages when displayed:
<br />the small dollar sign `﹩` is replaced by the regular dollar sign `$`,
<br />and the leading dot `․` by the regular dot `.'.
<br />This was done originally to sidestep
<br />[limitations in MongoDB field names](https://stackoverflow.com/questions/12397118/mongodb-dot-in-key-name),
<br />and has not been changed yet.</p>

<p># Rationale</p>

<p>The idea of creating free and open stats came after the GDPR:
<br />it became quite obnoxious to add something like Google Analytics to your webpage,
<br />with the cookie warning.
<br />Also Google Analytics became more and more obnoxious itself,
<br />to the point where it looks like Google is not interested in having people use their free product.</p>

<p>Other tools are usually expensive,
<br />and still have in-browser tracking.
<br />Sadly neither [GitHub](https://github.com/orgs/community/discussions/31474)
<br />nor [Gitlab](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/189)
<br />provide server-side analytics.</p>

<p>LibreCounter does server-side analytics,
<br />no cookies, free software, open for everyone to use.</p>

<p>## ePrivacy Directive</p>

<p>The [ePrivacy directive](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX%3A32002L0058)
<br />of 2002 is even more strict than the GDPR.
<br />In article 6 it states that traffic data should be deleted or anonymized right away.
<br />LibreCounter does not store traffic data (user agent, IP address),
<br />just anonymized aggregates.</p>

<p>## Guarantees</p>

<p>The code is running on a private server using Linode (now Akamai).
<br />There are no guarantees of any kind:
<br />I intend to provide this service to the community as long as I am able to do it.
<br />However, if your use case requires it I may provide a full code audit to verify the running code.</p>

<p>Since you are just adding an external image you should not have any GDPR obligations,
<br />the operator of the private server does (i.e. myself).
<br />Always a good idea to consult with your lawyers if you want to be sure though.</p>

<p>You can bring up your own instance since the code is completely free.</p>

<p>## Eye of Horus</p>

<p>The logo is a play on the [eye of Horus](https://en.wikipedia.org/wiki/Eye_of_Horus),
<br />to give you special powers of observation
<br />and at the same time bring protection to your website against the GDPR.
<br />It also helps ward off from people trying to profit from your visitors.</p>

<p>## Copyright</p>

<p>(C) 2023-2024 [Alex Fernández](https://pinchito.es/) and [contributors](https://github.com/alexfernandez/librecounter/graphs/contributors).
<br />Visual identity contributed by [Fullcircle](https://fullcircle.es/).
<br />Licensed under the [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html),
<br />which in a nutshell means that you should make the code public if you distribute it.
<br />No need to do anything if you just run it on your own website.</p>

<p>