KoBo software upgrade
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.
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.
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:
||||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.
git diff; to get standard git diff output anyway:
$ git diff --no-ext-diff envfiles/smtp.txt
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.