Merge pull request #341 from kobotoolbox/fix-postgresql-doc-upgrade

Update PostgreSQL upgrade documentation
kobotoolbox · Nov 17, 2022 · 8a85816 · 8a85816
2 parents 16832bb + e0ab14a
commit 8a85816
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 16 deletions.
diff --git 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 `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)
@@ -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 [`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/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 → doc/November-2022-Upgrade.md b/doc/May-2022-Upgrade.md → doc/November-2022-Upgrade.md
@@ -1,10 +1,10 @@
-## Upgrading from an old version of kobo-docker (before May 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).
@@ -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 and continue. When asked about configuration files, choose `install the package maintainer's version`._
+
 1. Initialize the database
 
     ```shell
@@ -158,7 +170,7 @@ 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"`)._
     
     ```
     CREATE EXTENSION IF NOT EXISTS postgis;
@@ -256,6 +268,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 +378,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 +601,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 +614,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 +647,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 +660,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 +672,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