plausible/analytics v1.5.1 on GitHub

The highlights of this release are:

City and region level geolocation (disabled by default, please see below for the guide)
Google Analytics integration: https://plausible.io/docs/google-analytics-import (WIP setup guide: plausible/docs#278)
CSV data export: https://plausible.io/docs/export-stats
ARM64 support
Improved first launch experience

New first launch

Admin user registration is now done through the UI instead of configuration variables. At first launch, users are presented with a registration page which will create the admin account. Admin account related configuration variables are ignored going forward. See below for details.

Admin user registration is required from 1.5 onwards. We are deprecating the DISABLE_AUTH option which allowed Plausible to be used without any user account at all.

Users with existing admin accounts are not affected, but we recommend removing the unused configuration variables. A benefit of moving admin account management to the UI is that you can now change the admin email account through the UI. Previously, this was done by manual database changes and configuration change which required restarting the service.

Upgrading Plausible Analytics to v1.5

In your docker-compose.yml update the image used for plausible to v1.5.1

plausible:
- image: plausible/analytics:v1.4
+ image: plausible/analytics:v1.5.1

_{Please make sure to not use v1.5.0 release which had startup problems: #2491}

Restart the container

$ docker compose stop plausible
$ docker compose rm plausible
$ docker compose up -d

This will boot up the new version of the app.

City-level geolocation setup (Optional, requires more memory)

⚠️ Note that this city level geolocation feature requires extra ~1GB of RAM to work. If you don't have enough RAM available, you might experience slow container startups and restarts.

City level geolocation can be enabled by mounting a volume with the downloaded geonames.csv and geolite2-city.mmdb and setting GEONAMES_SOURCE_FILE and IP_GEOLOCATION_DB to point to them:

$ # custom (smaller) csv can be used, see https://github.com/plausible/location#cities for more info
$ curl -O https://s3.eu-central-1.wasabisys.com/plausible-application/geonames.csv

$ export MAXMIND_LICENSE_KEY=LNpsJCCKPis6XvBP # this key is not valid anymore
$ curl -L "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=${MAXMIND_LICENSE_KEY}&suffix=tar.gz" -o geolite2-city.mmdb.gz
$ gunzip geolite2-city.mmdb.gz

docker-compose.yml

  plausible:
    image: plausible/analytics:v1.5.1
+   volumes:
+     - ./geonames.csv:/etc/app/geonames.csv:ro
+     - ./geolite2-city.mmdb:/etc/app/geolite2-city.mmdb:ro

plausible-conf.env

BASE_URL=replace-me
SECRET_KEY_BASE=replace-me
+ GEONAMES_SOURCE_FILE=/etc/app/geonames.csv
+ IP_GEOLOCATION_DB=/etc/app/geolite2-city.mmdb

Upgrading ClickHouse to 22.6 (Optional, but recommended)

In your docker-compose.yml update the image used for plausible_events_db to a newer ClickHouse version:

plausible_events_db:
- image: yandex/clickhouse-server:21.3.2.5
+ image: clickhouse/clickhouse-server:22.6-alpine

Restart the container

$ docker compose stop plausible plausible_events_db
$ docker compose rm plausible_events_db
$ docker compose up -d

This will boot up the new version of ClickHouse.

Related PR: plausible/hosting#45

Upgrading PostgreSQL to 14 (Optional, but recommended)

Upgrading PostgreSQL is a bit trickier, here's the upgrade guide.

Removing deprecated commands and environment variables (Optional, but recommended)

ADMIN_USER_EMAIL, ADMIN_USER_NAME, ADMIN_USER_PWD, DISABLE_AUTH environment variables are no longer supported and are ignored if set.

Please remove them from plausible-conf.env:

- ADMIN_USER_EMAIL=replace-me
- ADMIN_USER_NAME=replace-me
- ADMIN_USER_PWD=replace-me
- DISABLE_AUTH=true
  BASE_URL=replace-me
  SECRET_KEY_BASE=replace-me

/entrypoint.sh db init-admin command that was responsible for creating the admin user is also deprecated.

Please remove it from docker-compose.yml:

plausible:
  image: plausible/analytics:v1.5.1
- command: sh -c "sleep 10 && /entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh db init-admin && /entrypoint.sh run"
+ command: sh -c "sleep 10 && /entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh run"

Changelog

Following changes have been made since v1.4:

Added

Set a different interval on the top graph #1574 (thanks to @Vigasaurus for this feature)
A tagged-events script extension for out-of-the-box custom event tracking
The ability to escape | characters with \ in Stats API filter values
An upper bound of 1000 to the limit parameter in Stats API
The exclusions script extension now also takes a data-include attribute tag
A file-downloads script extension for automatically tracking file downloads as custom events
Integration with Matomo's referrer spam list to block known spammers
API route PUT /api/v1/sites/goals with form params site_id, event_name and/or page_path, and goal_type with supported types event and page
API route DELETE /api/v1/sites/goals/:goal_id with form params site_id
The public breakdown endpoint can be queried with the "events" metric
Data exported via the download button will contain CSV data for all visible graps in a zip file.
Region and city-level geolocation #1449
The u option can now be used in the manual extension to specify a URL when triggering events.
Delete a site and all related data through the Sites API
Subscribed users can see their Paddle invoices from the last 12 months under the user settings
Allow custom styles to be passed to embedded iframe #1522
New UTM Tags utm_content and utm_term #515
If a session was started without a screen_size it is updated if an event with screen_size occurs
Added LISTEN_IP configuration parameter #1189
The breakdown endpoint with the property query property=event:goal returns custom goal properties (within props)
Added IPv6 Ecto support (via the environment-variable ECTO_IPV6)
New filter type: contains, available for page, entry_page, exit_page
Add filter for custom property
Add ability to import historical data from GA: #1753
API route GET /api/v1/sites/:site_id
Hovering on top of list items will now show a tooltip with the exact number instead of a shortened version
Filter goals in realtime filter by clicking goal name
The time format (12 hour or 24 hour) for graph timelines is now presented based on the browser's defined language
Choice of metric for main-graph both in UI and API (visitors, pageviews, bounce_rate, visit_duration) #1364
New width=manual mode for embedded dashboards #2148
Add more timezone options
Add new strategy to recommend timezone when creating a new site
Alert outgrown enterprise users of their usage #2197
Manually lock and unlock enterprise users #2197
ARM64 support for docker images #2103
Add support for international domain names (IDNs) #2034
Allow self-hosters to register an account on first launch
Fix ownership transfer invitation link in self-hosted deployments

Fixed

Plausible script does not prevent default if it's been prevented by an external script plausible/analytics#1941
Hash part of the URL can now be used when excluding pages with script.exclusions.hash.js.
UI fix where multi-line text in pills would not be underlined properly on small screens.
UI fix to align footer columns
Guests can now use the favicon to toggle additional info about the site bing viewed (such as in public embeds).
Fix SecurityError in tracking script when user has blocked all local storage
Prevent dashboard graph from being selected when long pressing on the graph in a mobile browser
The exported pages.csv file now includes pageviews again plausible/analytics#1878
Fix a bug where city, region and country filters were filtering stats but not the location list
Fix a bug where regions were not being saved
Timezone offset labels now update with time changes
Render 404 if shared link auth cannot be verified plausible/analytics#2225
Restore compatibility with older format of shared links plausible/analytics#2225
Fix 'All time' period for sites with no recorded stats plausible/analytics#2277
Ensure settings page can be rendered after a form error plausible/analytics#2278
Ensure newlines from settings files are trimmed plausible/analytics#2480

Changed

script.file-downloads.outbound-links.js only sends an outbound link event when an outbound download link is clicked
Plausible script now uses callback navigation (instead of waiting for 150ms every time) when sending custom events
Cache the tracking script for 24 hours
Move entry_page and exit_page to be part of the Page filter group
Paginate /api/sites results and add a View all link to the site-switcher dropdown in the dashboard.
Remove the + Add Site link to the site-switcher dropdown in the dashboard.
DISABLE_REGISTRATIONS configuration parameter can now accept invite_only to allow invited users to register an account while keeping regular registrations disabled #1841
New and improved Session tracking module for higher throughput and lower latency. PR#1934
Do not display ZZ country code in countries report PR#1934
Add fallback icon for when DDG favicon cannot be fetched PR#2279

plausible/analytics v1.5.1
on GitHub

New first launch

Upgrading Plausible Analytics to v1.5

Restart the container

City-level geolocation setup (Optional, requires more memory)

Upgrading ClickHouse to 22.6 (Optional, but recommended)

Restart the container

Upgrading PostgreSQL to 14 (Optional, but recommended)

Removing deprecated commands and environment variables (Optional, but recommended)

Changelog

Added

Fixed

Changed

Security

Deprecated

Release candidates