Difference between revisions of "KoBo software upgrade"

Step by step how-to instructions on installing and running KoBo Toolbox on a standalone server.
Jump to: navigation, search
m
(Tag: visualeditor)
m
(Tag: visualeditor)
Line 23: Line 23:
 
         modified:  envfiles/smtp.txt</pre></blockquote>
 
         modified:  envfiles/smtp.txt</pre></blockquote>
  
All the configuration files that you edited previously are, obviously, modified. 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.
+
All the configuration files that you edited during setup are on the modified list. We will now use <code>git</code> 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 stash save
 
  $ git pull
 
  $ git pull
Line 65: Line 65:
 
#TRACKJS_TOKEN=                                              &lt;</pre></blockquote>
 
#TRACKJS_TOKEN=                                              &lt;</pre></blockquote>
  
Much easier to read, is it not? The new configuration file is shown in the left column, while the differences are indicated to the right. We un-commented the Analytics line adding the property info, while the Raven line has been introduced in the fresh version of the file. Please take note of the sdiff notation in the output example above:
+
Much easier to read, is it not? The new configuration file is shown in the left column, while the differences are indicated to the right; a symbol between the columns indicates what happened in that line We un-commented the Analytics line adding the property info, while the Raven line has been introduced in the fresh version of the file. The <nowiki><code>sdiff</code></nowiki> notation in the output example above:
 
{| class="wikitable"
 
{| class="wikitable"
 
!symbol
 
!symbol
 
!denotes
 
!denotes
 
!example
 
!example
 +
!required action
 
|-
 
|-
 
| style="text-align:center;" | '''<nowiki>|</nowiki>'''
 
| style="text-align:center;" | '''<nowiki>|</nowiki>'''
|the line that we changed, and the change is displayed to the right
+
|the line which we changed, and the change is displayed to the right
 
|first line
 
|first line
 +
|none
 
|-
 
|-
 
| style="text-align:center;" | '''('''
 
| style="text-align:center;" | '''('''
|he line identical in both files
+
|the line identical in both files
 
|second line
 
|second line
 +
|none
 
|-
 
|-
 
| style="text-align:center;" | '''&lt;'''
 
| style="text-align:center;" | '''&lt;'''
|the line *added in the new version*, which you should manually incorporate into the file
+
|the line ''added'' in the new version
 
|third line
 
|third line
 +
|merge into the file
 
|-
 
|-
 
| style="text-align:center;" | '''&gt;'''
 
| style="text-align:center;" | '''&gt;'''
|the line *removed in the new version*, which you should manually remove from the file
+
|the line ''removed'' in the new version
 
|(not shown)
 
|(not shown)
 +
|remove from the file
 
|}
 
|}
  
To get standard git diff output anyway:
+
When merging and removing items, be sure to understand your actions. Incorrect configuration can prevent the Toolbox from starting.
 +
 
 +
Back to <nowiki><code>git diff</code></nowiki>To get standard git diff output anyway:
 
  $ git diff --no-ext-diff envfiles/smtp.txt
 
  $ git diff --no-ext-diff envfiles/smtp.txt
 
After carefully reviewing each file in the modified list, pleace proceed to...
 
After carefully reviewing each file in the modified list, pleace proceed to...

Revision as of 02:01, 23 December 2016

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 are the differences, but can be difficult to read. To get a visually comprehendable comparison, continue 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 22 21: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, while the differences are indicated to the right; a symbol between the columns indicates what happened in that line We un-commented the Analytics line adding the property info, while the Raven line has been introduced in the fresh version of the file. The <code>sdiff</code> notation 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 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 <code>git diff</code>To get standard git diff output anyway:

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

After carefully reviewing each file in the modified list, pleace proceed to...

Updating images

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


 238  sudo docker exec -it kobodocker_kobocat_1 bash
 239  sudo docker exec -it kobodocker_kpi_1 bash