Updating MX to new version
Updating to a new MX release
Thanks to Billy on support forum for suggesting text for this article.
Knowing when a new release is available
Using forum notifications
As new releases are announced in Cumulus MX Announcements and Download - PLEASE READ FIRST topic, you can use the spanner tool to subscribe to this topic to receive notifications of a new post announcing a new release (or any other release-related announcement).
MX installations will output message
If ...
- ...you have a monitor to see the output from the Cumulus MX engine (Windows call this a console window, for Unix-based implementations this is the output window when using terminal), AND
- ...your device running MX is connected to internet, AND
- ...your MONO (if not Windows) is not obsolete (SSL certificate out of date), AND
- ...you restart MX
... then you will see a prompt when a new version is available.
It is worth stressing that if you leave MX running, then this feature will leave you blissfully unaware that an update is available; it only checks when MX is restarted.
MXDiags
In addition ...
- ...if you can view the MXdiags file for the current session of MX, AND
- ... that is running with connection to the internet, AND
- ...you restart MX
... if a new version of MX is available, the MXDiags file will say so (the message is not easy to spot as there is a lot output before it, but here is an example, but in my experience the message has appeared at different places for each of the recent updates):
2020-05-27 04:18:48.326 Calculating sunrise and sunset times 2020-05-27 04:18:48.326 Sunrise: 04:58:11 2020-05-27 04:18:48.326 Sunset : 21:19:54 2020-05-27 04:18:48.326 Tomorrow sunrise: 04:57:08 2020-05-27 04:18:48.326 Tomorrow sunset : 21:21:11 2020-05-27 04:18:48.388 You are not running the latest version of CumulusMX, build 3080 is available. 2020-05-27 04:18:48.763 Station type:
There is no message in whatever place it can appear ...
- ... if you are using latest version, OR
- ... if you are not connected to the internet, OR
- ... if you keep MX running all the time!
Start/Stop script
When the Status option of this script is used, when a new release of MX is available, it will output a message.
What to read (and when) before updating
- If your update is from the immediately previous build, then just check the release announcement inCumulus MX Announcements and Download - PLEASE READ FIRST topic, or the précis style entry at Cumulus_MX_formal_release_versions in this wiki (if that is up to date) for details of functionality changes and which files have been affected.
- The actual release announcement should be more informative. That is where you can read if the upgrade requires one-off actions (like changing the schema if you use a database, or editing your web pages to take advantage of new web tags).
- The release announcement may sometimes include scripts to download and run to perform one-off actions.
- Be aware that it is worth while checking back on the release announcement the next day. It may have been edited because the original announcement forgot to mention something. It may have been edited to mention that some bugs have now been found, and give you advice as whether it is best to regress to an earlier version or take some other action until the next release is available.
- Any new development or change in a new version of MX might cause problems for some users. You might want to stick with the version you are already using unless you really need any new functionality or the fixes gained by upgrading.
- Also remember that there are bugs in all versions of MX, this is a large and complicated package, and the current developer has not been able to test all the code with all possible settings and all possible weather stations.
Updating from an older version
- If your update is skipping some intermediate versions, then check the corresponding release announcements or Wiki entries for every version since the one you have been using before planning your upgrade.
- Again there may be one-off actions required at particular in-between versions and these will not be described in the Wiki whether on the Software page or the Cumulus_MX_formal_release_versions page.
Back-ups
It is always best to take a backup of your existing MX installation before you do an update, this allows you to regress back to the earlier version if either you mess up installing the new version, or the new version has a issue that prevents it working with the versions of other software (like MONO) that your installation uses.
The two approaches
Contributors to this section are named in text.
Some people upgrade by just copying in the files that the release announcement says have changed, others copy in all files from the downloaded zip. The first should only be used with caution, files like CumulusMX.exe.config can change between versions, but not be mentioned in a release announcement, and the developer will have been making edits to files since the previous release, and might forget exactly which files have been edited between releases. Also you may be upgrading from an earlier version and therefore be skipping several intermediate releases. You may be able to see the dates when files were changed within the zip and therefore be able to decide for yourself if you compare those dates with the previous release you were using if you have kept the download for the version you were using.
- The popular approach recommended by many forum contributors in many different posts (including at this post by Mark Crossley for example is to rename your current install directory, then unzip the new release, letting it create a new CumulusMX folder (or whatever name you prefer and specify in unzip options). Copy across Cumulus.ini and string.ini into that new directory, and then copy the contents of the data and Reports directories from your current install to the new install. Don't forget to copy any other set-up files across too. The advantage (as Mark says) is that you ensure you do use all the files in the new release, and don't miss out any he may have forgotten to mention in his release announcement. Another advantage (as PaulMy says here for example) is that you retain your old set-up intact and can easily restore it should you have a problem with new release.
- Various people advise that you don't delete your old installation for a week or so; as you may notice something from the older version that you haven't copied across!
- Check again that you copied across strings.ini, twitter.txt, Cumulus.ini, and similar files in the same folder level as CumulusMX.exe, as well as all the files in the data and Reports sub-folders.
- However,
- if you have a lot of set-up files, or other custom files, (i.e. files not part of release), or
- if you are downloading on a different device, or on a different disc to where you are running MX,
- then David (see this post) recommends this different approach. After downloading a new release unzip it on the device/disc where you down load it. Next simply copy the files (optionally only those that have newer dates because they have changed) into the existing MX directory on the device where you run MX. Then you know all your existing files are there, and you can choose to only copy in files that have been updated.
- The updated files can be tracked by their modification date, or by seeing which are specified in the release notes (find them on this forum or in Wiki here).
Updating when files within release might overwrite your own edits
If you have edited any files, see if the release notice says that file has been revised, if it has not then it is easy to keep your edited file by not copying in the replacement file from within the zip. If the release revises any file you previously edited, take a backup of your edited file, before you copy the new file into your folder. You can then use a file comparing tool to see what has changed in the release and what you changed and hopefully manage to merge to a new file that keeps any functionality change in a new release and keeps your customisation.
This includes any standard web pages you might have edited to give the look you desire, or the content you want (e.g. adding rain this month to this month page, or combining this month and this year page). If you have done major customisation to the standard website then you probably have followed the guidance and stored your new web page templates in a different directory and you use Extra Files to specify where they are, so the new MX will still find them.
If you have done any customisation to the interface then if you have followed the guidance in this article you will have copies of the files that you have customised of the interface folder so you have ability to copy them back into installation - but be careful with this one, as many releases change the interface in some way and the various components of the interface have to work together as a coherent unit. Be prepared to go back to the standard file for whatever you customised if something it depends upon has changed, after all you must not lose any vital functionality.
After update
Start the new installation of MX and watch out for any errors - If the device you run MX on has a monitor, then look in the terminal/command window. In all cases look at the latest file in the MXdiags folder to see if any errors are reported.
Also keep an eye on the support forum for first few days, some releases do have bugs, as developer cannot test all possible configurations.
Updating if you use a virus Checker
You may find that virus checkers such as Windows Defender reject your new version of MX. They need to be told it is safe.
Updating if you use the start/stop management script
This section contributed by Jank on support forum.
1. look on Software download page, find the link to latest version, and fill out the '...' below appropriately as you run these 2 commands on your device where you do downloads:
cd /tmp wget https://github.com/cumulusmx/CumulusMX/ ... .zip
2. Once that download is complete, start cumulusmx.sh with option -u
/home/pi/CumulusMX/cumulusmx.sh -u
3.When asked for the zip file, enter
/tmp/CumulusMXDist
and hit the TAB Button
4.Choose the zip file with the CumulusMX update and hit return.
5. Follow the on screen instructions
6. With each update component .....you can choose: [y]es, [n]o, [A]ll, [N]one, [r]ename
I would recommend select A as that will simply replace all files without further action.
CumulusMX will be restarted after update completes.
You can check if the update was successful by using option -s:
/home/pi/CumulusMX/cumulusmx.sh -s
