Create LICENSE

allow ws proxying in nginx

.prettierignore

@@ -0,0 +1 @@
+*

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Plausible Analytics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -7,7 +7,7 @@
 </p>
 
 <p align="center">
-    <strong>A getting started guide to self-hosting Plausible Community Edition</strong>
+    <strong>A getting started guide to self-hosting <a href="https://plausible.io/blog/community-edition">Plausible Community Edition</a></strong>
 </p>
 
 <!-- TODO latest version, current version, requirements -->
@@ -15,7 +15,6 @@
 **Contact**:
 
 - For release announcements please go to [GitHub releases.](https://github.com/plausible/analytics/releases)
-
 - For a question or advice please go to [GitHub discussions.](https://github.com/plausible/analytics/discussions/categories/self-hosted-support)
 
 ---
@@ -32,7 +31,7 @@
 
 ## Install
 
-Plausible Community Edition (or CE for short) is designed to be self-hosted through Docker. You don't have to be a Docker expert to launch your own instance, but you should have a basic understanding of the command-line and networking to successfully set it up.
+[Plausible Community Edition (or CE for short)](https://plausible.io/blog/community-edition) is designed to be self-hosted through [Docker.](https://docs.docker.com/guides/get-started/) You don't have to be a Docker expert to launch your own instance, but you should have a basic understanding of the command-line and networking to successfully set it up.
 
 ### Requirements
 
@@ -48,9 +47,7 @@ To get started quickly, clone the [plausible/community-edition](https://github.c
 
 <sub><kbd>console</kbd></sub>
 ```console
-$ mkdir hosting
+$ git clone https://github.com/plausible/community-edition hosting
-$ cd hosting
-$ git clone https://github.com/plausible/community-edition .
 Cloning into 'community-edition'...
 remote: Enumerating objects: 280, done.
 remote: Counting objects: 100% (146/146), done.
@@ -58,18 +55,18 @@ remote: Compressing objects: 100% (74/74), done.
 remote: Total 280 (delta 106), reused 86 (delta 71), pack-reused 134
 Receiving objects: 100% (280/280), 69.44 KiB | 7.71 MiB/s, done.
 Resolving deltas: 100% (136/136), done.
-$ ls
+$ ls hosting
 README.md           clickhouse/         docker-compose.yml  images/             plausible-conf.env  reverse-proxy/      upgrade/
 ```
 
 In the downloaded directory you'll find two important files:
 
-- [`docker-compose.yml`](https://github.com/plausible/community-edition/blob/master/docker-compose.yml) - installs and orchestrates networking between your Plausible CE server, Postgres database, Clickhouse database (for stats), and an SMTP server.
+- [docker-compose.yml](./docker-compose.yml) — installs and orchestrates networking between your Plausible CE server, Postgres database, and Clickhouse database for stats.
-- [`plausible-conf.env`](https://github.com/plausible/community-edition/blob/master/plausible-conf.env) - configures the Plausible server itself. Full configuration options are documented [below.](#configure)
+- [plausible-conf.env](./plausible-conf.env) — configures the Plausible server itself. Full configuration options are documented [below.](#configure)
 
 Right now the latter looks like this:
 
-<sub><kbd>[plausible-conf.env](https://github.com/plausible/community-edition/blob/master/plausible-conf.env)</kbd></sub>
+<sub><kbd>[plausible-conf.env](./plausible-conf.env)</kbd></sub>
 ```env
 BASE_URL=replace-me
 SECRET_KEY_BASE=replace-me
@@ -78,7 +75,9 @@ TOTP_VAULT_KEY=replace-me
 
 Let's do as it asks and populate these required environment variables with our own values.
 
-First we generate the secrets for [`SECRET_KEY_BASE`](#secret_key_base) and [`TOTP_VAULT_KEY`](#totp_vault_key) using `openssl`
+#### Required configuration
+
+First we generate the [secret key base](#secret_key_base) and [TOTP vault key](#totp_vault_key) using OpenSSL:
 
 <sub><kbd>console</kbd></sub>
 ```console
@@ -88,9 +87,7 @@ $ openssl rand -base64 32
 dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I=
 ```
 
-> ⚠️ [`SECRET_KEY_BASE`](#secret_key_base) needs to be Base64 encoded 32 (or more) bytes and [`TOTP_VAULT_KEY`](#totp_vault_key) needs to be Base64 encoded 32 bytes.
+And then we decide on the [base URL](#base_url) where the instance would be accessible:
-
-And then we decide on the [`BASE_URL`](#base_url) where the instance would be accessible. Let's assume we choose `http://plausible.example.com`
 
 <sub><kbd>plausible-conf.env</kbd></sub>
 ```diff
@@ -104,15 +101,35 @@ And then we decide on the [`BASE_URL`](#base_url) where the instance would be ac
 
 We can start our instance now but the requests would be served over HTTP. Not cool! Let's configure [Caddy](https://caddyserver.com) to enable HTTPS.
 
-<!-- TODO note about CloudFlare -->
+#### Caddy
 
-> For other reverse-proxy setups please see [reverse-proxy](https://github.com/plausible/community-edition/tree/master/reverse-proxy) docs.
+> [!TIP]
+> For other reverse-proxy setups please see [reverse-proxy](./reverse-proxy) docs.
 
-First we need to point DNS records for `plausible.example.com` to the IP address of the instance. This is needed for Caddy to issue the TLS certificates.
+<details>
+<summary>Don't need reverse proxy?</summary>
+
+---
+
+If you're **opting out** of a reverse proxy and HTTPS, you'll need to adjust the Plausible service [configuration](./docker-compose.yml#L38) to ensure it's not limited to localhost (127.0.0.1). This change allows the service to be accessible from any network interface:
+
+<sub><kbd>[docker-compose.yml](./docker-compose.yml#L38)</kbd></sub>
+```diff
+plausible:
+  ports:
+-   - 127.0.0.1:8000:8000
++   - 8000:8000
+```
+
+---
+
+</details>
+
+First we need to point DNS records for our base URL to the IP address of the instance. This is needed for Caddy to issue the TLS certificates.
 
 Then we need to let Caddy know the domain name for which to issue the TLS certificate and the service to redirect the requests to.
 
-<sub><kbd>[reverse-proxy/docker-compose.caddy-gen.yml](https://github.com/plausible/community-edition/blob/master/reverse-proxy/docker-compose.caddy-gen.yml)</kbd></sub>
+<sub><kbd>[reverse-proxy/docker-compose.caddy-gen.yml](./reverse-proxy/docker-compose.caddy-gen.yml)</kbd></sub>
 ```diff
   plausible:
     labels:
@@ -123,7 +140,7 @@ Then we need to let Caddy know the domain name for which to issue the TLS certif
 +     virtual.tls-email: "admin@plausible.example.com"
 ```
 
-Finally we need to update `BASE_URL` to use `https://` scheme.
+Finally we need to update the base URL to use HTTPS scheme.
 
 <sub><kbd>plausible-conf.env</kbd></sub>
 ```diff
@@ -135,6 +152,8 @@ Finally we need to update `BASE_URL` to use `https://` scheme.
 
 Now we can start everything together.
 
+#### Launch
+
 <sub><kbd>console</kbd></sub>
 ```console
 $ docker compose -f docker-compose.yml -f reverse-proxy/docker-compose.caddy-gen.yml up -d
@@ -151,11 +170,12 @@ $ docker compose -f docker-compose.yml -f reverse-proxy/docker-compose.caddy-gen
  ✔ Container caddy-gen                      Started
 ```
 
-It takes some time to start PostgreSQL and ClickHouse, create the databases, and run the migrations. After about fifteen seconds you should be able to access your instance at `BASE_URL` and see the registration screen for the admin user.
+It takes some time to start PostgreSQL and ClickHouse, create the databases, and run the migrations. After about fifteen seconds you should be able to access your instance at the base URL and see the registration screen for the admin user.
 
-In case something feels off, make sure to check out the logs with <kbd>docker compose logs</kbd> and start a [GitHub discussion.](https://github.com/plausible/analytics/discussions/categories/self-hosted-support)
+> [!TIP]
+> If something feels off, make sure to check out the logs with <kbd>docker compose logs</kbd> and start a [GitHub discussion.](https://github.com/plausible/analytics/discussions/categories/self-hosted-support)
 
-Happy hosting!
+🎉 Happy hosting! 🚀
 
 Next we'll go over how to upgrade the instance when a new release comes out, more things to configure, and how to integrate with Google and others!
 
@@ -169,8 +189,8 @@ Plausible CE follows [semantic versioning:](https://semver.org/) `MAJOR.MINOR.PA
 
 You can find available Plausible versions on [Github packages.](https://github.com/plausible/analytics/pkgs/container/community-edition) The default `latest` tag refers to the latest stable release tag. You can also pin your version:
 
-- `ghcr.io/plausible/community-edition:v2` pins the major version to `2` but allows minor and patch version upgrades
+- <kbd>ghcr.io/plausible/community-edition:v2</kbd> pins the major version to `2` but allows minor and patch version upgrades
-- `ghcr.io/plausible/community-edition:v2.1` pins the minor version to `2.1` but allows only patch upgrades
+- <kbd>ghcr.io/plausible/community-edition:v2.1</kbd> pins the minor version to `2.1` but allows only patch upgrades
 
 None of the functionality is backported to older versions. If you wish to get the latest bug fixes and security updates you need to upgrade to a newer version.
 
@@ -178,8 +198,9 @@ New versions are published on [the releases page](https://github.com/plausible/a
 
 We recommend to pin the major version instead of using `latest`. Either way the general flow for upgrading between minor version would look like this:
 
+<sub><kbd>console</kbd></sub>
 ```console
-$ cd hosting
+$ cd hosting # or wherever you cloned this repo
 $ docker compose stop plausible
 [+] Running 1/1
  ✔ Container hosting-plausible-1  Stopped
@@ -208,29 +229,35 @@ ghcr.io/plausible/community-edition   v2.1          63f7c8708294   6 days ago
 ghcr.io/plausible/community-edition   v2.1.0-rc.0   2b2735265a65   7 months ago   163MB
 $ docker rmi 2b2735265a65
 Untagged: ghcr.io/plausible/community-edition:v2.1.0-rc.0
-// etc.
+...
 ```
 
+> [!TIP]
 > You can omit <kbd>-f docker-compose.yml -f reverse-proxy/docker-compose.caddy-gen.yml</kbd> if you are not using Caddy.
 
-Changes in major versions would involve performing a data migration (e.g.[v2.0.0](https://github.com/plausible/analytics/releases/tag/v2.0.0)) or some other extra step.
+Changes in major versions would involve performing a data migration (e.g. [v2.0.0](https://github.com/plausible/analytics/releases/tag/v2.0.0)) or some other extra step.
 
 ## Configure
 
-Plausible is configured with environment variables, by default supplied via [<kbd>plausible-conf.env</kbd>](https://github.com/plausible/community-edition/blob/v2.1.0/plausible-conf.env) [env_file.](https://github.com/plausible/community-edition/blob/v2.1.0/docker-compose.yml#L38-L39)
+Plausible is configured with environment variables, by default supplied via [plausible-conf.env](./plausible-conf.env) [env_file.](./docker-compose.yml#L38-L39)
 
-> Note that if you start a container with one set of ENV vars and then update the ENV vars and restart the container, they won't take effect due to the immutable nature of the containers. The container needs to be recreated.
+> [!WARNING]
+> Note that if you start a container with one set of ENV vars and then update the ENV vars and restart the container, they won't take effect due to the immutable nature of the containers. The container needs to be **recreated.**
 
-Here's the minimal <kbd>plausible-conf.env</kbd> we got from [Quick start.](#quick-start)
+#### Example configurations
 
+Here's the minimal configuration file we got from the [quick start:](#quick-start)
+
+<sub><kbd>plausible-conf.env</kbd></sub>
 ```env
 BASE_URL=https://plausible.example.com
 SECRET_KEY_BASE=GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz
 TOTP_VAULT_KEY=dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I=
 ```
 
-And here's <kbd>plausible-conf.env</kbd> with some extra configuration
+And here's a configuration with some extra options provided:
 
+<sub><kbd>plausible-conf.env</kbd></sub>
 ```env
 BASE_URL=https://plausible.example.com
 SECRET_KEY_BASE=GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz
@@ -240,7 +267,12 @@ MAXMIND_EDITION=GeoLite2-City
 GOOGLE_CLIENT_ID=140927866833-002gqg48rl4iku76lbkk0qhu0i0m7bia.apps.googleusercontent.com
 GOOGLE_CLIENT_SECRET=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
 MAILER_NAME=Plausible
-MAILER_EMAIL=plausible@plausible.example.com
+MAILER_EMAIL=somebody+plausible@gmail.com
+MAILER_ADAPTER=Bamboo.Mua
+SMTP_HOST_ADDR=smtp.gmail.com
+SMTP_HOST_PORT=587
+SMTP_USER_NAME=somebody@gmail.com
+SMTP_USER_PWD="wnqj fkbn jcwc byxk" 
 DISABLE_REGISTRATION=invite_only
 ```
 
@@ -248,22 +280,23 @@ Here're the currently supported ENV vars:
 
 ### Required
 
-#### `BASE_URL`
+#### BASE_URL
 
 Configures the base URL to use in link generation, doesn't have any defaults and needs to be provided in the ENV vars
 
 <sub><kbd>plausible-conf.env</kbd></sub>
 ```env
-BASE_URL=https://example.fun
+BASE_URL=https://plausible.example.com
 ```
 
+> [!NOTE]
 > In production systems, this should be your ingress host (CDN or proxy).
 
 ---
 
-#### `SECRET_KEY_BASE`
+#### SECRET_KEY_BASE
 
-Configures the secret used for sessions in the dashboard, doesn't have any defaults and needs to be provided in the ENV vars, can be generated with `openssl rand -base64 48`
+Configures the secret used for sessions in the dashboard, doesn't have any defaults and needs to be provided in the ENV vars, can be generated with OpenSSL:
 
 <sub><kbd>console</kbd></sub>
 ```console
@@ -274,15 +307,16 @@ GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz
 <sub><kbd>plausible-conf.env</kbd></sub>
 ```env
 SECRET_KEY_BASE=GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz
-``````
+```
 
-> ⚠️ Don't use this exact value or someone would be able to sign a cookie with `user_id=1` and log in as the admin!
+> [!WARNING]
+> Don't use this exact value or someone would be able to sign a cookie with `user_id=1` and log in as the admin!
 
-> ⚠️ [`SECRET_KEY_BASE`](#secret_key_base) needs to be either Bsde16 or Base64 encoded 32 (or more) bytes.
+---
 
-#### `TOTP_VAULT_KEY`
+#### TOTP_VAULT_KEY
 
-Configures the secret used for encrypting TOTP secrets at rest, doesn't have any defaults and needs to be provided in the ENV vars, can be generated with `openssl rand -base64 32`
+Configures the secret used for encrypting TOTP secrets at rest using AES256-GCM, doesn't have any defaults and needs to be provided in the ENV vars, can be generated with OpenSSL:
 
 <sub><kbd>console</kbd></sub>
 ```console
@@ -295,14 +329,9 @@ dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I=
 TOTP_VAULT_KEY=dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I=
 ``````
 
-> [`TOTP_VAULT_KEY`](#totp_vault_key) needs to be Base64 encoded 32 bytes.
+### Registration
 
-### Optional
+#### DISABLE_REGISTRATION
-
-<details>
-<summary>Registration</summary>
-
-#### `DISABLE_REGISTRATION`
 
 Default: `true`
 
@@ -310,47 +339,48 @@ Restricts registration of new users. Possible values are `true` (full restrictio
 
 ---
 
-#### `ENABLE_EMAIL_VERIFICATION`
+#### ENABLE_EMAIL_VERIFICATION
 
 Default: `false`
 
-When enabled, new users need to verify their email addressby following a link delivered to their mailbox. Please configure your server for SMTP to receive this email. You can find Plausible's SMTP configuration options under "Email" below.
+When enabled, new users need to verify their email addressby following a link delivered to their mailbox. Please configure your server for SMTP to receive this email. You can find Plausible's SMTP configuration options under [below.](#email)
 
 If something went wrong you can run this command to verify all users in the database:
 
 <sub><kbd>console</kbd></sub>
 ```console
-$ cd hosting
+$ cd hosting # or wherever you cloned this repo
 $ docker compose exec plausible_db psql -U postgres -h localhost -d plausible_db -c "UPDATE users SET email_verified = true;"
 ```
 
-</details>
+### Web
-<details>
-<summary>Web</summary>
 
-#### `LISTEN_IP`
+#### LISTEN_IP
 
 Default: `0.0.0.0`
 
 Configures the IP address to bind the listen socket for the web server.
 
+> [!WARNING]
 > Note that setting it to `127.0.0.1` in a container would make the web server unavailable from outside the container.
 
 ---
 
-#### `PORT`
+#### PORT
 
 Default: `8000`
 
 Configures the port to bind the listen socket for the web server.
 
-</details>
+---
-<details>
+
-<summary>Database</summary><br/>
+### Database
 
 Plausible uses PostgreSQL for storing user data and ClickhouseDB for analytics data. Use the following variables to configure them.
 
-#### `DATABASE_URL`
+---
+
+#### DATABASE_URL
 
 Default: `postgres://postgres:postgres@plausible_db:5432/plausible_db`
 
@@ -358,7 +388,7 @@ Configures the URL for PostgreSQL database.
 
 ---
 
-#### `CLICKHOUSE_DATABASE_URL`
+#### CLICKHOUSE_DATABASE_URL
 
 Default: `http://plausible_events_db:8123/plausible_events_db`
 
@@ -366,7 +396,7 @@ Configures the URL for ClickHouse database.
 
 ---
 
-#### `ECTO_IPV6`
+#### ECTO_IPV6
 
 Enables Ecto to use IPv6 when connecting to the PostgreSQL database. Not set by default.
 
@@ -377,7 +407,7 @@ ECTO_IPV6=true
 
 ---
 
-#### `ECTO_CH_IPV6`
+#### ECTO_CH_IPV6
 
 Enables Ecto to use IPv6 when connecting to the ClickHouse database. Not set by default.
 
@@ -386,13 +416,11 @@ Enables Ecto to use IPv6 when connecting to the ClickHouse database. Not set by
 ECTO_CH_IPV6=true
 ```
 
-</details>
+### Google
-<details>
-<summary>Google</summary><br/>
 
-For step-by-step integration with Google [see below.](#integrate)
+For step-by-step integration with Google [see below.](#google-integration)
 
-#### `GOOGLE_CLIENT_ID`
+#### GOOGLE_CLIENT_ID
 
 The Client ID from the Google API Console for your project. Not set by default.
 
@@ -403,7 +431,7 @@ GOOGLE_CLIENT_ID=140927866833-002gqg48rl4iku76lbkk0qhu0i0m7bia.apps.googleuserco
 
 ---
 
-#### `GOOGLE_CLIENT_SECRET`
+#### GOOGLE_CLIENT_SECRET
 
 The Client Secret from the Google API Console for your project. Not set by default.
 
@@ -412,23 +440,13 @@ The Client Secret from the Google API Console for your project. Not set by defau
 GOOGLE_CLIENT_SECRET=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
 ```
 
-</details>
+### IP Geolocation
-<details>
-<summary>IP Geolocation</summary><br/>
 
 Plausible CE uses the country database created by [db-ip](https://db-ip.com/) for enriching analytics data with visitor countries. The database is shipped within the container image and country data collection happens automatically.
 
-Optionally, you can provide a different database. For example, you can use [MaxMind](https://www.maxmind.com) services and enable city-level geolocation.
+Optionally, you can provide a different database. For example, you can use [MaxMind](https://www.maxmind.com) services and enable city-level geolocation:
 
-
+<sub><kbd>plausible-conf.env</kbd></sub>
-| Parameter              | Default                                                                                                                  | Description                                                                                                                                                                                                                        |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `IP_GEOLOCATION_DB`    | /app/lib/plausible-0.0.1/priv/geodb/dbip-country.mmdb.gz                                                                 | This database is used to lookup GeoName IDs for IP addresses. If not set, Plausible defaults to the [file](https://github.com/plausible/analytics/blob/v2.0.0/Dockerfile#L47) shipped within the container image.                  |
-| `GEONAMES_SOURCE_FILE` | [/app/lib/location-0.1.0/priv/geonames.lite.csv](https://github.com/plausible/location/blob/main/priv/geonames.lite.csv) | This file is used to turn GeoName IDs into human readable strings for display on the dashboard. Defaults to the one shipped within the container image.                                                                            |
-| `MAXMIND_LICENSE_KEY`  | --                                                                                                                       | If set, this ENV variable takes precedence over `IP_GEOLOCATION_DB` and makes Plausible download (and keep up to date) a free MaxMind GeoLite2 MMDB of the selected edition. [See below](#integrate) for integration instructions. |
-| `MAXMIND_EDITION`      | <kbd>GeoLite2-City</kbd>                                                                                                 | MaxMind database edition to use (only if `MAXMIND_LICENSE_KEY` is set)                                                                                                                                                             |
-
-<sub>Example <kbd>plausible-conf.env</kbd> with MaxMind configured</sub>
 ```env
 BASE_URL=https://plausible.example.com
 SECRET_KEY_BASE=GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz
@@ -436,46 +454,164 @@ MAXMIND_LICENSE_KEY=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
 MAXMIND_EDITION=GeoLite2-City
 ```
 
-</details>
+---
-<details><summary>Email</summary><br/>
 
-Plausible CE uses a SMTP server to send transactional emails e.g. account activation, password reset. In addition, it sends non-transactional emails like weekly or monthly reports.
+#### IP_GEOLOCATION_DB
 
-| Parameter               | Default                          | Description                                                                     |
+Default: `/app/lib/plausible-0.0.1/priv/geodb/dbip-country.mmdb.gz`
-| ----------------------- | -------------------------------- | ------------------------------------------------------------------------------- |
-| `MAILER_EMAIL`          | <kbd>hello@plausible.local</kbd> | The email id to use for as _from_ address of all communications from Plausible. |
-| `MAILER_NAME`           | --                               | The display name for the sender (_from_).                                       |
-| `SMTP_HOST_ADDR`        | <kbd>localhost</kbd>             | The host address of your SMTP server.                                           |
-| `SMTP_HOST_PORT`        | <kbd>25</kbd>                    | The port of your SMTP server.                                                   |
-| `SMTP_USER_NAME`        | --                               | The username/email in case SMTP auth is enabled.                                |
-| `SMTP_USER_PWD`         | --                               | The password in case SMTP auth is enabled.                                      |
-| `SMTP_HOST_SSL_ENABLED` | <kbd>false</kbd>                 | If SSL is enabled for SMTP connection                                           |
-| `SMTP_RETRIES`          | <kbd>2</kbd>                     | Number of retries to make until mailer gives up.                                |
 
-Alternatively, you can use other [Bamboo Adapters](https://hexdocs.pm/bamboo/readme.html#available-adapters) such as Postmark, Mailgun, Mandrill or Send Grid to send transactional emails. In this case, use the following parameters:
+This database is used to lookup GeoName IDs for IP addresses. If not set, defaults to the [file](https://github.com/plausible/analytics/blob/v2.0.0/Dockerfile#L47) shipped within the container image.
 
-| Parameter          | Default                       | Description                                                                                                                                                                                                                                                                                             |
+---
-| ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MAILER_ADAPTER`   | <kbd>Bamboo.SMTPAdapter</kbd> | Instead of the default, replace this with <kbd>Bamboo.PostmarkAdapter</kbd>, <kbd>Bamboo.MailgunAdapter</kbd>, <kbd>Bamboo.MandrillAdapter</kbd> or <kbd>Bamboo.SendGridAdapter</kbd> and add the appropriate variables below                                                                           |
-| `POSTMARK_API_KEY` | --                            | Enter your Postmark API key.                                                                                                                                                                                                                                                                            |
-| `MAILGUN_API_KEY`  | --                            | Enter your Mailgun API key.                                                                                                                                                                                                                                                                             |
-| `MAILGUN_DOMAIN`   | --                            | Enter your Mailgun domain.                                                                                                                                                                                                                                                                              |
-| `MAILGUN_BASE_URI` | --                            | This is optional. Mailgun makes a difference in the API base URL between sender domains from within the EU and outside. By default, the base URL is set to <kbd>https://api.mailgun.net/v3</kbd>. To override this you can pass <kbd>https://api.eu.mailgun.net/v3</kbd> if you are using an EU domain. |
-| `MANDRILL_API_KEY` | --                            | Enter your Mandrill API key.                                                                                                                                                                                                                                                                            |
-| `SENDGRID_API_KEY` | --                            | Enter your SendGrid API key.                                                                                                                                                                                                                                                                            |
 
-In case you are using Postmark, you have to set the `MAILER_EMAIL` variable which needs to be configured in PostmarkApps sender signatures.
+#### GEONAMES_SOURCE_FILE
+
+Default: [/app/lib/location-0.1.0/priv/geonames.lite.csv](https://github.com/plausible/location/blob/main/priv/geonames.lite.csv)
+
+This file is used to turn GeoName IDs into human readable strings for display on the dashboard. Defaults to the one shipped within the container image.
+
+---
+
+#### MAXMIND_LICENSE_KEY
+
+If set, this ENV variable takes precedence over [IP_GEOLOCATION_DB](#ip_geolocation_db) and makes Plausible download (and keep up to date) a free MaxMind GeoLite2 MMDB of the selected edition. [See below](#maxmind-integration) for integration instructions.
+
+---
+
+#### MAXMIND_EDITION
+
+Default: `GeoLite2-City`
+
+MaxMind database edition to use (only if [MAXMIND_LICENSE_KEY](#maxmind_license_key) is set)
+
+### Email
+
+Plausible CE sends transactional emails e.g. account activation, password reset. In addition, it sends non-transactional emails like weekly or monthly reports.
+
+It uses SMTP with an optional [relay](#smtp_host_addr) by default. Alternatively, you can use other [services](https://hexdocs.pm/bamboo/readme.html#available-adapters) such as Postmark, Mailgun, Mandrill or Send Grid to send emails.
+
+[Here's](https://gist.github.com/ruslandoga/c94ce526231fb77930132aaeda3fc3c9) a short guide on using your Gmail account for email delivery.
+
+#### MAILER_ADAPTER
+
+Default: `Bamboo.SMTPAdapter`
+
+Instead of the default, you can replace this with <kbd>Bamboo.PostmarkAdapter</kbd>, <kbd>Bamboo.MailgunAdapter</kbd>, <kbd>Bamboo.MandrillAdapter</kbd> or <kbd>Bamboo.SendGridAdapter</kbd> and add the appropriate variables.
+
+<details>
+<summary>Having problems with the default SMTP client?</summary>
+
+---
+
+Please try the new SMTP client introduced in [v2.1.0](https://github.com/plausible/analytics/discussions/4125) by setting MAILER_ADAPTER to `Bamboo.Mua`. All the `SMTP_*` environment variables can stay the same.
+
+<sub><kbd>plausible-conf.env</kbd></sub>
+```diff
+  BASE_URL=https://plausible.example.com
+  SECRET_KEY_BASE=PkVcxRgQDfQyhPETlog3vvCrj5LdYFSv4ejPEJHJO+i/37w6RZfRjeVCpJayjUjJMfXsNurcv5upPhTRoD3KgQ==
+  TOTP_VAULT_KEY=aihU7k+GSBKbcVFuX9VEPyUhuwlKEomqA94/SQQ0NR4=
+  SMTP_HOST_ADDR=smtp.gmail.com
+  SMTP_HOST_PORT=587
+  SMTP_USER_NAME=somebody@gmail.com
+  SMTP_USER_PWD="wnqj fkbn jcwc byxk"
++ MAILER_ADAPTER=Bamboo.Mua
+```
+
+---
 
 </details>
 
+#### MAILER_EMAIL
+
+Default: `hello@plausible.local`
+
+The email id to use for as _from_ address of all communications from Plausible.
+
+#### MAILER_NAME
+
+The display name for the sender (_from_).
+
+---
+
+#### SMTP_HOST_ADDR
+
+The host address of your SMTP relay.
+
+#### SMTP_HOST_PORT
+
+Default: `25`
+
+The port of your SMTP relay.
+
+#### SMTP_USER_NAME
+
+The username/email in case SMTP auth is required on your SMTP relay.
+
+#### SMTP_USER_PWD
+
+The password in case SMTP auth is required on your SMTP relay.
+
+#### SMTP_HOST_SSL_ENABLED
+
+Default: `false`
+
+Configures whether SMTPS (SMTP over SSL) is enabled for SMTP connection, e.g. when you use port 465.
+
+#### SMTP_RETRIES
+
+Default: `2`
+
+Number of retries to make until mailer gives up.
+
+---
+
+#### POSTMARK_API_KEY
+
+Enter your Postmark API key.
+
+> [!NOTE]
+> You also have to set the [MAILER_EMAIL](#mailer_email) variable which needs to be configured in PostmarkApps sender signatures.
+
+---
+
+#### MAILGUN_API_KEY
+
+Enter your Mailgun API key.
+
+#### MAILGUN_DOMAIN
+
+Enter your Mailgun domain.
+
+#### MAILGUN_BASE_URI
+
+Default: `https://api.mailgun.net/v3`
+
+Mailgun makes a difference in the API base URL between sender domains from within the EU and outside. By default, the base URL is set to <kbd>https://api.mailgun.net/v3</kbd>. To override this you can pass <kbd>https://api.eu.mailgun.net/v3</kbd> if you are using an EU domain.
+
+---
+
+#### MANDRILL_API_KEY
+
+Enter your Mandrill API key.
+
+---
+
+#### SENDGRID_API_KEY
+
+Enter your SendGrid API key.
+
 ## Integrate
 
-<details>
+### Google integration
-<summary>Google</summary>
 
 Integrating with Google either to get search keywords for hits from Google search or for imports from Universal Analytics can be frustrating.
 
-The following screenshot-annotated guide shows how to do it all in an easy way: follow the Google-colored arrows.
+The following screenshot-annotated guide shows how to do it all in an easy way: just follow the Google-colored arrows!
+
+<details>
+<summary><b>View the guide</b></summary>
+
+---
 
 Here's the outline of what we'll do:
 
@@ -488,10 +624,12 @@ Here's the outline of what we'll do:
 - [Integrate with Google Search](#integrate-with-google-search)
   - [Enable APIs for Google Search integration](#enable-apis-for-google-search-integration)
   - [Link it with Plausible](#link-it-with-plausible)
-- [Import historical data from Universal Analytics](#import-historical-data-from-universal-analytics)
+- [Import historical data from UA and GA4](#import-historical-data-from-ua-and-ga4)
   - [Enable APIs for exports on Google Cloud](#enable-apis-for-exports-on-google-cloud)
   - [Import into Plausible](#import-into-plausible)
 
+---
+
 ### Set up OAuth on Google Cloud
 
 #### Select or create a Google Cloud project
@@ -574,11 +712,11 @@ Pick <kbd>Web application</kbd> for the application type, type the name for the
 
 <img src="./images/3-oauth-client-create.png">
 
-That redirect URL should be `/auth/google/callback` on your Plausible instance's [<kbd>BASE_URL</kbd>](https://github.com/plausible/hosting/blob/bb6decee4d33ccf84eb235b6053443a01498db53/plausible-conf.env#L1)
+That redirect URL should be `/auth/google/callback` on your Plausible instance's [<kbd>BASE_URL</kbd>](./plausible-conf.env#L1)
 
 <img src="./images/3-oauth-client-created.png">
 
-Copy these to your [<kbd>plausible-conf.env</kbd>](https://github.com/plausible/hosting/blob/master/plausible-conf.env) and make sure to recreate the `plausible` container since the ENV vars provided on startup get "baked in"
+Copy these to your [<kbd>plausible-conf.env</kbd>](./plausible-conf.env) and make sure to recreate the `plausible` container since the ENV vars provided on startup get "baked in"
 
 <sub><kbd>plausible-conf.env</kbd></sub>
 ```env
@@ -648,7 +786,7 @@ Go to the site settings on your Plausible dashboard.
 
 <img src="./images/6-plausible-settings-pick.png">
 
-In the settings select <kbd>Search Console</kbd> and press <kbd>Continue with Google</kbd>
+In the settings select <kbd>Integrations</kbd> and press <kbd>Continue with Google</kbd>
 
 > If you see a warning instead, that means you haven't set the <kbd>GOOGLE_CLIENT_ID</kbd> and <kbd>GOOGLE_CLIENT_SECRET</kbd> environment variables [correctly.](#issue-an-oauth-client-and-key-for-that-application)
 
@@ -676,7 +814,13 @@ Pick the property from Search Console.
 
 And now we should be able to drilldown into Google search terms like on [plausible.io](https://plausible.io/plausible.io/referrers/Google?source=Google)
 
-### Import historical data from Universal Analytics
+### Import historical data from UA and GA4
+
+Exporting historical data from Google requires enabling multiple APIs:
+
+<img src="./images/6-enabled-apis.png">
+
+Gotta Catch ‘Em All!
 
 #### Enable APIs for exports on Google Cloud
 
@@ -696,13 +840,31 @@ And enable it.
 
 <img src="./images/7-analytics-reporting-api-enable.png">
 
+Now search for <kbd>Google Analytics Admin API</kbd>
+
+<img src="./images/7-analytics-admin-api-search.png">
+
+And also enable it.
+
+<img src="./images/7-analytics-admin-api-enable.png">
+
+Finally search for <kbd>Google Analytics Data API</kbd>
+
+<img src="./images/7-analytics-data-api-search.png">
+
+And enable it!
+
+<img src="./images/7-analytics-data-api-enable.png">
+
+Phew!
+
 #### Import into Plausible
 
 Go to the site settings on your Plausible dashboard.
 
 <img src="./images/6-plausible-settings-pick.png">
 
-In the <kbd>General</kbd> settings section scroll down to <kbd>Data Import from Google Analytics</kbd> and press  <kbd>Continue with Google</kbd> button.
+In the <kbd>Imports & Exports</kbd> settings section press on the <kbd>Google Analytics</kbd> button.
 
 > If you see a warning instead, that means you haven't set the <kbd>GOOGLE_CLIENT_ID</kbd> and <kbd>GOOGLE_CLIENT_SECRET</kbd> environment variables [correctly.](#issue-an-oauth-client-and-key-for-that-application)
 
@@ -734,14 +896,14 @@ Confirm everything's in order and start the import.
 
 You'll receive an email once the data is imported.
 
-</details>
+---
-<details>
-<summary>MaxMind</summary>
-
-To use MaxMind you need to create an account [here.](https://www.maxmind.com/en/geolite2/signup) Once you have your account details, you can add `MAXMIND_LICENSE_KEY` and `MAXMIND_EDITION` environmental valiables to your <kbd>plausible-conf.env</kbd> and the databases would be automatically downloaded and kept up to date. Note that using city-level databases like MaxMind's `GeoLite2-City` requires ~1GB more RAM.
 
 </details>
 
+### MaxMind integration
+
+To use MaxMind you need to create an account [here.](https://www.maxmind.com/en/geolite2/signup) Once you have your account details, you can add [MAXMIND_LICENSE_KEY](#maxmind_license_key) and [MAXMIND_EDITION](#maxmind_edition) environmental valiables to your [plausible-conf.env](./plausible-conf.env) and the databases would be automatically downloaded and kept up to date. Note that using city-level databases like MaxMind's GeoLite2-City requires ~1GB more RAM.
+
 ## FAQ
 
 <details>
@@ -751,7 +913,7 @@ You can starts an Interactive Elixir session from within the `plausible` contain
 
 <sub><kbd>console</kbd></sub>
 ```console
-$ cd hosting
+$ cd hosting # or wherever you cloned this repo
 $ docker compose exec plausible bin/plausible remote
 ```
 ```elixir
@@ -779,7 +941,7 @@ You can starts a `clickhouse client` session from within the `plausible_events_d
 
 <sub><kbd>console</kbd></sub>
 ```console
-$ cd hosting
+$ cd hosting # or wherever you cloned this repo
 $ docker compose exec plausible_events_db clickhouse client --database plausible_events_db
 ```
 ```sql
@@ -817,7 +979,7 @@ You can starts a `psql` session from within the `plausible_db` container:
 
 <sub><kbd>console</kbd></sub>
 ```console
-$ cd hosting
+$ cd hosting # or wherever you cloned this repo
 $ docker compose exec plausible_db psql -U postgres -h localhost -d plausible_db
 ```
 ```sql

docker-compose.yml

@@ -1,12 +1,8 @@
-version: "3.3"
 services:
-  mail:
-    image: bytemark/smtp
-    restart: always
-
   plausible_db:
-    # supported versions are 13, 14, and 15
+    # Plausible v2.1.0 was tested against PostgreSQL versions 15 and 16
-    image: postgres:14-alpine
+    # https://github.com/plausible/analytics/blob/v2.1.0/.github/workflows/elixir.yml#L21-L32
+    image: postgres:16-alpine
     restart: always
     volumes:
       - db-data:/var/lib/postgresql/data
@@ -14,10 +10,11 @@ services:
       - POSTGRES_PASSWORD=postgres
 
   plausible_events_db:
-    image: clickhouse/clickhouse-server:23.3.7.5-alpine
+    image: clickhouse/clickhouse-server:24.3.3.102-alpine
     restart: always
     volumes:
       - event-data:/var/lib/clickhouse
+      - event-logs:/var/log/clickhouse-server
       - ./clickhouse/clickhouse-config.xml:/etc/clickhouse-server/config.d/logging.xml:ro
       - ./clickhouse/clickhouse-user-config.xml:/etc/clickhouse-server/users.d/logging.xml:ro
     ulimits:
@@ -26,13 +23,12 @@ services:
         hard: 262144
 
   plausible:
-    image: ghcr.io/plausible/community-edition:v2.1.0-rc.0
+    image: ghcr.io/plausible/community-edition:v2.1.0
     restart: always
     command: sh -c "sleep 10 && /entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh run"
     depends_on:
       - plausible_db
       - plausible_events_db
-      - mail
     ports:
       - 127.0.0.1:8000:8000
     env_file:
@@ -43,3 +39,5 @@ volumes:
     driver: local
   event-data:
     driver: local
+  event-logs:
+    driver: local

reverse-proxy/README.md

@@ -38,7 +38,7 @@ $ docker-compose -f docker-compose.yml -f reverse-proxy/traefik/docker-compose.t
 Install the necessary Apache modules and restart Apache. Edit the file `reverse-proxy/apache2/plausible.conf` to contain the domain name you use for your server, then copy it into Apache's configuration folder. Enable it by creating a symlink in Apache's enabled sites folder with `a2ensite` command. Finally use Certbot to create a TLS certificate for your site:
 
 ```shell
-$ sudo a2enmod proxy proxy_http proxy_ajp remoteip headers
+$ sudo a2enmod proxy proxy_http proxy_ajp remoteip headers proxy_wstunnel
 $ sudo systemctl restart apache2
 $ sudo cp reverse-proxy/apache2/plausible.conf /etc/apache2/sites-available/
 $ sudo a2ensite plausible.conf

reverse-proxy/nginx/plausible

@@ -8,5 +8,12 @@ server {
 	location / {
 		proxy_pass http://127.0.0.1:8000;
 		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+
+		location = /live/websocket {
+			proxy_pass http://127.0.0.1:8000;
+			proxy_http_version 1.1;
+			proxy_set_header Upgrade $http_upgrade;
+			proxy_set_header Connection "Upgrade";
+		}
 	}
 }