v1.5.1

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`

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

<sub>Please make sure to **not** use `v1.5.0` release which had startup problems: https://github.com/plausible/analytics/issues/2491</sub>

#### 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`](https://github.com/plausible/location#cities) and [`geolite2-city.mmdb`](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data?lang=en) and setting `GEONAMES_SOURCE_FILE` and `IP_GEOLOCATION_DB` to point to them:

```console
$ # 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
```

```console
$ 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`
```diff
  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`
```diff
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:

```diff
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.](https://github.com/plausible/hosting/blob/master/upgrade/postgres.md)

### 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`:

```diff
- 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`](https://github.com/plausible/hosting/blob/a6fe8d13df3566f7bb3625a1a524f5498d56693d/docker-compose.yml#L31) command that was responsible for creating the admin user [is also deprecated.](https://github.com/plausible/analytics/blob/e522a2d7c182f5a0c7b2d95bf3ea248567a529e0/rel/overlays/init-admin.sh#L4-L5)

Please remove it from `docker-compose.yml`:

```diff
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](https://github.com/plausible/analytics/compare/v1.4.4...v1.5.1) 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](https://github.com/matomo-org/referrer-spam-list/blob/master/spammers.txt) 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](https://github.com/plausible/analytics/discussions/1968)
- 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](https://github.com/plausible/analytics/issues/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](https://github.com/plausible/analytics/issues/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](https://github.com/plausible/analytics/pull/2225)
- Restore compatibility with older format of shared links [plausible/analytics#2225](https://github.com/plausible/analytics/pull/2225)
- Fix 'All time' period for sites with no recorded stats [plausible/analytics#2277](https://github.com/plausible/analytics/pull/2277)
- Ensure settings page can be rendered after a form error [plausible/analytics#2278](https://github.com/plausible/analytics/pull/2278)
- Ensure newlines from settings files are trimmed [plausible/analytics#2480](https://github.com/plausible/analytics/pull/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](https://github.com/plausible/analytics#1934)
- Do not display ZZ country code in countries report [PR#1934](https://github.com/plausible/analytics#2223)
- Add fallback icon for when DDG favicon cannot be fetched [PR#2279](https://github.com/plausible/analytics#2279)

### Security
- Add Content-Security-Policy header to favicon path

### Deprecated
- `DISABLE_AUTH` is no longer supported

### Release candidates

- [`v1.5.0-rc.0`](https://github.com/plausible/analytics/discussions/2324)
- [`v1.5.0-rc.1`](https://github.com/plausible/analytics/discussions/2460)