Analytics Versions Save

The highlights of this release candidate are:

• Introduction of Community Edition [see below]
• TOTP for 2FA [docs]
• Sites page got a new look with spark charts
• The new WordPress integration now works better thanks to the Plugin API
• Hosting documentation (now at plausible/community-edition) also got an update and now includes a more thorough Google integration guide
• Even though not present in this release candidate, importing the data between self-hosted and cloud will be available in v2.1.0

Introduction of Community Edition

As of version 2.1.0 this project will split into Plausible Community Edition and Plausible Enterprise Edition. The Community Edition (CE) will remain completely open source under the AGPLv3 license. The Enterprise Edition (EE) will contain extra features that will be published as source-available on Github, but we do not grant rights for anyone else to use, distribute or otherwise exploit these features. Read more here.

As part of this change, we are also rebranding the project. The new logos for CE and EE will be different so as to clarify which version is being referred to or used at any given time.

And finally as a contributor, you will have to sign a Contributor License Agreement (CLA) in order for you PRs to be considered for merging.

Upgrading to v2.1.0-rc.0

⚠️ This guide assumes you are using v2.0.0 ⚠️

Update config

Add a secret key for the new required TOTP_VAULT_KEY environment variable

_console

$ openssl rand -base64 32
aihU7k+GSBKbcVFuX9VEPyUhuwlKEomqA94/SQQ0NR4=

_{plausible-conf.env}

  BASE_URL=https://plausible.example.com
  SECRET_KEY_BASE=PkVcxRgQDfQyhPETlog3vvCrj5LdYFSv4ejPEJHJO+i/37w6RZfRjeVCpJayjUjJMfXsNurcv5upPhTRoD3KgQ==
+ TOTP_VAULT_KEY=aihU7k+GSBKbcVFuX9VEPyUhuwlKEomqA94/SQQ0NR4=

This new key is used to encrypt TOTP secrets at rest.

Update images

Update the images used for plausible and plausible_events_db (thank you @lordcris https://github.com/plausible/analytics/discussions/3817#discussioncomment-8569053)

_{docker-compose.yml}

plausible:
- image: plausible/analytics:v2.0.0
+ image: ghcr.io/plausible/community-edition:v2.1.0-rc.0

plausible_events_db:
- image: clickhouse/clickhouse-server:22.6-alpine
+ image: clickhouse/clickhouse-server:23.3.7.5-alpine

and restart the containers

_console

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

This will boot up the new version of the app.

Changelog

Following changes have been made since v2.0.0:

Added

• IP Block List in Site Settings
• Allow filtering with contains/matches operator for Sources, Browsers and Operating Systems.
• Allow filtering by multiple custom properties
• Wildcard and member filtering on the Stats API event:goal property
• Allow filtering with contains/matches operator for custom properties
• Add referrers.csv to CSV export
• Add a new Properties section in the dashboard to break down by custom properties
• Add custom_props.csv to CSV export (almost the same as the old prop_breakdown.csv, but has different column headers, and includes props for pageviews too, not only custom events)
• Add referrers.csv to CSV export
• Improve password validation in registration and password reset forms
• Adds Gravatar profile image to navbar
• Enforce email reverification on update
• Add Plugins API Tokens provisioning UI
• Add searching sites by domain in /sites view
• Add last 24h plots to /sites view
• Add site pinning to /sites view
• Add support for JSON logger, via LOG_FORMAT=json environment variable
• Add support for 2FA authentication
• Add 'browser_versions.csv' to CSV export
• Add CLICKHOUSE_MAX_BUFFER_SIZE_BYTES env var which defaults to 100000 (100KB)

Removed

• Removed the nested custom event property breakdown UI when filtering by a goal in Goal Conversions
• Removed the prop_names returned in the Stats API event:goal breakdown response
• Removed the prop-breakdown.csv file from CSV export
• Deprecated CLICKHOUSE_MAX_BUFFER_SIZE

Changed

• Limit the number of Goal Conversions shown on the dashboard and render a "Details" link when there are more entries to show
• Show Outbound Links / File Downloads / 404 Pages / Cloaked Links instead of Goal Conversions when filtering by the corresponding goal
• Require custom properties to be explicitly added from Site Settings > Custom Properties in order for them to show up on the dashboard
• GA/SC sections moved to new settings: Integrations
• Replace CLICKHOUSE_MAX_BUFFER_SIZE with CLICKHOUSE_MAX_BUFFER_SIZE_BYTES

Fixed

• Stop returning custom events in goal breakdown with a pageview goal filter and vice versa
• Only return (none) values in custom property breakdown for the first page (pagination) of results
• Fixed weekly/monthly e-mail report rendering issues
• Fix broken interval selection in the all time view plausible/analytics#3110
• Fixed IPv6 problems in data migration plausible/analytics#3179
• Fixed long URLs display in Outbound Link breakdown view
• Fixed Sentry reports for ingestion requests plausible/analytics#3182
• Fix breakdown pagination bug in the dashboard details view when filtering by goals
• Update bot detection (matomo 6.1.4, ua_inspector 3.4.0)
• Improved the Goal Settings page (search, autcompletion etc.)
• Log mailer errors plausible/analytics#3336
• Allow custom event timeseries in stats API plausible/analytics#3505
• Fixes for sites with UTF characters in domain plausible/analytics#3560
• Fix crash when using special characters in filter plausible/analytics#3634

The highlights of this release are:

• more visitor metrics like total visits and views per visit
• period comparisons [docs] [example]
• ability to change domains names https://github.com/plausible/analytics/pull/2803
• automatic geolocation database downloads plausible/analytics#2362
• more email adapters support (Mailgun, Mandrill, SendGrid) plausible/analytics#2649

Upgrading Plausible Analytics to v2.0

⚠️ ⚠️ ⚠️

Upgrading to v2.0 requires performing a data migration. Please read these notes until the end before deploying v2.0.0

Ensure you are using a new ClickHouse version

The steps below have been tested with clickhouse/clickhouse-server:22.6-alpine please make sure to upgrade ClickHouse to at least this version.

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

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

Update image tag

In your docker-compose.yml update the image used for plausible to v2.0.0

plausible:
- image: plausible/analytics:v1.5.1
+ image: plausible/analytics:v2.0.0

and restart the container

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

This will boot up the new version of the app.

If you open the dashboards now, you wouldn't see any past metrics. This is expected as v2.0 uses the new events_v2 and sessions_v2 tables to store analytics data. We need to perform data migration to copy the data into the new tables.

Run data migration

⚠️ ⚠️ ⚠️

You need enough free disk space available for x2 of the current plausible_events_db's event-data volume size. You can use something like docker system df -v | grep hosting_event-data to check how much space the current volume is occupying.

Connect to the running plausible container and start the migration flow

$ cd hosting
$ docker compose exec plausible bin/plausible rpc Plausible.DataMigration.NumericIDs.run

You can attempt this migration multiple times unless you drop v1 tables.

Drop v1 tables (optional)

Once you verify the migration went well, the old tables can be dropped. It's easiest to use clickhouse-client for this

$ ch hosting
$ docker compose exec plausible_events_db clickhouse-client

:) \c plausible_events_db
:) show tables;
:) drop table events;
:) drop table sessions;

See https://clickhouse.com/docs/en/operations/server-configuration-parameters/settings#max-table-size-to-drop for how to drop tables with more than 50GB of data.

Enable automatic MaxMind GeoLite2 updates (optional)

In your plausible-config.env set MAXMIND_LICENSE_KEY environment variable and get an automatically updated GeoLite2 City geolocation database. The database edition is configurable with MAXMIND_EDITION environment variable and defaults to GeoLite2-City.

- IP_GEOLOCATION_DB=...
+ MAXMIND_LICENSE_KEY=LNpsJCCKPis6XvBP
+ MAXMIND_EDITION=GeoLite2-City

Note that for the changes in plausible-config.env to propagate to the plausible, the container needs to be recreated:

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

Also note that using GeoLite2-City edition requires more RAM than using GeoLite2-Country.

Now you can remove any other volumes and services used to download, store, and update geolocation databases.

Changelog

Following changes have been made since v1.5:

Added

• Add support for with_imported=true in Stats API aggregate endpoint
• Ability to use '--' instead of '=' sign in the tagged-events classnames
• 'Last updated X seconds ago' info to 'current visitors' tooltips
• Add support for more Bamboo adapters, i.e. Bamboo.MailgunAdapter, Bamboo.MandrillAdapter, Bamboo.SendGridAdapter plausible/analytics#2649
• Ability to change domain for existing site (requires numeric IDs data migration, instructions will be provided separately) UI + API (PUT /api/v1/sites)
• Add LOG_FAILED_LOGIN_ATTEMPTS environment variable to enable failed login attempts logs plausible/analytics#2936
• Add MAILER_NAME environment variable support plausible/analytics#2937
• Add MAILGUN_BASE_URI support for Bamboo.MailgunAdapter plausible/analytics#2935
• Add a landing page for self-hosters plausible/analytics#2989
• Allow optional IPv6 for clickhouse repo plausible/analytics#2970

Fixed

• Fix tracker bug - call callback function even when event is ignored
• Make goal-filtered CSV export return only unique_conversions timeseries in the 'visitors.csv' file
• Stop treating page filter as an entry page filter
• City report showing N/A instead of city names with imported data plausible/analytics#2675
• Empty values for Screen Size, OS and Browser are uniformly replaced with "(not set)"
• Fix more pageviews with session prop filter than with no filters
• Cascade delete sent_renewal_notifications table when user is deleted plausible/analytics#2549
• Show appropriate top-stat metric labels on the realtime dashboard when filtering by a goal
• Fix breakdown API pagination when using event metrics plausible/analytics#2562
• Automatically update all visible dashboard reports in the realtime view
• Connect via TLS when using HTTPS scheme in ClickHouse URL plausible/analytics#2570
• Add error message in case a transfer to an invited (but not joined) user is requested plausible/analytics#2651
• Fix bug with showing property breakdown with a prop filter
• Fix bug when combining goal and prop filters plausible/analytics#2654
• Fix broken favicons when domain includes a slash
• Fix bug when using multiple wildcard goal filters
• Fix a bug where realtime would fail with imported data
• Fix a bug where the country name was not shown when filtering through the map

Changed

• Treat page filter as entry page filter for bounce_rate
• Reject events with long URIs and data URIs plausible/analytics#2536
• Always show direct traffic in sources reports plausible/analytics#2531
• Stop recording XX and T1 country codes plausible/analytics#2556
• Device type is now determined from the User-Agent instead of window.innerWidth plausible/analytics#2711
• Add padding by default to embedded dashboards so that shadows are not cut off plausible/analytics#2744
• Update the User Agents database (https://github.com/matomo-org/device-detector/releases/tag/6.1.1)
• Disable registration in self-hosted setups by default plausible/analytics#3014

Removed

• Remove Firewall plug and IP_BLOCKLIST environment variable
• Remove the ability to collapse the main graph plausible/analytics#2627
• Remove custom_dimension_filter feature flag plausible/analytics#2996

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: https://github.com/plausible/docs/pull/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: https://github.com/plausible/analytics/issues/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: https://github.com/plausible/hosting/pull/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 plausible/analytics#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 plausible/analytics#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 plausible/analytics#1522
• New UTM Tags utm_content and utm_term plausible/analytics#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 plausible/analytics#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: plausible/analytics#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) plausible/analytics#1364
• New width=manual mode for embedded dashboards plausible/analytics#2148
• Add more timezone options
• Add new strategy to recommend timezone when creating a new site
• Alert outgrown enterprise users of their usage plausible/analytics#2197
• Manually lock and unlock enterprise users plausible/analytics#2197
• ARM64 support for docker images plausible/analytics#2103
• Add support for international domain names (IDNs) plausible/analytics#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 plausible/analytics#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

Security

• Add Content-Security-Policy header to favicon path

Deprecated

• DISABLE_AUTH is no longer supported

Release candidates

• v1.5.0-rc.0
• v1.5.0-rc.1

The highlights of this release are:

• more visitor metrics like total visits and views per visit
• period comparisons [docs] [example]
• ability to change domains names https://github.com/plausible/analytics/pull/2803
• automatic geolocation database downloads plausible/analytics#2362
• more email adapters support (Mailgun, Mandrill, SendGrid) plausible/analytics#2649

Upgrading Plausible Analytics to v2.0

⚠️ ⚠️ ⚠️

Upgrading to v2.0 requires performing a data migration. Please read these notes until the end before deploying v2.0.0-rc.2

Ensure you are using a new ClickHouse version

The steps below have been tested with clickhouse/clickhouse-server:22.6-alpine please make sure to upgrade ClickHouse to at least this version.

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

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

Update image tag

In your docker-compose.yml update the image used for plausible to v2.0.0-rc.2

plausible:
- image: plausible/analytics:v1.5.1
+ image: plausible/analytics:v2.0.0-rc.2

and restart the container

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

This will boot up the new version of the app.

If you open the dashboards now, you wouldn't see any past metrics. This is expected as v2.0 uses the new events_v2 and sessions_v2 tables to store analytics data. We need to perform data migration to copy the data into the new tables.

Run data migration

⚠️ ⚠️ ⚠️

You need enough free disk space available for x2 of the current plausible_events_db's event-data volume size. You can use something like docker system df -v | grep hosting_event-data to check how much space the current volume is occupying.

Connect to the running plausible container and start the migration flow

$ cd hosting
$ docker compose exec plausible bin/plausible rpc Plausible.DataMigration.NumericIDs.run

You can attempt this migration multiple times unless you drop v1 tables.

Drop v1 tables (optional)

Once you verify the migration went well, the old tables can be dropped. It's easiest to use clickhouse-client for this

$ ch hosting
$ docker compose exec plausible_events_db clickhouse-client

:) \c plausible_events_db
:) show tables;
:) drop table events;
:) drop table sessions;

See https://clickhouse.com/docs/en/operations/server-configuration-parameters/settings#max-table-size-to-drop for how to drop tables with more than 50GB of data.

Enable automatic MaxMind GeoLite2 updates (optional)

In your plausible-config.env set MAXMIND_LICENSE_KEY environment variable and get an automatically updated GeoLite2 City geolocation database. The database edition is configurable with MAXMIND_EDITION environment variable and defaults to GeoLite2-City.

- IP_GEOLOCATION_DB=...
+ MAXMIND_LICENSE_KEY=LNpsJCCKPis6XvBP
+ MAXMIND_EDITION=GeoLite2-City

Note that for the changes in plausible-config.env to propagate to the plausible, the container needs to be recreated:

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

Also note that using GeoLite2-City edition requires more RAM than using GeoLite2-Country.

Now you can remove any other volumes and services used to download, store, and update geolocation databases.

Changelog

Following changes have been made since v1.5:

Added

• Add support for with_imported=true in Stats API aggregate endpoint
• Ability to use '--' instead of '=' sign in the tagged-events classnames
• 'Last updated X seconds ago' info to 'current visitors' tooltips
• Add support for more Bamboo adapters, i.e. Bamboo.MailgunAdapter, Bamboo.MandrillAdapter, Bamboo.SendGridAdapter plausible/analytics#2649
• Ability to change domain for existing site (requires numeric IDs data migration, instructions will be provided separately) UI + API (PUT /api/v1/sites)
• Add LOG_FAILED_LOGIN_ATTEMPTS environment variable to enable failed login attempts logs plausible/analytics#2936
• Add MAILER_NAME environment variable support plausible/analytics#2937
• Add MAILGUN_BASE_URI support for Bamboo.MailgunAdapter plausible/analytics#2935
• Add a landing page for self-hosters plausible/analytics#2989

Fixed

• Fix tracker bug - call callback function even when event is ignored
• Make goal-filtered CSV export return only unique_conversions timeseries in the 'visitors.csv' file
• Stop treating page filter as an entry page filter
• City report showing N/A instead of city names with imported data plausible/analytics#2675
• Empty values for Screen Size, OS and Browser are uniformly replaced with "(not set)"
• Fix more pageviews with session prop filter than with no filters
• Cascade delete sent_renewal_notifications table when user is deleted plausible/analytics#2549
• Show appropriate top-stat metric labels on the realtime dashboard when filtering by a goal
• Fix breakdown API pagination when using event metrics plausible/analytics#2562
• Automatically update all visible dashboard reports in the realtime view
• Connect via TLS when using HTTPS scheme in ClickHouse URL plausible/analytics#2570
• Add error message in case a transfer to an invited (but not joined) user is requested plausible/analytics#2651
• Fix bug with showing property breakdown with a prop filter
• Fix bug when combining goal and prop filters plausible/analytics#2654
• Fix broken favicons when domain includes a slash

Changed

• Treat page filter as entry page filter for bounce_rate
• Reject events with long URIs and data URIs plausible/analytics#2536
• Always show direct traffic in sources reports plausible/analytics#2531
• Stop recording XX and T1 country codes plausible/analytics#2556
• Device type is now determined from the User-Agent instead of window.innerWidth plausible/analytics#2711
• Add padding by default to embedded dashboards so that shadows are not cut off plausible/analytics#2744
• Update the User Agents database (https://github.com/matomo-org/device-detector/releases/tag/6.1.1)

Removed

• Remove Firewall plug and IP_BLOCKLIST environment variable
• Remove the ability to collapse the main graph plausible/analytics#2627
• Remove custom_dimension_filter feature flag plausible/analytics#2996

The highlights of this release are:

• more visitor metrics like total visits and views per visit
• period comparisons [docs] [example]
• ability to change domains names https://github.com/plausible/analytics/pull/2803
• automatic geolocation database downloads plausible/analytics#2362
• more email adapters support (Mailgun, Mandrill, SendGrid) plausible/analytics#2649

Upgrading Plausible Analytics to v2.0

⚠️ ⚠️ ⚠️

Upgrading to v2.0 requires performing a data migration. Please read these notes until the end before deploying v2.0.0-rc.1

Ensure you are using a new ClickHouse version

The steps below have been tested with clickhouse/clickhouse-server:22.6-alpine please make sure to upgrade ClickHouse to at least this version.

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

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

Update image tag

In your docker-compose.yml update the image used for plausible to v2.0.0-rc.1

plausible:
- image: plausible/analytics:v1.5.1
+ image: plausible/analytics:v2.0.0-rc.1

and restart the container

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

This will boot up the new version of the app.

If you open the dashboards now, you wouldn't see any past metrics. This is expected as v2.0 uses the new events_v2 and sessions_v2 tables to store analytics data. We need to perform data migration to copy the data into the new tables.

Run data migration

⚠️ ⚠️ ⚠️

You need enough free disk space available for x2 of the current plausible_events_db's event-data volume size. You can use something like docker system df -v | grep hosting_event-data to check how much space the current volume is occupying.

Connect to the running plausible container and start the migration flow

$ cd hosting
$ docker compose exec plausible bin/plausible rpc Plausible.DataMigration.NumericIDs.run

You can attempt this migration multiple times unless you drop v1 tables.

Drop v1 tables (optional)

Once you verify the migration went well, the old tables can be dropped. It's easiest to use clickhouse-client for this

$ ch hosting
$ docker compose exec plausible_events_db clickhouse-client

:) \c plausible_events_db
:) show tables;
:) drop table events;
:) drop table sessions;

See https://clickhouse.com/docs/en/operations/server-configuration-parameters/settings#max-table-size-to-drop for how to drop tables with more than 50GB of data.

Enable automatic MaxMind GeoLite2 updates (optional)

In your plausible-config.env set MAXMIND_LICENSE_KEY environment variable and get an automatically updated GeoLite2 City geolocation database. The database edition is configurable with MAXMIND_EDITION environment variable and defaults to GeoLite2-City.

- IP_GEOLOCATION_DB=...
+ MAXMIND_LICENSE_KEY=LNpsJCCKPis6XvBP
+ MAXMIND_EDITION=GeoLite2-City

Note that for the changes in plausible-config.env to propagate to the plausible, the container needs to be recreated:

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

Also note that using GeoLite2-City edition requires more RAM than using GeoLite2-Country.

Now you can remove any other volumes and services used to download, store, and update geolocation databases.

Changelog

Following changes have been made since v1.5:

Added

• Add support for with_imported=true in Stats API aggregate endpoint
• Ability to use '--' instead of '=' sign in the tagged-events classnames
• 'Last updated X seconds ago' info to 'current visitors' tooltips
• Add support for more Bamboo adapters, i.e. Bamboo.MailgunAdapter, Bamboo.MandrillAdapter, Bamboo.SendGridAdapter plausible/analytics#2649
• Ability to change domain for existing site (requires numeric IDs data migration, instructions will be provided separately) UI + API (PUT /api/v1/sites)
• Add LOG_FAILED_LOGIN_ATTEMPTS environment variable to enable failed login attempts logs plausible/analytics#2936
• Add MAILER_NAME environment variable support plausible/analytics#2937
• Add MAILGUN_BASE_URI support for Bamboo.MailgunAdapter plausible/analytics#2935

Fixed

• Fix tracker bug - call callback function even when event is ignored
• Make goal-filtered CSV export return only unique_conversions timeseries in the 'visitors.csv' file
• Stop treating page filter as an entry page filter
• City report showing N/A instead of city names with imported data plausible/analytics#2675
• Empty values for Screen Size, OS and Browser are uniformly replaced with "(not set)"
• Fix more pageviews with session prop filter than with no filters
• Cascade delete sent_renewal_notifications table when user is deleted plausible/analytics#2549
• Show appropriate top-stat metric labels on the realtime dashboard when filtering by a goal
• Fix breakdown API pagination when using event metrics plausible/analytics#2562
• Automatically update all visible dashboard reports in the realtime view
• Connect via TLS when using HTTPS scheme in ClickHouse URL plausible/analytics#2570
• Add error message in case a transfer to an invited (but not joined) user is requested plausible/analytics#2651
• Fix bug with showing property breakdown with a prop filter
• Fix bug when combining goal and prop filters plausible/analytics#2654
• Fix broken favicons when domain includes a slash

Changed

• Treat page filter as entry page filter for bounce_rate
• Reject events with long URIs and data URIs plausible/analytics#2536
• Always show direct traffic in sources reports plausible/analytics#2531
• Stop recording XX and T1 country codes plausible/analytics#2556
• Device type is now determined from the User-Agent instead of window.innerWidth plausible/analytics#2711
• Add padding by default to embedded dashboards so that shadows are not cut off plausible/analytics#2744
• Update the User Agents database (https://github.com/matomo-org/device-detector/releases/tag/6.1.1)

Removed

• Remove Firewall plug and IP_BLOCKLIST environment variable
• Remove the ability to collapse the main graph plausible/analytics#2627

The highlights of this release are:

• period comparisons [docs] [example]
• ability to change domains names https://github.com/plausible/analytics/pull/2803
• automatic geolocation database downloads plausible/analytics#2362
• more email adapters support (Mailgun, Mandrill, SendGrid) plausible/analytics#2649

Upgrading Plausible Analytics to v2.0

⚠️ ⚠️ ⚠️

Upgrading to v2.0 requires performing a data migration. Please read these notes until the end before deploying v2.0.0-rc.0

Ensure you are using a new ClickHouse version

The steps below have been tested with clickhouse/clickhouse-server:22.6-alpine please make sure to upgrade ClickHouse to at least this version.

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

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

Update image tag

In your docker-compose.yml update the image used for plausible to v2.0.0-rc.0

plausible:
- image: plausible/analytics:v1.5.1
+ image: plausible/analytics:v2.0.0-rc.0

and restart the container

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

This will boot up the new version of the app.

If you open the dashboards now, you wouldn't see any past metrics. This is expected as v2.0 uses the new events_v2 and sessions_v2 tables to store analytics data. We need to perform data migration to copy the data into the new tables.

Run data migration

⚠️ ⚠️ ⚠️

You need enough free disk space available for x2 of the current plausible_events_db's event-data volume size. You can use something like docker system df -v | grep hosting_event-data to check how much space the current volume is occupying.

Connect to the running plausible container and start the migration flow

$ cd hosting
$ docker compose exec plausible bin/plausible rpc Plausible.DataMigration.NumericIDs.run

You can attempt this migration multiple times unless you drop v1 tables.

Drop v1 tables (optional)

Once you verify the migration went well, the old tables can be dropped. It's easiest to use clickhouse-client for this

$ ch hosting
$ docker compose exec plausible_events_db clickhouse-client

:) \c plausible_events_db
:) show tables;
:) drop table events;
:) drop table sessions;

See https://clickhouse.com/docs/en/operations/server-configuration-parameters/settings#max-table-size-to-drop for how to drop tables with more than 50GB of data.

Enable automatic MaxMind GeoLite2 updates (optional)

In your plausible-config.env set MAXMIND_LICENSE_KEY environment variable and get an automatically updated GeoLite2 City geolocation database. The database edition is configurable with MAXMIND_EDITION environment variable and defaults to GeoLite2-City.

- IP_GEOLOCATION_DB=...
+ MAXMIND_LICENSE_KEY=LNpsJCCKPis6XvBP
+ MAXMIND_EDITION=GeoLite2-City

Note that for the changes in plausible-config.env to propagate to the plausible, the container needs to be recreated:

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

Also note that using GeoLite2-City edition requires more RAM than using GeoLite2-Country.

Now you can remove any other volumes and services used to download, store, and update geolocation databases.

Changelog

Following changes have been made since v1.5:

Added

• Ability to use '--' instead of '=' sign in the tagged-events classnames
• 'Last updated X seconds ago' info to 'current visitors' tooltips
• Add support for more Bamboo adapters, i.e. Bamboo.MailgunAdapter, Bamboo.MandrillAdapter, Bamboo.SendGridAdapter plausible/analytics#2649
• Ability to change domain for existing site (requires numeric IDs data migration, instructions will be provided separately) UI + API (PUT /api/v1/sites)

Fixed

• Make goal-filtered CSV export return only unique_conversions timeseries in the 'visitors.csv' file
• Stop treating page filter as an entry page filter
• City report showing N/A instead of city names with imported data plausible/analytics#2675
• Empty values for Screen Size, OS and Browser are uniformly replaced with "(not set)"
• Fix more pageviews with session prop filter than with no filters
• Cascade delete sent_renewal_notifications table when user is deleted plausible/analytics#2549
• Show appropriate top-stat metric labels on the realtime dashboard when filtering by a goal
• Fix breakdown API pagination when using event metrics plausible/analytics#2562
• Automatically update all visible dashboard reports in the realtime view
• Connect via TLS when using HTTPS scheme in ClickHouse URL plausible/analytics#2570
• Add error message in case a transfer to an invited (but not joined) user is requested plausible/analytics#2651
• Fix bug with showing property breakdown with a prop filter
• Fix bug when combining goal and prop filters plausible/analytics#2654

Changed

• Treat page filter as entry page filter for bounce_rate
• Reject events with long URIs and data URIs plausible/analytics#2536
• Always show direct traffic in sources reports plausible/analytics#2531
• Stop recording XX and T1 country codes plausible/analytics#2556
• Device type is now determined from the User-Agent instead of window.innerWidth plausible/analytics#2711
• Add padding by default to embedded dashboards so that shadows are not cut off plausible/analytics#2744
• Update the User Agents database (https://github.com/matomo-org/device-detector/releases/tag/6.1.1)

Removed

• Remove Firewall plug and IP_BLOCKLIST environment variable
• Remove the ability to collapse the main graph plausible/analytics#2627

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.0 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.

For v1.5.0-rc.0 changes and upgrade steps please see the previous release candidate discussion.

Upgrading Plausible Analytics to v1.5.0-rc.1

In your docker-compose.yml update the image used for plausible to tag v1.5.0-rc.1:

plausible:
- image: plausible/analytics:1.5.0-rc.0
+ image: plausible/analytics:v1.5.0-rc.1

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.

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.0-rc.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.5.0-rc.0:

Added

• Allow self-hosters to register an account on first launch

Deprecated

• DISABLE_AUTH is no longer supported

The highlights of this release are:

• City and region level geolocation (disabled by default, please see this discussion for setup info)
• Google Analytics integration: https://plausible.io/docs/google-analytics-import (WIP setup guide: https://github.com/plausible/docs/pull/278)
• CSV data export: https://plausible.io/docs/export-stats
• ARM64 support

Upgrading Plausible Analytics to v1.5

In your docker-compose.yml update the image used for plausible to tag 1.5.0-rc.0:

plausible:
- image: plausible/analytics:v1.4
+ image: plausible/analytics:1.5.0-rc.0

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.

Upgrading ClickHouse to 22.6 (Optional, but recommended)

In your docker-compose.yml, update the image used for plausible_events_db to the newest stable 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: https://github.com/plausible/hosting/pull/45

Upgrading PostgreSQL to 14 (Optional, but recommended)

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

Changelog

Following changes have been made since v1.4:

Added

• 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 plausible/analytics#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 plausible/analytics#1522
• New UTM Tags utm_content and utm_term plausible/analytics#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 plausible/analytics#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: plausible/analytics#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) plausible/analytics#1364
• New width=manual mode for embedded dashboards plausible/analytics#2148
• Add more timezone options
• Add new strategy to recommend timezone when creating a new site
• Alert outgrown enterprise users of their usage plausible/analytics#2197
• Manually lock and unlock enterprise users plausible/analytics#2197
• ARM64 support for docker images plausible/analytics#2103
• Add support for international domain names (IDNs) plausible/analytics#2034

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

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 plausible/analytics#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

Security patch for password reset emails. Analysis of the issue and its impact: https://my-devbox.de/en/blog/accidental-pen-tester-evening/

Fixed

• Fix vulnerability with password reset emails

Fixed

• Make sure that ownership transfer can be made in self-hosted without creating a trial