KoBo software upgrade

Step by step how-to instructions on installing and running KoBo Toolbox on a standalone server.
Jump to: navigation, search

You should perform the upgrade tasks, laid out in following two sections, in sequence and in the same session. During the upgrade session, system will be inaccessible at times. Please make sure that users are properly notified about the service down-time beforehand.

Updating kobo-docker

Your kobo-docker folder shoul be nearly identical to the source Git repository at the time of your KoBo ToolBox Setup (or the previous update). The only changed files should be the configurations.

Configuration files need your special attention during the upgrade. Our versions contain necessary parameters for the Toolbox to operate; new versions coming from the repository might have new (or different!) options that go together with the updated code. Yet the repository version is blank, so we cannot just take the new versions, or the old versions. We need to merge the new settings from new config files, coming from the repo, into our versions of config files.

Configuration files are critical for KoBo operation, so we are performing a manual merge by (good old) looking, copying and pasting. We will use git diff to establish the differences between versions of the same file.

Change to kobo-docker directory, and establish which files have been changed

$ cd $KOBO_DOCKER
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   docker-compose.server.yml
        modified:   envfile.server.txt
        modified:   envfiles/external_services.txt
        modified:   envfiles/smtp.txt

All the configuration files that you edited during setup are on the modified list. We will now use git to stash those changes away for the moment, update kobo-docker via git pull and finally return our config files from the stash.

$ git stash save
$ git pull
$ git stash pop

Now our config files are back in position, and we need to check differences and incorporate new stuff. IMPORTANT: carry out the following process for all the files that git status lists as modified.

Differencces between our config file and the *updated* (but blank) config file can now be reviewed with

$  git diff --no-ext-diff envfiles/external_services.txt
diff --git a/envfiles/external_services.txt b/envfiles/external_services.txt
index ce2650f..7d30e16 100644
--- a/envfiles/external_services.txt
+++ b/envfiles/external_services.txt
@@ -1,3 +1,2 @@
-#GOOGLE_ANALYTICS_TOKEN=
+GOOGLE_ANALYTICS_TOKEN=UA-89355929-1
 #RAVEN_DSN=
-#TRACKJS_TOKEN=

The output precisely describes where and what the differences are, but can be difficult to read. Iterpreted to simple English, the output would be: we un-commented the Analytics line, and added the property info to it, the Raven line has been introduced in the new version of the file.

Reading git diff output directly, as fun as it may sound, is not entirely necessary. If you prefer a more visual comparison, please proceed to...

Showing side-by-side differences with git

We will use sdiff to display git differences. The following command will create a git wrapper for sdiff, please make sure to paste it as a single line:

$ D=/usr/bin/git-sdiff && echo -e '#!/bin/bash' "\n/usr/bin/sdiff -w160 -l \"\$2\" \"\$5\"" | sudo dd status=none of=$D && sudo chown root:root $D && sudo chmod 0755 $D && ls -l $D

...if successful outputs:

-rwxr-xr-x 1 root root 48 Dec 01 11:34 /usr/bin/git-sdiff

To enable git-sdiff on a project level

$ cd $KOBO_DOCKER
$ git config diff.external git-sdiff 

To enable sdiff on an user level

$ git config --global diff.external git-sdiff

Now try comparing the configuration files side-by-side:

$ git diff envfiles/smtp.txt
#GOOGLE_ANALYTICS_TOKEN=                                      | GOOGLE_ANALYTICS_TOKEN=UA-89355929-1
#RAVEN_DSN=                                                   (
#TRACKJS_TOKEN=                                               <

Much easier to read, is it not? The new configuration file is shown in the left column line by line; the differences are in the right one; and a symbol between columns indicates what happened with that line. The <code>sdiff</code> notation, as shown in the output example above:

symbol denotes example required action
| the line which we changed, and the change is displayed to the right first line none
( the line identical in both files, nothing is displayed to the right second line none
< the line added in the new version third line merge into the file
> the line removed in the new version (not shown) remove from the file

When merging and removing items, be sure to understand your actions. Incorrect configuration can prevent the Toolbox from starting.

Back to git diff; to get standard git diff output anyway:

$ git diff --no-ext-diff envfiles/smtp.txt

Updating images

Please complete the previous step, Updating kobo-docker, before carrying on.

We will stop and remove KoBo containers, pull the updates and bring the system back up.

$ cd $KOBO_DOCKER
$ sudo docker-compose stop
$ sudo docker-compose rm
$ sudo docker-compose pull
$ sudo docker-compose up -d

KoBo Toolbox is now upgraded to the latest release. You might want to glance at log messages as varous services are coming up:

$ sudo docker-compose logs -f
 238  sudo docker exec -it kobodocker_kobocat_1 bash
 239  sudo docker exec -it kobodocker_kpi_1 bash

Enketo Express specific update Jan 2018

In order to upgrade to latest EE image available, set the version in compose file:

$ cd $KOBO_DOCKER
$ sudo nano docker-compose.server.yml
enketo_express:
  image: kobotoolbox/enketo-express-extra-widgets:1.57.0

...and then follow through the previous section Updating images.