community-edition

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./images/logo_dark.svg" width="300"> <source media="(prefers-color-scheme: light)" srcset="./images/logo_light.svg" width="300"> <img src="./images/logo_light.svg" width="300"> </picture> </p> <p align="center"> <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 -->

Contact:

• For release announcements please go to GitHub releases.
• For a question or advice please go to GitHub discussions.

---

<p align="center"> <a href="#install">Install</a> &bull; <a href="#upgrade">Upgrade</a> &bull; <a href="#configure">Configure</a> &bull; <a href="#integrate">Integrate</a> &bull; <a href="#faq">FAQ</a> </p>

---

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.

Requirements

The only thing you need to install Plausible CE is a server with Docker. The server must have a CPU with x86_64 or arm64 architecture and support for SSE 4.2 or equivalent NEON instructions. We recommend using a minimum of 4GB of RAM but the requirements will depend on your site traffic.

We've tested this on Digital Ocean (affiliate link) but any hosting provider works. If your server doesn't come with Docker pre-installed, you can follow their docs to install it.

To make your Plausible CE instance accessible on a (sub)domain, you also need to be able to edit your DNS. Plausible CE isn't currently designed for subfolder installations.

Quick start

To get started quickly, clone the plausible/community-edition repo. It has everything you need to boot up your own Plausible CE server.

_{<kbd>console</kbd>}

$ git clone https://github.com/plausible/community-edition hosting
Cloning into 'community-edition'...
remote: Enumerating objects: 280, done.
remote: Counting objects: 100% (146/146), done.
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 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 — installs and orchestrates networking between your Plausible CE server, Postgres database, and Clickhouse database for stats.
• plausible-conf.env — configures the Plausible server itself. Full configuration options are documented below.

Right now the latter looks like this:

_{<kbd>plausible-conf.env</kbd>}

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 and TOTP vault key using OpenSSL:

_{<kbd>console</kbd>}

$ openssl rand -base64 48
GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz
$ openssl rand -base64 32
dsxvbn3jxDd16az2QpsX5B8O+llxjQ2SJE2i5Bzx38I=

And then we decide on the base URL where the instance would be accessible:

_{<kbd>plausible-conf.env</kbd>}

- BASE_URL=replace-me
+ 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 to enable HTTPS.

Caddy

[!TIP] For other reverse-proxy setups please see reverse-proxy docs.

<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 to ensure it's not limited to localhost (127.0.0.1). This change allows the service to be accessible from any network interface:

_{<kbd>docker-compose.yml</kbd>}

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.

_{<kbd>reverse-proxy/docker-compose.caddy-gen.yml</kbd>}

  plausible:
    labels:
-     virtual.host: "example.com" # change to your domain name
+     virtual.host: "plausible.example.com"
      virtual.port: "8000"
-     virtual.tls-email: "admin@example.com" # change to your email
+     virtual.tls-email: "admin@plausible.example.com"

Finally we need to update the base URL to use HTTPS scheme.

_{<kbd>plausible-conf.env</kbd>}

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

Launch

_{<kbd>console</kbd>}

$ docker compose -f docker-compose.yml -f reverse-proxy/docker-compose.caddy-gen.yml up -d
[+] Running 19/19
 ✔ plausible_db 9 layers [⣿⣿⣿⣿⣿⣿⣿]          Pulled
 ✔ plausible_events_db 7 layers [⣿⣿⣿⣿⣿⣿⣿]   Pulled
 ✔ plausible 7 layers [⣿⣿⣿⣿⣿⣿⣿]             Pulled
 ✔ caddy-gen 8 layers [⣿⣿⣿⣿⣿⣿⣿⣿]            Pulled
[+] Running 5/5
 ✔ Network hosting_default                  Created
 ✔ Container hosting-plausible_db-1         Started
 ✔ Container hosting-plausible_events_db-1  Started
 ✔ Container hosting-plausible-1            Started
 ✔ 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 the base URL and see the registration screen for the admin user.

[!TIP] If something feels off, make sure to check out the logs with <kbd>docker compose logs</kbd> and start a GitHub discussion.

🎉 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!

Upgrade

Each new release 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: MAJOR.MINOR.PATCH

You can find available Plausible versions on Github packages. The default latest tag refers to the latest stable release tag. You can also pin your version:

• <kbd>ghcr.io/plausible/community-edition:v2</kbd> pins the major version to 2 but allows minor and patch version 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.

New versions are published on the releases page and their changes are documented in our Changelog. 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:

_{<kbd>console</kbd>}

$ cd hosting # or wherever you cloned this repo
$ docker compose stop plausible
[+] Running 1/1
 ✔ Container hosting-plausible-1  Stopped
$ docker compose rm plausible
? Going to remove hosting-plausible-1 Yes
[+] Running 1/0
 ✔ Container hosting-plausible-1  Removed
$ docker compose -f docker-compose.yml -f reverse-proxy/docker-compose.caddy-gen.yml up -d
[+] Running 8/8
 ✔ plausible 7 layers [⣿⣿⣿⣿⣿⣿⣿]      0B/0B      Pulled 6.4s
   ✔ 96526aa774ef Pull complete    0.4s
   ✔ 93631fa7258d Pull complete    0.6s
   ✔ 06afbc05374b Pull complete    1.6s
   ✔ 7ddeeadcce1e Pull complete    1.2s
   ✔ 724ddb9b523f Pull complete    2.8s
   ✔ 32581b0068b9 Pull complete    1.7s
   ✔ 4f4fb700ef54 Pull complete    2.0s
[+] Running 4/4
 ✔ Container hosting-plausible_events_db-1  Running    0.0s
 ✔ 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='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
...

[!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) or some other extra step.

Configure

Plausible is configured with environment variables, by default supplied via plausible-conf.env env_file.

[!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.

Example configurations

Here's the minimal configuration file we got from the quick start:

_{<kbd>plausible-conf.env</kbd>}

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:

_{<kbd>plausible-conf.env</kbd>}

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=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

Here're the currently supported ENV vars:

Required

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

_{<kbd>plausible-conf.env</kbd>}

BASE_URL=https://plausible.example.com

[!NOTE] In production systems, this should be your ingress host (CDN or proxy).

---

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:

_{<kbd>console</kbd>}

$ openssl rand -base64 48
GLVzDZW04FzuS1gMcmBRVhwgd4Gu9YmSl/k/TqfTUXti7FLBd7aflXeQDdwCj6Cz

_{<kbd>plausible-conf.env</kbd>}

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:

_{<kbd>console</kbd>}

$ openssl rand -base64