From 1827d82ec42f59951b094249af46682a743e5318 Mon Sep 17 00:00:00 2001 From: Olivier Leger Date: Thu, 17 Nov 2022 14:58:35 -0500 Subject: [PATCH 1/4] Update PostgreSQL documentation upgrade --- .gitignore | 1 + README.md | 6 +-- ...22-Upgrade.md => November-2022-Upgrade.md} | 41 ++++++++++++++----- 3 files changed, 34 insertions(+), 14 deletions(-) rename doc/{May-2022-Upgrade.md => November-2022-Upgrade.md} (92%) diff --git a/.gitignore b/.gitignore index 3976817e..5d259a00 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,4 @@ start-env.sh stop-env.sh nginx/maintenance/index.html .uniqid +.DS_Store diff --git a/README.md b/README.md index eac40497..9ed3408e 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ 1. [Introduction](#introduction) 1. [_Two PostgreSQL databases are now required_](#two-postgresql-databases-are-now-required) 1. [Important notice when upgrading from commit `5c2ef02` (March 4, 2019) or earlier](#important-notice-when-upgrading-from-commit-5c2ef02-march-4-2019-or-earlier) -1. [Important notice when upgrading from commit between `51aeccb` (March 11, 2019) and `TBC` (May XX, 2022)](#important-notice-when-upgrading-from-commit-between-51aeccb-march-11-2019-and-tbc-may-xx-2022) +1. [Important notice when upgrading from commit between `51aeccb` (March 11, 2019) and `TBC` (November 17, 2022)](#important-notice-when-upgrading-from-commit-between-51aeccb-march-11-2019-and-tbc-november-17-2022) 1. [Architecture](#architecture) 1. [Setup procedure](#setup-procedure) 1. [Usage](#usage) @@ -38,9 +38,9 @@ Running current releases of KoboToolbox requires you to upgrade your PostgreSQL If you do not, the application may not start or your data may not be visible. -## Important notice when upgrading from commit between [`51aeccb` (March 11, 2019)](https://github.com/kobotoolbox/kobo-docker/commit/51aeccb91316d640f30e28190b936ae48d56c468) and [`TBC` (May XX, 2022)]() +## Important notice when upgrading from commit between [`51aeccb` (March 11, 2019)](https://github.com/kobotoolbox/kobo-docker/commit/51aeccb91316d640f30e28190b936ae48d56c468) and [`TBC` (November 17, 2022)]() -Running current releases of KoboToolbox requires you to upgrade your PostgreSQL and MongoDB databases. Please follow [these instructions](./doc/May-2022-Upgrade.md). +Running current releases of KoboToolbox requires you to upgrade your PostgreSQL and MongoDB databases. Please follow [these instructions](./doc/November-2022-Upgrade.md). If you do not, the application may not start or your data may not be visible. diff --git a/doc/May-2022-Upgrade.md b/doc/November-2022-Upgrade.md similarity index 92% rename from doc/May-2022-Upgrade.md rename to doc/November-2022-Upgrade.md index bac9c9c3..5c7c0f28 100644 --- a/doc/May-2022-Upgrade.md +++ b/doc/November-2022-Upgrade.md @@ -1,4 +1,4 @@ -## Upgrading from an old version of kobo-docker (before May 2022) +## Upgrading from an old version of kobo-docker (before November 2022) Current versions of kobo-docker require PostgreSQL 14, MongoDB 5 and Redis 6 @@ -21,12 +21,12 @@ Check the size of the PostgreSQL database in `.vols/db`, e.g. with free. For this tutorial, we are using kobo-install to run docker-compose commands. -If you do not use kobo-install, please replace `python run.py -cb` with `docker-compose -f docker-compose.primary.backend.template.yml -f docker-compose.primary.backend.yml [-f docker-compose.primary.backend.override.yml] [-f docker-compose.primary.backend.custom.yml]` +If you do not use kobo-install, please replace `python3 run.py -cb` with `docker-compose -f docker-compose.primary.backend.template.yml -f docker-compose.primary.backend.yml [-f docker-compose.primary.backend.override.yml] [-f docker-compose.primary.backend.custom.yml]` 1. Stop the containers ```shell - user@computer:kobo-install$ python run.py --stop + user@computer:kobo-install$ python3 run.py --stop ``` 1. Edit composer file `docker-compose.primary.backend.template.yml` @@ -71,11 +71,21 @@ If you do not use kobo-install, please replace `python run.py -cb` with `docker- 1. Run a one-off `PostgreSQL` container ```shell - user@computer:kobo-install$ python run.py -cb run --rm postgres bash + user@computer:kobo-install$ python3 run.py -cb run --rm postgres bash ``` 1. Install PostgreSQL 14 + ```shell + root@postgres:/# apt-get install apt-transport-https ca-certificates + ``` + + ```shell + root@postgres:/# rm -rf /etc/apt/sources.list.d/pgdg.list && \ + echo "deb https://apt-archive.postgresql.org/pub/repos/apt stretch-pgdg-archive main" >> /etc/apt/sources.list && \ + echo "deb-src https://apt-archive.postgresql.org/pub/repos/apt stretch-pgdg-archive main" >> /etc/apt/sources.list + ``` + ```shell root@postgres:/# apt-get update && \ apt-cache policy postgresql-14-postgis-3 && \ @@ -90,6 +100,8 @@ If you do not use kobo-install, please replace `python run.py -cb` with `docker- apt-get upgrade ``` + _Notes: You may receive a (long) warning that PostgreSQL 9.5 is obsolete, ignore it, continue and use new version config files when asked for._ + 1. Initialize the database ```shell @@ -158,7 +170,8 @@ If you do not use kobo-install, please replace `python run.py -cb` with `docker- Depending on your kobo-docker environment, databases may have other names. You may need to adapt the snippet below to your current configuration. - _Notes: You may need to copy lines below one by one because sometimes copying the whole block does not work as expected._ + _Notes: You may need to copy lines below one by one because sometimes copying the whole block does not work as expected (e.g.: error like **invalid integer value "postgis" for connection option "port" +Previous connection kept**)._ ``` CREATE EXTENSION IF NOT EXISTS postgis; @@ -256,6 +269,12 @@ If you do not use kobo-install, please replace `python run.py -cb` with `docker- > Upgrade Complete > --------------- > ``` + + You can exit the one-off container + + ```shell + root@postgres:/# exit + ``` 1. Edit composer file `docker-compose.backend.template.yml` again @@ -360,7 +379,7 @@ Please note that MongoDB [recommends using an XFS partition](https://www.mongodb To validate if your MongoDB instance is using the correct engine, run this command. ```shell - user@computer:kobo-install$ python run.py --cb exec mongo bash + user@computer:kobo-install$ python3 run.py -cb exec mongo bash root@mongo:/# mongo -u "$MONGO_INITDB_ROOT_USERNAME" -p "$MONGO_INITDB_ROOT_PASSWORD" admin > db.serverStatus().storageEngine ``` @@ -583,7 +602,7 @@ Please note that MongoDB [recommends using an XFS partition](https://www.mongodb 1. Stop `mongo` container ```shell - user@computer:kobo-install$ python run.py --cb stop mongo + user@computer:kobo-install$ python3 run.py -cb stop mongo ``` 1. Edit composer file `docker-compose.primary.backend.template.yml` and change image to `mongo:3.6` @@ -596,7 +615,7 @@ Please note that MongoDB [recommends using an XFS partition](https://www.mongodb 1. Start the container: ```shell - user@computer:kobo-install$ python run.py --cb up --force-recreate mongo + user@computer:kobo-install$ python3 run.py -cb up --force-recreate mongo ``` 1. Wait for MongoDB to be ready. You should see in the console the output below: @@ -629,7 +648,7 @@ Please note that MongoDB [recommends using an XFS partition](https://www.mongodb Then start the container: ```shell - user@computer:kobo-install$ python run.py --cb up -d --force-recreate mongo + user@computer:kobo-install$ python3 run.py -cb up -d --force-recreate mongo ``` Done! @@ -642,7 +661,7 @@ Please note that MongoDB [recommends using an XFS partition](https://www.mongodb Start your containers as usual. ```shell - user@computer:kobo-install$ python run.py + user@computer:kobo-install$ python3 run.py ``` Log into one of your user accounts and validate everything is working as expected. @@ -654,7 +673,7 @@ Please note that MongoDB [recommends using an XFS partition](https://www.mongodb 1. Stop containers ```shell - user@computer:kobo-install$ python run.py --stop + user@computer:kobo-install$ python3 run.py --stop ``` 1. Rename folder From b72c5fc60a9f800e639f74f21077925f15ba8502 Mon Sep 17 00:00:00 2001 From: "John N. Milner" Date: Thu, 17 Nov 2022 16:36:25 -0500 Subject: [PATCH 2/4] Make a few small edits --- doc/November-2022-Upgrade.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/November-2022-Upgrade.md b/doc/November-2022-Upgrade.md index 5c7c0f28..ca5d83dd 100644 --- a/doc/November-2022-Upgrade.md +++ b/doc/November-2022-Upgrade.md @@ -100,7 +100,7 @@ If you do not use kobo-install, please replace `python3 run.py -cb` with `docker apt-get upgrade ``` - _Notes: You may receive a (long) warning that PostgreSQL 9.5 is obsolete, ignore it, continue and use new version config files when asked for._ + _Notes: You may receive a (long) warning that PostgreSQL 9.5 is obsolete: ignore it and continue. When asked about configuration files, choose `install the package maintainer's version`._ 1. Initialize the database @@ -170,8 +170,7 @@ If you do not use kobo-install, please replace `python3 run.py -cb` with `docker Depending on your kobo-docker environment, databases may have other names. You may need to adapt the snippet below to your current configuration. - _Notes: You may need to copy lines below one by one because sometimes copying the whole block does not work as expected (e.g.: error like **invalid integer value "postgis" for connection option "port" -Previous connection kept**)._ + _Notes: You may need to copy lines below one by one because sometimes copying the whole block does not work as expected (e.g.: error like `invalid integer value "postgis" for connection option "port"`)._ ``` CREATE EXTENSION IF NOT EXISTS postgis; From 9ab13d6bd616c1e3fa08a36c0253aff87aa4fa99 Mon Sep 17 00:00:00 2001 From: "John N. Milner" Date: Thu, 17 Nov 2022 16:42:59 -0500 Subject: [PATCH 3/4] Change TBC to 2.022.44 --- README.md | 4 ++-- doc/November-2022-Upgrade.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9ed3408e..52d8f5c3 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ 1. [Introduction](#introduction) 1. [_Two PostgreSQL databases are now required_](#two-postgresql-databases-are-now-required) 1. [Important notice when upgrading from commit `5c2ef02` (March 4, 2019) or earlier](#important-notice-when-upgrading-from-commit-5c2ef02-march-4-2019-or-earlier) -1. [Important notice when upgrading from commit between `51aeccb` (March 11, 2019) and `TBC` (November 17, 2022)](#important-notice-when-upgrading-from-commit-between-51aeccb-march-11-2019-and-tbc-november-17-2022) +1. [Important notice when upgrading from commit between `51aeccb` (March 11, 2019) and `2.022.44` (November 17, 2022)](#important-notice-when-upgrading-from-commit-between-51aeccb-march-11-2019-and-2.022.44-november-17-2022) 1. [Architecture](#architecture) 1. [Setup procedure](#setup-procedure) 1. [Usage](#usage) @@ -38,7 +38,7 @@ Running current releases of KoboToolbox requires you to upgrade your PostgreSQL If you do not, the application may not start or your data may not be visible. -## Important notice when upgrading from commit between [`51aeccb` (March 11, 2019)](https://github.com/kobotoolbox/kobo-docker/commit/51aeccb91316d640f30e28190b936ae48d56c468) and [`TBC` (November 17, 2022)]() +## Important notice when upgrading from commit between [`51aeccb` (March 11, 2019)](https://github.com/kobotoolbox/kobo-docker/commit/51aeccb91316d640f30e28190b936ae48d56c468) and [`2.022.44` (November 17, 2022)](https://github.com/kobotoolbox/kobo-docker/releases/tag/2.022.44) Running current releases of KoboToolbox requires you to upgrade your PostgreSQL and MongoDB databases. Please follow [these instructions](./doc/November-2022-Upgrade.md). diff --git a/doc/November-2022-Upgrade.md b/doc/November-2022-Upgrade.md index ca5d83dd..f1ba3384 100644 --- a/doc/November-2022-Upgrade.md +++ b/doc/November-2022-Upgrade.md @@ -1,10 +1,10 @@ -## Upgrading from an old version of kobo-docker (before November 2022) +## Upgrading from an old version of kobo-docker (before November 17, 2022) -Current versions of kobo-docker require PostgreSQL 14, MongoDB 5 and Redis 6 +Current versions of kobo-docker (release [`2.022.44`](https://github.com/kobotoolbox/kobo-docker/releases/tag/2.022.44) and later) require PostgreSQL 14, MongoDB 5, and Redis 6. If you are running a version of kobo-docker that was last updated prior to -May 2022 (i.e. commit TBC or older), +November 17, 2022 (i.e. older than release [`2.022.44`](https://github.com/kobotoolbox/kobo-docker/releases/tag/2.022.44)), you need to upgrade your databases before using the current version of kobo-docker (this repository) or [kobo-install](https://github.com/kobotoolbox/kobo-install). From e0ab14a45c06fe955bafb861fb52d8eb0a0ae6e1 Mon Sep 17 00:00:00 2001 From: "John N. Milner" Date: Thu, 17 Nov 2022 16:48:27 -0500 Subject: [PATCH 4/4] Match GitHub's anchor naming --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 52d8f5c3..b2dd95dc 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ 1. [Introduction](#introduction) 1. [_Two PostgreSQL databases are now required_](#two-postgresql-databases-are-now-required) 1. [Important notice when upgrading from commit `5c2ef02` (March 4, 2019) or earlier](#important-notice-when-upgrading-from-commit-5c2ef02-march-4-2019-or-earlier) -1. [Important notice when upgrading from commit between `51aeccb` (March 11, 2019) and `2.022.44` (November 17, 2022)](#important-notice-when-upgrading-from-commit-between-51aeccb-march-11-2019-and-2.022.44-november-17-2022) +1. [Important notice when upgrading from commit between `51aeccb` (March 11, 2019) and `2.022.44` (November 17, 2022)](#important-notice-when-upgrading-from-commit-between-51aeccb-march-11-2019-and-202244-november-17-2022) 1. [Architecture](#architecture) 1. [Setup procedure](#setup-procedure) 1. [Usage](#usage)