diff --git a/README.md b/README.md index a98ba6b..bf77569 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ README.md clickhouse/ docker-compose.yml images/ In the downloaded directory you'll find two important files: -- [docker-compose.yml](./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](./plausible-conf.env) — configures the Plausible server itself. Full configuration options are documented [below.](#configure) Right now the latter looks like this: @@ -70,18 +70,21 @@ Right now the latter looks like this: ```env BASE_URL=replace-me SECRET_KEY_BASE=replace-me +TOTP_VAULT_KEY=replace-me ``` Let's do as it asks and populate these required environment variables with our own values. #### Required configuration -First we generate the [secret key base](#secret_key_base) using OpenSSL: +First we generate the [secret key base](#secret_key_base) and [TOTP vault key](#totp_vault_key) using OpenSSL: console ```console $ openssl rand -base64 48 GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz +$ openssl rand -base64 32 +dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I= ``` And then we decide on the [base URL](#base_url) where the instance would be accessible: @@ -92,6 +95,8 @@ And then we decide on the [base URL](#base_url) where the instance would be acce + BASE_URL=http://plausible.example.com - SECRET_KEY_BASE=replace-me + SECRET_KEY_BASE=GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz +- TOTP_VAULT_KEY=replace-me ++ TOTP_VAULT_KEY=dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I= ``` 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. @@ -142,6 +147,7 @@ Finally we need to update the base URL to use HTTPS scheme. - BASE_URL=http://plausible.example.com + BASE_URL=https://plausible.example.com SECRET_KEY_BASE=GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz + TOTP_VAULT_KEY=dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I= ``` Now we can start everything together. @@ -175,22 +181,20 @@ Next we'll go over how to upgrade the instance when a new release comes out, mor ## Upgrade -Each new [release](https://github.com/plausible/analytics/releases/tag/v2.0.0) contains information on how to upgrade to it from the previous version. This section outlines the -general steps and explains the versioning. +Each new [release](https://github.com/plausible/analytics/releases) contains information on how to upgrade to it from the previous version. This section outlines the general steps and explains the versioning. ### Version management Plausible CE follows [semantic versioning:](https://semver.org/) `MAJOR.MINOR.PATCH` -You can find available Plausible versions on [DockerHub](https://hub.docker.com/r/plausible/analytics). The default `latest` tag refers to the latest stable release tag. You can also pin your version: +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: -- plausible/analytics:v2 pins the major version to 2 but allows minor and patch version upgrades -- plausible/analytics:v2.0 pins the minor version to 2.0 but allows only patch upgrades +- ghcr.io/plausible/community-edition:v2 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 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. -New versions are published on [the releases page](https://github.com/plausible/analytics/releases) and their changes are documented in our [Changelog.](https://github.com/plausible/analytics/blob/master/CHANGELOG.md) Please note that database schema changes require running migrations when you're upgrading. However, we consider the schema -as an internal API and therefore schema changes aren't considered a breaking change. +New versions are published on [the releases page](https://github.com/plausible/analytics/releases) and their changes are documented in our [Changelog.](https://github.com/plausible/analytics/blob/master/CHANGELOG.md) Please note that database schema changes require running migrations when you're upgrading. However, we consider the schema as an internal API and therefore schema changes aren't considered a breaking change. 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: @@ -219,14 +223,12 @@ $ docker compose -f docker-compose.yml -f reverse-proxy/docker-compose.caddy-gen ✔ Container hosting-plausible_db-1 Running 0.0s ✔ Container hosting-plausible-1 Started 1.2s ✔ Container caddy-gen Running 0.0s -$ docker images --filter=reference='plausible/analytics:*' -REPOSITORY TAG IMAGE ID CREATED SIZE -plausible/analytics v2.0 2b2735265a65 7 months ago 163MB -plausible/analytics v1.5 5e1e0047953a 8 months ago 130MB -$ docker rmi 5e1e0047953a -Untagged: plausible/analytics:v1.5 -Untagged: plausible/analytics@sha256:365124b00f103ac40ce3c64cd49a869d94f2ded221d9bb7900be1cecfaf34acf -Deleted: sha256:5e1e0047953afc179ee884389e152b3f07343fb34e5586f9ecc2f33c6ba3bcaa +$ docker images --filter=reference='ghcr.io/plausible/community-edition:*' +REPOSITORY TAG IMAGE ID CREATED SIZE +ghcr.io/plausible/community-edition v2.1 63f7c8708294 6 days ago 83.4MB +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 ... ``` @@ -250,6 +252,7 @@ Here's the minimal configuration file we got from the [quick start:](#quick-star ```env BASE_URL=https://plausible.example.com SECRET_KEY_BASE=GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz +TOTP_VAULT_KEY=dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I= ``` And here's a configuration with some extra options provided: @@ -258,12 +261,18 @@ And here's a configuration with some extra options provided: ```env BASE_URL=https://plausible.example.com SECRET_KEY_BASE=GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz +TOTP_VAULT_KEY=dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I= MAXMIND_LICENSE_KEY=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 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 ``` @@ -303,6 +312,23 @@ SECRET_KEY_BASE=GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz > [!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! +--- + +#### TOTP_VAULT_KEY + +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: + +console +```console +$ openssl rand -base64 32 +dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I= +``` + +plausible-conf.env +```env +TOTP_VAULT_KEY=dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I= +`````` + ### Registration #### DISABLE_REGISTRATION @@ -462,7 +488,9 @@ MaxMind database edition to use (only if [MAXMIND_LICENSE_KEY](#maxmind_license_ 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 a [relay](./docker-compose.yml#L3-L5) 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. +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 @@ -470,6 +498,31 @@ Default: `Bamboo.SMTPAdapter` Instead of the default, you can replace this with Bamboo.PostmarkAdapter, Bamboo.MailgunAdapter, Bamboo.MandrillAdapter or Bamboo.SendGridAdapter and add the appropriate variables. +
+Having problems with the default SMTP client? + +--- + +Please try the new SMTP client introduced in [v2.1.0-rc.1](https://github.com/plausible/analytics/discussions/4084) by setting MAILER_ADAPTER to `Bamboo.Mua`. All the `SMTP_*` environment variables can stay the same. + +plausible-conf.env +```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 +``` + +We plan to make it the new default in the final v2.1.0 release. + +--- + +
+ #### MAILER_EMAIL Default: `hello@plausible.local` @@ -484,8 +537,6 @@ The display name for the sender (_from_). #### SMTP_HOST_ADDR -Default: [`mail`](./docker-compose.yml#L3-L5) - The host address of your SMTP relay. #### SMTP_HOST_PORT @@ -751,6 +802,10 @@ Trust our own application. +Trust more. + + + Allow viewing Search Console data. @@ -801,10 +856,22 @@ Trust our own application. -Pick the view to import and then follow the Plausible directions. +Trust more. + + + +Pick the view to import. +And then follow the Plausible directions. + + + +Confirm everything's in order and start the import. + + + You'll receive an email once the data is imported. --- diff --git a/docker-compose.yml b/docker-compose.yml index c77f46b..8bf8599 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,8 +1,4 @@ services: - mail: - image: bytemark/smtp - restart: always - plausible_db: # Plausible v2.0.0 was tested against PostgreSQL versions 12, 13, and 14 # https://github.com/plausible/analytics/blob/v2.0.0/.github/workflows/elixir.yml#L16 @@ -14,7 +10,7 @@ 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 @@ -27,13 +23,12 @@ services: hard: 262144 plausible: - image: plausible/analytics:v2.0 + image: ghcr.io/plausible/community-edition:v2.1.0-rc.1 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: @@ -46,4 +41,3 @@ volumes: driver: local event-logs: driver: local - diff --git a/images/6-choose-google-account.png b/images/6-choose-google-account.png index 5b1b854..825cd36 100644 Binary files a/images/6-choose-google-account.png and b/images/6-choose-google-account.png differ diff --git a/images/6-data-continue.png b/images/6-data-continue.png new file mode 100644 index 0000000..2191fb7 Binary files /dev/null and b/images/6-data-continue.png differ diff --git a/images/6-data-import.png b/images/6-data-import.png index 65ee2ee..13e5876 100644 Binary files a/images/6-data-import.png and b/images/6-data-import.png differ diff --git a/images/6-import-continue.png b/images/6-import-continue.png new file mode 100644 index 0000000..09d1ab9 Binary files /dev/null and b/images/6-import-continue.png differ diff --git a/images/6-import.png b/images/6-import.png new file mode 100644 index 0000000..799392b Binary files /dev/null and b/images/6-import.png differ diff --git a/images/6-pick-view.png b/images/6-pick-view.png index d60cce8..97dd473 100644 Binary files a/images/6-pick-view.png and b/images/6-pick-view.png differ diff --git a/images/6-plausible-settings-pick.png b/images/6-plausible-settings-pick.png index 9f3c572..25d395a 100644 Binary files a/images/6-plausible-settings-pick.png and b/images/6-plausible-settings-pick.png differ diff --git a/images/6-plausible-settings-search-console.png b/images/6-plausible-settings-search-console.png index e2b4a03..e29c633 100644 Binary files a/images/6-plausible-settings-search-console.png and b/images/6-plausible-settings-search-console.png differ diff --git a/images/6-property.png b/images/6-property.png index 73445bb..3630b79 100644 Binary files a/images/6-property.png and b/images/6-property.png differ diff --git a/images/6-sign-in-copycat.png b/images/6-sign-in-copycat.png new file mode 100644 index 0000000..ca485de Binary files /dev/null and b/images/6-sign-in-copycat.png differ diff --git a/plausible-conf.env b/plausible-conf.env index 64e0fea..e026eda 100644 --- a/plausible-conf.env +++ b/plausible-conf.env @@ -1,2 +1,3 @@ BASE_URL=replace-me SECRET_KEY_BASE=replace-me +TOTP_VAULT_KEY=replace-me