Self-Hosting Plausible Analytics with Docker on Debian 11

Original post at u.sb

This post walks through how to install Plausible Analytics with Docker on Debian 11 to self-host your website analytics.

PS: The same steps also apply to any Linux distribution that can run Docker.

Why self-host your analytics?#

The reason is simple: you should own your site data. Do you really want all your website data to be sold to so‑called “big data” companies by third parties?

Plausible Analytics is a privacy‑focused web analytics platform. After testing it for several months, it has proven sufficient for almost all needs and can replace commercial products such as Google Analytics.

Installing Plausible Analytics#

It’s recommended to install it under the /opt/plausible directory:

1
mkdir -p /opt/plausible
2
cd /opt/plausible

First, create a docker-compose.yaml file and adjust the parameters as needed:

1
version: "3.8"
2
services:
3
  mail:
4
    image: bytemark/smtp
5
    restart: always
6

7
  plausible_db:
8
    image: postgres:12
9
    volumes:
10
      - db-data:/var/lib/postgresql/data
11
    environment:
12
      - POSTGRES_PASSWORD=postgres
13
    restart: always
14

15
  plausible_events_db:
16
    image: yandex/clickhouse-server:21.3.2.5
17
    volumes:
18
      - event-data:/var/lib/clickhouse
19
      - ./clickhouse/clickhouse-config.xml:/etc/clickhouse-server/config.d/logging.xml:ro
20
      - ./clickhouse/clickhouse-user-config.xml:/etc/clickhouse-server/users.d/logging.xml:ro
21
    ulimits:
22
      nofile:
23
        soft: 262144
24
        hard: 262144
25
    restart: always
26

27
  plausible:
28
    image: plausible/analytics:latest
29
    command: sh -c "sleep 10 && /entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh db init-admin && /entrypoint.sh run"
30
    depends_on:
31
      - plausible_db
32
      - plausible_events_db
33
      - mail
34
      - geoip
35
    volumes:
36
      - ./geoip:/geoip:ro
37
    ports:
38
      - 127.0.0.1:8000:8000
39
    env_file:
40
      - plausible-conf.env
41
    restart: always
42

43
  geoip:
44
    image: maxmindinc/geoipupdate
45
    env_file:
46
      - geoip.env
47
    volumes:
48
      - ./geoip:/usr/share/GeoIP
49

50
volumes:
51
  db-data:
52
    driver: local
53
  event-data:
54
    driver: local
55
  geoip:
56
    driver: local

Next, in the same directory, create the geoip folder and the plausible-conf.env file:

1
mkdir -p geoip
2
touch plausible-conf.env
3
touch geoip.env

Edit plausible-conf.env and configure it following the official guide. Suppose your URL is https://stat.example.com/, an example configuration would look like this:

1
ADMIN_USER_EMAIL=管理员邮箱
2
ADMIN_USER_NAME=管理员用户名
3
ADMIN_USER_PWD=管理员密码
4
BASE_URL=https://stat.example.com/
5
SECRET_KEY_BASE=随机字符
6
MAILER_EMAIL=网站通知邮箱
7
SMTP_HOST_ADDR=SMTP 主机名
8
SMTP_HOST_PORT=SMTP 端口
9
SMTP_USER_NAME=SMTP 用户名
10
SMTP_USER_PWD=SMTP 密码
11
DISABLE_REGISTRATION=true
12
GEOLITE2_COUNTRY_DB=/geoip/GeoLite2-Country.mmdb

SECRET_KEY_BASE needs to be a 64‑character random string. You can generate one using openssl rand -base64 64 or pwgen 64.

Set DISABLE_REGISTRATION to true to disable user signups.

You can use any email delivery provider for SMTP. For a quick option, you can simply use free services like Gmail, or you can self‑host Mailcow for your own use; see the tutorial here.

Next, register an account with Maxmind. After registration, go to Account > Manage License Keys in the left menu, click Generate new license key to obtain a License Key, and make a note of both your Account ID and the License Key.

Then edit geoip.env and fill it in like this:

1
GEOIPUPDATE_EDITION_IDS=GeoLite2-Country
2
GEOIPUPDATE_FREQUENCY=168
3
GEOIPUPDATE_ACCOUNT_ID=你的 Account ID
4
GEOIPUPDATE_LICENSE_KEY=你的 License Key

Now pull the images and start the stack:

1
docker-compose pull
2
docker-compose up -d

Once it has started, you can access Plausible at http://127.0.0.1:8000/. If you want to expose it publicly, you’ll also need to configure an Nginx reverse proxy.

After reloading Nginx, you should be able to visit https://stat.example.com/.

Upgrading Plausible Analytics#

The universal Docker upgrade workflow:

1
docker-compose pull
2

3
docker-compose up -d
4

5
docker system prune

Backing up Plausible Analytics#

Backup#

1
#!/usr/bin/env sh
2

3
docker-compose stop
4
docker run --rm -v plausible_db-data:/volume -v `pwd`:/backup loomchild/volume-backup backup plausible_db-data
5
docker run --rm -v plausible_event-data:/volume -v `pwd`:/backup loomchild/volume-backup backup plausible_event-data
6
docker-compose start -d

Restore script:

1
#!/usr/bin/env sh
2

3
docker-compose stop
4
docker run --rm -v plausible_db-data:/volume -v `pwd`:/backup loomchild/volume-backup restore -f plausible_db-data
5
docker run --rm -v plausible_event-data:/volume -v `pwd`:/backup loomchild/volume-backup restore -f plausible_event-data
6
docker-compose start -d

Uninstalling Plausible Analytics#

1
docker-compose down
2
rm -rf /opt/plausible
3
docker image rm postgres:12
4
docker image rm maxmindinc/geoipupdate:latest
5
docker image rm plausible/analytics:latest
6
docker image rm yandex/clickhouse-server:21.3.2.5
7
docker image rm bytemark/smtp:latest
8
docker volume rm plausible_db-data
9
docker volume rm plausible_event-data

Adding to WordPress#

Directly edit the header.php file of the theme you’re using and add the tracking script right after <?php wp_head(); ?>.

If you prefer not to modify your theme, you can simply install the official plugin.

Adding to VuePress#

If you’re using VuePress v1.x, edit .vuepress/config.js and add the following under module.exports:

1
['script', {}, `
2
const script = document.createElement('script');
3
script.async = true;
4
script.defer = true;
5
script['data-domain'] = '统计域名';
6
script.src = 'https://stat.example.com/js/plausible.js';
7
document.head.appendChild(script);`
8
],

If you’re using VuePress v2.x, edit .vuepress/config.ts and add the following under export default:

1
['script', {}, `
2
const script = document.createElement('script');
3
script.async = true;
4
script.defer = true;
5
script['data-domain'] = '统计域名';
6
script.src = 'https://stat.example.com/js/plausible.js';
7
document.head.appendChild(script);`
8
],

Adding to Next.js#

Install the next-plausible package and use code similar to the following:

1
import PlausibleProvider from 'next-plausible'
2

3
export default function MyApp({ Component, pageProps }) {
4
  return (
5
    <PlausibleProvider domain="统计域名" customDomain="https://stat.example.com" selfHosted>
6
      <Component {...pageProps} />
7
    </PlausibleProvider>
8
  )
9
}

For more integration options, refer to the official docs.