Create LICENSE

This reverts commit 43e8842846.

.github/workflows/spellcheck.yml

@@ -0,0 +1,20 @@
+name: spellcheck
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  codespell:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: codespell-project/actions-codespell@v2
+        with:
+          check_filenames: true
+
+  typos:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: crate-ci/typos@master

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

clickhouse/clickhouse-config.xml

@@ -1,9 +1,16 @@
-<yandex>
+<clickhouse>
     <logger>
         <level>warning</level>
         <console>true</console>
     </logger>
     
+    <!-- 
+    Avoid the warning: "Listen [::]:9009 failed: Address family for hostname not supported". 
+    If Docker has IPv6 disabled, bind ClickHouse to IPv4 to prevent this issue. 
+    Add this to the configuration to ensure it listens on all IPv4 interfaces:
+    <listen_host>0.0.0.0</listen_host>
+    -->
+
     <!-- Stop all the unnecessary logging -->
     <query_thread_log remove="remove"/>
     <query_log remove="remove"/>
@@ -11,4 +18,6 @@
     <trace_log remove="remove"/>
     <metric_log remove="remove"/>
     <asynchronous_metric_log remove="remove"/>
-</yandex>
+    <session_log remove="remove"/>
+    <part_log remove="remove"/>
+</clickhouse>

clickhouse/clickhouse-user-config.xml

@@ -1,8 +1,8 @@
-<yandex>
+<clickhouse>
     <profiles>
         <default>
             <log_queries>0</log_queries>
             <log_query_threads>0</log_query_threads>
         </default>
     </profiles>
-</yandex>
+</clickhouse>

docker-compose.yml

@@ -1,11 +1,8 @@
-version: "3.3"
 services:
-  mail:
-    image: bytemark/smtp
-    restart: always
-
   plausible_db:
-    image: postgres:12
+    # Plausible v2.1.1 was tested against PostgreSQL versions 15 and 16
+    # https://github.com/plausible/analytics/blob/v2.1.1/.github/workflows/elixir.yml#L21-L32
+    image: postgres:16-alpine
     restart: always
     volumes:
       - db-data:/var/lib/postgresql/data
@@ -13,10 +10,11 @@ services:
       - POSTGRES_PASSWORD=postgres
 
   plausible_events_db:
-    image: yandex/clickhouse-server:21.3.2.5
+    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:
@@ -25,15 +23,14 @@ services:
         hard: 262144
 
   plausible:
-    image: plausible/analytics:latest
+    image: ghcr.io/plausible/community-edition:v2.1.1
     restart: always
-    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"
     depends_on:
       - plausible_db
       - plausible_events_db
-      - mail
     ports:
-      - 8000:8000
+      - 127.0.0.1:8000:8000
     env_file:
       - plausible-conf.env
 
@@ -42,5 +39,5 @@ volumes:
     driver: local
   event-data:
     driver: local
-  geoip:
+  event-logs:
     driver: local

geoip/docker-compose.geoip.yml

@@ -1,24 +0,0 @@
-version: "3.3"
-services:
-  plausible:
-    depends_on:
-      - geoip
-    environment:
-      - GEOLITE2_COUNTRY_DB=/geoip/GeoLite2-Country.mmdb
-    volumes:
-      - geoip:/geoip:ro
-
-  geoip:
-    image: maxmindinc/geoipupdate
-    restart: always
-    environment:
-      - GEOIPUPDATE_EDITION_IDS=GeoLite2-Country
-      - GEOIPUPDATE_FREQUENCY=168 # update every 7 days
-    env_file:
-      geoip/geoip.conf
-    volumes:
-      - geoip:/usr/share/GeoIP
-
-volumes:
-  geoip:
-    driver: local

geoip/geoip.conf

@@ -1,2 +0,0 @@
-GEOIPUPDATE_ACCOUNT_ID=<your-account-id>
-GEOIPUPDATE_LICENSE_KEY=<your-license-key>

kubernetes/README.md

@@ -1,38 +0,0 @@
-# Plausible Analytics in Kubernetes
-
-This guide is designed to extend the [normal self-hosting guide](https://plausible.io/docs/self-hosting), please refer to it before following this guide.
-
-## 1. Clone the hosting repo
-
-To deploy Plausible Analytics into Kubernetes first download the [plausible/hosting](https://github.com/plausible/hosting) repo.
-
-```bash
-git clone https://github.com/plausible/hosting
-cd hosting
-```
-
-## 2. Add required configuration
-
-Like the original self hosting guide configure your server in the `plausible-conf.env` file.
-
-## 3. Deploy the server
-
-Once you've entered your secret key base, base url and admin credentials, you're ready to deploy the server:
-
-```bash
-kubectl create namespace plausible # Create a new namespace for all resources
-kubectl -n plausible create secret generic plausible-config --from-env-file=plausible-conf.env # Create a configmap from the plausible-conf.env file
-# Please change the Postgres and Clickhouse passwords to something more secure here!
-kubectl -n plausible create secret generic plausible-db-user --from-literal='username=postgres' --from-literal='password=postgres' # Create the Postgres user
-kubectl -n plausible create secret generic plausible-events-db-user --from-literal='username=clickhouse' --from-literal='password=clickhouse' # Create the Clickhouse user
-kubectl -n plausible apply -f ./kubernetes
-```
-
-You can now navigate to http://{hostname}:8000 and see the login screen.
-
-When you first log in with your admin credentials, you will be prompted to enter a verification code which has been sent to your email. Please configure your server for SMTP to receive this email. [Here are Plausible's SMTP configuration options](https://plausible.io/docs/self-hosting-configuration#mailersmtp-setup).
-Otherwise, run this command to verify all users in the database:
-
-```bash
-kubectl -n plausible exec statefulset/plausible-db -- /bin/bash -c 'psql -U $POSTGRES_USER -d $POSTGRES_DB -c "UPDATE users SET email_verified = true;"'
-```

kubernetes/plausible-db.yaml

@@ -1,114 +0,0 @@
-apiVersion: v1
-kind: Service
-metadata:
-  name: plausible-db
-  labels:
-    app.kubernetes.io/name: postgres
-    app.kubernetes.io/component: database
-    app.kubernetes.io/part-of: plausible
-spec:
-  type: ClusterIP
-  ports:
-    - name: db
-      port: 5432
-      targetPort: 5432
-      protocol: TCP
-  selector:
-    app.kubernetes.io/name: postgres
-    app.kubernetes.io/component: database
-    app.kubernetes.io/part-of: plausible
----
-apiVersion: apps/v1
-kind: StatefulSet
-metadata:
-  name: plausible-db
-  labels:
-    app.kubernetes.io/name: postgres
-    app.kubernetes.io/component: database
-    app.kubernetes.io/part-of: plausible
-spec:
-  replicas: 1
-  serviceName: plausible-db
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: postgres
-      app.kubernetes.io/component: database
-      app.kubernetes.io/part-of: plausible
-  template:
-    metadata:
-      labels:
-        app.kubernetes.io/name: postgres
-        app.kubernetes.io/component: database
-        app.kubernetes.io/part-of: plausible
-    spec:
-      restartPolicy: Always
-      # see https://github.com/docker-library/postgres/blob/6bbf1c7b308d1c4288251d73c37f6caf75f8a3d4/14/buster/Dockerfile
-      securityContext:
-        runAsUser: 999
-        runAsGroup: 999
-        fsGroup: 999
-      containers:
-        - name: plausible-db
-          image: postgres:latest
-          imagePullPolicy: Always
-          ports:
-            - containerPort: 5432
-          volumeMounts:
-            - name: data
-              mountPath: /var/lib/postgresql/data
-          env:
-            - name: POSTGRES_DB
-              value: plausible
-            - name: PGDATA
-              value: /var/lib/postgresql/data/pgdata
-            - name: POSTGRES_USER
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-db-user
-                  key: username
-            - name: POSTGRES_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-db-user
-                  key: password
-          securityContext:
-            allowPrivilegeEscalation: false
-          resources:
-            limits:
-              memory: 2Gi
-              cpu: 1500m
-            requests:
-              memory: 65Mi
-              cpu: 15m
-          readinessProbe:
-            exec:
-              command:
-                - /bin/sh
-                - -c
-                - pg_isready -U postgres
-            initialDelaySeconds: 20
-            failureThreshold: 6
-            periodSeconds: 10
-          livenessProbe:
-            exec:
-              command:
-                - /bin/sh
-                - -c
-                - pg_isready -U postgres
-            initialDelaySeconds: 30
-            failureThreshold: 3
-            periodSeconds: 10
-  volumeClaimTemplates:
-    - metadata:
-        name: data
-        labels:
-          app.kubernetes.io/name: postgres
-          app.kubernetes.io/component: database
-          app.kubernetes.io/part-of: plausible
-      spec:
-        accessModes: ["ReadWriteOnce"]
-        resources:
-          requests:
-            storage: 128Mi
-          limits:
-            storage: 15Gi

kubernetes/plausible-events-db.yaml

@@ -1,150 +0,0 @@
-apiVersion: v1
-kind: Service
-metadata:
-  name: plausible-events-db
-  labels:
-    app.kubernetes.io/name: clickhouse
-    app.kubernetes.io/component: database
-    app.kubernetes.io/part-of: plausible
-spec:
-  type: ClusterIP
-  ports:
-    - name: db
-      port: 8123
-      targetPort: 8123
-      protocol: TCP
-  selector:
-    app.kubernetes.io/name: clickhouse
-    app.kubernetes.io/component: database
-    app.kubernetes.io/part-of: plausible
----
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: plausible-events-db-config
-data:
-  clickhouse-config.xml: |
-    <yandex>
-        <logger>
-            <level>warning</level>
-            <console>true</console>
-        </logger>
-
-        <!-- Stop all the unnecessary logging -->
-        <query_thread_log remove="remove"/>
-        <query_log remove="remove"/>
-        <text_log remove="remove"/>
-        <trace_log remove="remove"/>
-        <metric_log remove="remove"/>
-        <asynchronous_metric_log remove="remove"/>
-    </yandex>
-  clickhouse-user-config.xml: |
-    <yandex>
-        <profiles>
-            <default>
-                <log_queries>0</log_queries>
-                <log_query_threads>0</log_query_threads>
-            </default>
-        </profiles>
-    </yandex>
----
-apiVersion: apps/v1
-kind: StatefulSet
-metadata:
-  name: plausible-events-db
-  labels:
-    app.kubernetes.io/name: clickhouse
-    app.kubernetes.io/component: database
-    app.kubernetes.io/part-of: plausible
-spec:
-  replicas: 1
-  serviceName: plausible-events-db
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: clickhouse
-      app.kubernetes.io/component: database
-      app.kubernetes.io/part-of: plausible
-  template:
-    metadata:
-      labels:
-        app.kubernetes.io/name: clickhouse
-        app.kubernetes.io/component: database
-        app.kubernetes.io/part-of: plausible
-    spec:
-      restartPolicy: Always
-      # see https://github.com/ClickHouse/ClickHouse/blob/master/docker/server/Dockerfile
-      securityContext:
-        runAsUser: 101
-        runAsGroup: 101
-        fsGroup: 101
-      containers:
-        - name: plausible-events-db
-          image: yandex/clickhouse-server:latest
-          imagePullPolicy: Always
-          ports:
-            - containerPort: 8123
-          volumeMounts:
-            - name: data
-              mountPath: /var/lib/clickhouse
-            - name: config
-              mountPath: /etc/clickhouse-server/config.d/logging.xml
-              subPath: clickhouse-config.xml
-              readOnly: true
-            - name: config
-              mountPath: /etc/clickhouse-server/users.d/logging.xml"
-              subPath: clickhouse-user-config.xml
-              readOnly: true
-          env:
-            - name: CLICKHOUSE_DB
-              value: plausible
-            - name: CLICKHOUSE_USER
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-events-db-user
-                  key: username
-            - name: CLICKHOUSE_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-events-db-user
-                  key: password
-          securityContext:
-            allowPrivilegeEscalation: false
-          resources:
-            limits:
-              memory: 2Gi
-              cpu: 1500m
-            requests:
-              memory: 80Mi
-              cpu: 10m
-          readinessProbe:
-            httpGet:
-              path: /ping
-              port: 8123
-            initialDelaySeconds: 20
-            failureThreshold: 6
-            periodSeconds: 10
-          livenessProbe:
-            httpGet:
-              path: /ping
-              port: 8123
-            initialDelaySeconds: 30
-            failureThreshold: 3
-            periodSeconds: 10
-      volumes:
-        - name: config
-          configMap:
-            name: plausible-events-db-config
-  volumeClaimTemplates:
-    - metadata:
-        name: data
-        labels:
-          app.kubernetes.io/name: clickhouse
-          app.kubernetes.io/component: database
-          app.kubernetes.io/part-of: plausible
-      spec:
-        accessModes: ["ReadWriteOnce"]
-        resources:
-          requests:
-            storage: 128Mi
-          limits:
-            storage: 20Gi

kubernetes/plausible-mail.yaml

@@ -1,70 +0,0 @@
-apiVersion: v1
-kind: Service
-metadata:
-  name: plausible-smtp
-  labels:
-    app.kubernetes.io/name: smtp
-    app.kubernetes.io/component: email
-    app.kubernetes.io/part-of: plausible
-spec:
-  type: ClusterIP
-  ports:
-    - name: smtp
-      port: 25
-      targetPort: 25
-      protocol: TCP
-  selector:
-    app.kubernetes.io/name: smtp
-    app.kubernetes.io/component: email
-    app.kubernetes.io/part-of: plausible
----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: plausible-smtp
-  labels:
-    app.kubernetes.io/name: smtp
-    app.kubernetes.io/component: email
-    app.kubernetes.io/part-of: plausible
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: smtp
-      app.kubernetes.io/component: email
-      app.kubernetes.io/part-of: plausible
-  template:
-    metadata:
-      labels:
-        app.kubernetes.io/name: smtp
-        app.kubernetes.io/component: email
-        app.kubernetes.io/part-of: plausible
-    spec:
-      restartPolicy: Always
-      containers:
-        - name: plausible-smtp
-          image: bytemark/smtp:latest
-          imagePullPolicy: Always
-          ports:
-            - containerPort: 25
-          securityContext:
-            allowPrivilegeEscalation: false
-          resources:
-            limits:
-              memory: 512Mi
-              cpu: 500m
-            requests:
-              memory: 5Mi
-              cpu: 1m
-          readinessProbe:
-            tcpSocket:
-              port: 25
-            initialDelaySeconds: 20
-            failureThreshold: 6
-            periodSeconds: 10
-          livenessProbe:
-            tcpSocket:
-              port: 25
-            initialDelaySeconds: 30
-            failureThreshold: 3
-            periodSeconds: 10

kubernetes/plausible.yaml

@@ -1,150 +0,0 @@
-apiVersion: v1
-kind: Service
-metadata:
-  name: plausible
-  labels:
-    app.kubernetes.io/name: plausible
-    app.kubernetes.io/component: server
-spec:
-  type: LoadBalancer
-  ports:
-    - name: http
-      port: 8000
-      targetPort: 8000
-      protocol: TCP
-  selector:
-    app.kubernetes.io/name: plausible
-    app.kubernetes.io/component: server
----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: plausible
-  labels:
-    app.kubernetes.io/name: plausible
-    app.kubernetes.io/component: server
-spec:
-  # Plausible is not currently designed to run in a clustered scenario. Increasing the replicas of this deployment is highly NOT recommended!
-  replicas: 1
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: plausible
-      app.kubernetes.io/component: server
-  template:
-    metadata:
-      labels:
-        app.kubernetes.io/name: plausible
-        app.kubernetes.io/component: server
-    spec:
-      restartPolicy: Always
-      # see https://github.com/plausible/analytics/blob/master/Dockerfile
-      securityContext:
-        runAsUser: 1000
-        runAsGroup: 1000
-        fsGroup: 1000
-      initContainers:
-        - name: plausible-init
-          image: plausible/analytics:latest
-          command:
-            - "/bin/sh"
-            - "-c"
-          args:
-            - sleep 30 && /entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh db init-admin
-          envFrom:
-            - secretRef:
-                name: plausible-config
-          env:
-            - name: POSTGRES_USER
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-db-user
-                  key: username
-            - name: POSTGRES_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-db-user
-                  key: password
-            - name: CLICKHOUSE_USER
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-events-db-user
-                  key: username
-            - name: CLICKHOUSE_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-events-db-user
-                  key: password
-            - name: DATABASE_URL
-              value: postgres://$(POSTGRES_USER):$(POSTGRES_PASSWORD)@$(PLAUSIBLE_DB_SERVICE_HOST):$(PLAUSIBLE_DB_SERVICE_PORT)/plausible
-            - name: CLICKHOUSE_DATABASE_URL
-              value: http://$(CLICKHOUSE_USER):$(CLICKHOUSE_PASSWORD)@$(PLAUSIBLE_EVENTS_DB_SERVICE_HOST):$(PLAUSIBLE_EVENTS_DB_SERVICE_PORT)/plausible
-            - name: SMTP_HOST_ADDR
-              value: $(PLAUSIBLE_SMTP_SERVICE_HOST)
-          securityContext:
-            allowPrivilegeEscalation: false
-          resources:
-            limits:
-              memory: 2Gi
-              cpu: 1500m
-            requests:
-              memory: 50Mi
-              cpu: 10m
-      containers:
-        - name: plausible
-          image: plausible/analytics:latest
-          imagePullPolicy: Always
-          ports:
-            - containerPort: 8000
-          envFrom:
-            - secretRef:
-                name: plausible-config
-          env:
-            - name: POSTGRES_USER
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-db-user
-                  key: username
-            - name: POSTGRES_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-db-user
-                  key: password
-            - name: CLICKHOUSE_USER
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-events-db-user
-                  key: username
-            - name: CLICKHOUSE_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: plausible-events-db-user
-                  key: password
-            - name: DATABASE_URL
-              value: postgres://$(POSTGRES_USER):$(POSTGRES_PASSWORD)@$(PLAUSIBLE_DB_SERVICE_HOST):$(PLAUSIBLE_DB_SERVICE_PORT)/plausible
-            - name: CLICKHOUSE_DATABASE_URL
-              value: http://$(CLICKHOUSE_USER):$(CLICKHOUSE_PASSWORD)@$(PLAUSIBLE_EVENTS_DB_SERVICE_HOST):$(PLAUSIBLE_EVENTS_DB_SERVICE_PORT)/plausible
-            - name: SMTP_HOST_ADDR
-              value: $(PLAUSIBLE_SMTP_SERVICE_HOST)
-          securityContext:
-            allowPrivilegeEscalation: false
-          resources:
-            limits:
-              memory: 2Gi
-              cpu: 1500m
-            requests:
-              memory: 140Mi
-              cpu: 10m
-          readinessProbe:
-            httpGet:
-              path: /api/health
-              port: 8000
-            initialDelaySeconds: 35
-            failureThreshold: 6
-            periodSeconds: 10
-          livenessProbe:
-            httpGet:
-              path: /api/health
-              port: 8000
-            initialDelaySeconds: 45
-            failureThreshold: 3
-            periodSeconds: 10

plausible-conf.env

@@ -1,5 +1,3 @@
-ADMIN_USER_EMAIL=replace-me
-ADMIN_USER_NAME=replace-me
-ADMIN_USER_PWD=replace-me
 BASE_URL=replace-me
 SECRET_KEY_BASE=replace-me
+TOTP_VAULT_KEY=replace-me

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/apache2/plausible.conf

@@ -4,6 +4,8 @@
  ServerName example.com
 
  ProxyPreserveHost On
+ ProxyAddHeaders On
+ ProxyPassMatch ^/(live/websocket)$  ws://localhost:8000/$1
  ProxyPass / http://localhost:8000/
  ProxyPassReverse / http://localhost:8000/
 

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";
+		}
 	}
 }

upgrade/postgres.md

@@ -0,0 +1,159 @@
+Guide to upgrading PostgreSQL version `>= 12` to version `14` using `pg_dump` and `psql`. Based on [Upgrade a PostgreSQL database with docker.](https://hollo.me/devops/upgrade-postgresql-database-with-docker.html)
+
+**Note:** following this guide you'd need to stop some containers and it would make your plausible instance temporarily unavailable.
+
+---
+
+### Plan
+
+1. dump contents of the old version PostgreSQL to a file
+1. copy the dump to the host
+1. replace old version PostgreSQL with new version PostgreSQL
+1. copy and load the dump into new version PostgreSQL
+
+---
+
+### Steps
+
+1. Stop `plausible` to avoid writing to old `plausible_db`
+
+```console
+> docker compose stop plausible
+[+] Running 2/2
+ ⠿ Container hosting-plausible-1     Stopped           6.5s
+```
+
+2. Dump old `plausible_db` contents to a backup file
+
+```console
+> docker compose exec plausible_db sh -c "pg_dump -U postgres plausible_db > plausible_db.bak"
+```
+
+3. Copy the backup to the host
+
+```console
+> docker compose cp plausible_db:plausible_db.bak plausible_db.bak
+```
+
+4. (Optional) verify backup went OK
+
+```console
+> head plausible_db.bak
+--
+-- PostgreSQL database dump
+--
+
+-- Dumped from database version 12.12 (Debian 12.12-1.pgdg110+1)
+-- Dumped by pg_dump version 12.12 (Debian 12.12-1.pgdg110+1)
+
+SET statement_timeout = 0;
+SET lock_timeout = 0;
+SET idle_in_transaction_session_timeout = 0;
+```
+
+5. Edit `docker-compose.yml` to use new PostgreSQL version, here we update from `v12` to `v14`, alpine flavour.
+
+```diff
+  plausible_db:
+-   image: postgres:12
++   image: postgres:14-alpine
+    restart: always
+    volumes:
+      - db-data:/var/lib/postgresql/data
+    environment:
+      - POSTGRES_PASSWORD=postgres
+```
+
+6. Ensure relevant containers are stopped
+
+```console
+> docker compose stop plausible plausible_db
+[+] Running 2/2
+ ⠿ Container hosting-plausible-1     Stopped           0.0s
+ ⠿ Container hosting-plausible_db-1  Stopped           0.2s
+```
+
+7. Remove old `plausible_db` container to be able to nuke its volume in the next step
+
+```console
+> docker compose rm plausible_db
+? Going to remove hosting-plausible_db-1 Yes
+[+] Running 1/0
+ ⠿ Container hosting-plausible_db-1  Removed           0.0s
+```
+
+8. Remove old `plausible_db` volume, mine is named `hosting_db-data`
+
+```console
+> docker volume ls
+DRIVER    VOLUME NAME
+<...snip...>
+local     hosting_db-data
+local     hosting_event-data
+<...snip...>
+
+> docker volume rm hosting_db-data
+hosting_db-data
+```
+
+9. Start new version `plausible_db` container
+
+```console
+> docker compose up plausible_db -d
+[+] Running 9/9
+ ⠿ plausible_db Pulled                                 9.3s
+   ⠿ 9b18e9b68314 Already exists                       0.0s
+   ⠿ 75aada9edfc5 Pull complete                        1.2s
+   ⠿ 820773693750 Pull complete                        1.2s
+   ⠿ 8812bb04ef2e Pull complete                        5.2s
+   ⠿ 2ccec0f7805c Pull complete                        5.2s
+   ⠿ 833f9b98598e Pull complete                        5.3s
+   ⠿ 1eb578dc04e6 Pull complete                        5.4s
+   ⠿ c873bf6204df Pull complete                        5.4s
+[+] Running 2/2
+ ⠿ Volume "hosting_db-data"          Created           0.0s
+ ⠿ Container hosting-plausible_db-1  Started           0.5s
+```
+
+10. Create new DB and load data into it
+
+```console
+> docker compose exec plausible_db createdb -U postgres plausible_db
+> docker compose cp plausible_db.bak plausible_db:plausible_db.bak
+
+> docker compose exec plausible_db sh -c "psql -U postgres -d plausible_db < plausible_db.bak"
+SET
+SET
+SET
+SET
+SET
+ set_config
+------------
+
+(1 row)
+
+SET
+SET
+SET
+SET
+CREATE EXTENSION
+<...snip...>
+```
+
+11. Start all other containers
+
+```console
+> docker compose up -d
+[+] Running 4/4
+ ⠿ Container hosting-plausible_events_db-1  Running           0.0s
+ ⠿ Container hosting-mail-1                 Running           0.0s
+ ⠿ Container hosting-plausible_db-1         Started           0.5s
+ ⠿ Container hosting-plausible-1            Started           0.5s
+```
+
+12. (Optional) Remove backups from the container and the host
+
+```console
+> rm plausible_db.bak
+> docker compose exec plausible_db rm plausible_db.bak
+```