Dear all,
this thread has the intent to share my experiences and ideas so far, and maybe discuss a better approach (see at the end), and improve xwiki documentation, to maybe help others. I’ve spent quite some time on this topic lately (in total probably 50 hours already)
How do you upgrade xwiki without losing configuration changes?_ (especially when using docker)
Your Guide in Upgrading XWiki (in Docker) says:
Note that your current XWiki configuration files (xwiki.cfg, xwiki.properties and hibernate.cfg.xml) will be preserved.
This is somewhat in contrast to Upgrading the webapp:
The general strategy is to download the new WAR distribution and to replace your current installed WAR with it. […] In addition you would override some XWiki configuration files located in WEB-INF (xwiki.properties and xwiki.cfg to name just two).
(I’ve think I’ve read somewhere about merging the two main configuration files, but can’t find that text atm.)
So basically, when upgrading, you must to merge the existing xwiki.cfg
and xwiki.properties
, because there may be additions, changes or deletions, using a tool like e.g. WinMerge.
Issue #1: The docker upgrade path violates this, because the docker-entrypoint.sh will use the existing old config files in the permanent data docker volume and copy them back over to the new configuration files within the container, essentially losing the new files, because you can’t access them beforehand.
Solution: Start a new docker container with the new xwiki image, so it’s config files are copied into a new docker volume (or access this container with docker exec
). You can then merge these files with your existing one. You could manually download the WAR
file and unzip it’s contents, BUT for docker the hibernate.cfg.xml
is here on github so you have to compare with there…
Issue #2: How do you do all that, without loosing track, running on different systems, containers, docker-compose git repositories and whatnot?
My approach: Using git(hub). We have a in-house github repository where I’ve committed all files where we had to do changes. These are on the master
branch, and tagged with the corresponding xwiki version.
When doing a version upgrade, I create a new branch e.g. 10.7-test
, get all config files of the “vanilla” docker container and paste them in the repository. Then, using e.g. SourceTree, I review all changes in all files, and use Stage hunk or Discard hunks (or line) until everything is merged, and commit and push this to branch 10.7-test
In a xwiki test environment, similar to production, the xwiki data volume contains the git repository. There i checkout branch 10.7-test
, and proceed with stopping the xwiki container and recreating it with the new 10.7 docker image. When it starts, it is now using the already merged configurations.
If all function tests with the new version are satisfactory, I merge 10.7-test
into master
, tag it with version 10.7
and push.
On the xwiki production server, in the xwiki permanent data docker volume, I pull from the master
branch, and repeat the other upgrade steps like on the test environment.
THAT is quite an undertaking, considering we’d like to upgrade more frequently in the future.
Currently I’m managing this, but I want to delegate this to our IT departement (god help me)
If you have any suggestions, tips, etc. on this, it would be greatly appreciated.
Maybe I’m overcomplicating things
I’m currently preparing to switch from xwiki 8.4.3 WAR on tomcat on windows to xwiki 10.8 tomcat-postgres on docker on linux CentOS. It’s a complete new installation where all content will be imported via XAR Export/Import. Wish me luck.
Thank you
BR
Mario