diff --git a/README.md b/README.md index fc956d5..f3b3b47 100644 --- a/README.md +++ b/README.md @@ -10,3 +10,7 @@ Find instructions on how to run Plausible Analytics Self Hosted [in our docs](ht We are always looking to expand on the options and setups provided here. Feel free to open an issue or PR if you feel something could be improved. + +### Upgrade guides + +- [Upgrading `plausible_db` (PostgreSQL)](upgrade/postgres.md) diff --git a/docker-compose.yml b/docker-compose.yml index a95a18e..afa2c42 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -5,6 +5,7 @@ services: restart: always plausible_db: + # supported versions are 12, 13, and 14 image: postgres:14-alpine restart: always volumes: diff --git a/kubernetes/plausible-db.yaml b/kubernetes/plausible-db.yaml index f1353d1..04c6411 100644 --- a/kubernetes/plausible-db.yaml +++ b/kubernetes/plausible-db.yaml @@ -49,6 +49,7 @@ spec: fsGroup: 999 containers: - name: plausible-db + # supported versions are 12, 13, and 14 image: postgres:latest imagePullPolicy: Always ports: diff --git a/upgrade/postgres.md b/upgrade/postgres.md new file mode 100644 index 0000000..448b5ca --- /dev/null +++ b/upgrade/postgres.md @@ -0,0 +1,187 @@ +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 in a mounted volume +1. replace old version PostgreSQL with new version PostgreSQL +1. load dump from the mounted volume into new version PostgreSQL + +--- + +### Steps + +1. Add a backup volume to `plausible_db` in your `docker-compose.yml` + +```diff + plausible_db: + image: postgres:12 + restart: always + volumes: + - db-data:/var/lib/postgresql/data ++ - ./backup:/backup + environment: + - POSTGRES_PASSWORD=postgres +``` + +2. Stop relevant containers to avoid writing to old `plausible_db` + +```console +> docker compose stop plausible plausible_db +[+] Running 2/2 + ⠿ Container hosting-plausible-1 Stopped 6.5s + ⠿ Container hosting-plausible_db-1 Stopped 0.2s +``` + +3. Restart `plausible_db` container to attach volume + +```console +> docker compose up plausible_db -d +[+] Running 1/1 + ⠿ Container hosting-plausible_db-1 Started 0.3s +``` + +4. Dump old `plausible_db` contents to a backup file + +```console +> docker compose exec plausible_db sh -c "pg_dump -U postgres plausible_db > /backup/plausible_db.bak" +``` + +5. (Optional) verify backup went OK + +```console +> ls backup +plausible_db.bak + +> head backup/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; +``` + +6. 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 + - ./backup:/backup + environment: + - POSTGRES_PASSWORD=postgres +``` + +7. 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 +``` + +8. 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 +``` + +9. 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 +``` + +10. 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 +``` + +11. Create new DB and load data into it + +```console +> docker compose exec plausible_db createdb -U postgres plausible_db + +> docker compose exec plausible_db sh -c "psql -U postgres -d plausible_db < /backup/plausible_db.bak" +SET +SET +SET +SET +SET + set_config +------------ + +(1 row) + +SET +SET +SET +SET +CREATE EXTENSION +<...snip...> +``` + +12. 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 +``` + +13. (Optional) Remove backups from `docker-compose.yml` and your filesystem + +```diff + plausible_db: + image: postgres:14-alpine + restart: always + volumes: + - db-data:/var/lib/postgresql/data +- - ./backup:/backup + environment: + - POSTGRES_PASSWORD=postgres +``` + +``` +> rm -rf ./backup +```