Updating MX to new version: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

Updating MX to new version (view source)

Revision as of 09:22, 1 February 2021

1,329 bytes added ,  09:22, 1 February 2021
m
Text replacement - "[[MXDiags" to "[[MXDiags_folder"
m (Text replacement - "[[MXDiags" to "[[MXDiags_folder")
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Who this article is for=
=Who this article is for=


Please be aware that if you want to move from Cumulus 1 to MX, you should read [[Moving_from_Cumulus_1_to_MX]] article instead.
Please be aware that if you want to move from Cumulus 1 to MX, you should read [[Migrating_from_Cumulus_1_to_MX]] article instead.


This article is for those who already use MX, and so are comfortable with basic MX installation and running.
This article is for those who already use MX, and so are comfortable with basic MX installation and running.
Line 10: Line 10:


=Introduction to updating MX=
=Introduction to updating MX=
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This document is 'Work In Progress' so content may not be complete or accurate!
</div>
[[Category:Cumulus MX]]


==Installer Option==
==Installer Option==


HansR on support forum is developing an installer as this is being typed, see [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=18893 this topic]. He proposes to start a new topic when his installer is ready for general use, and I hope he will update this section appropriately.
HansR on support forum is developing an installer as this is being typed, see [https://cumulus.hosiene.co.uk/viewtopic.php?f=44&t=18916 this topic].  
 
<big>I hope he will update this section appropriately.</big>


==Updating if you are running MX on a Linux computer==
==Updating if you are running MX on a Linux computer==


You might want to read galfert's post on the support forum [https://cumulus.hosiene.co.uk/viewtopic.php?p=148851#p148851 here] for the relevant Linux instructions in a concise format.
You might want to read galfert's post on the support forum [https://cumulus.hosiene.co.uk/viewtopic.php?p=148851#p148851 here] for the relevant Linux instructions in a concise format.
== Updating if you use the start/stop management script ==
This section contributed by ''Jank'' on support forum.  Note the version on the forum might have been updated from the original included here.
1. look on [[Software|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:
<pre>cd /tmp
wget https://github.com/cumulusmx/CumulusMX/ ... .zip</pre>
2. Once that download is complete, start cumulusmx.sh with option -u
<pre>/home/pi/CumulusMX/cumulusmx.sh -u</pre>
3.When asked for the zip file, enter
<pre>/tmp/CumulusMXDist</pre> 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:
<pre> /home/pi/CumulusMX/cumulusmx.sh -s</pre>


== Updating to the next MX release if you have not updated before ==
== Updating to the next MX release if you have not updated before ==
Line 48: Line 83:
===Advice about skipping versions===
===Advice about skipping versions===


Early builds of MX were all assigned to the same version number, recently the version number seems to change with every new build. Thus the following simple advice about skipping versions might not be applicable in 2021 onwards.
Please see [[Updating_MX_to_new_version#Updating_from_a_very_old_version]] sub-section later on this page (and preceding sub-sections where relevant)
 
One would assume that, skipping minor releases in an update (from 3.x.y to 3.x.z, i.e. only final digit of version number changing is a minor release) would always be simple, even if several intermediate builds are skipped. Most developers would not introduce a new feature in a minor release that requires a one-off extra action for a successful upgrade. Unfortunately, some minor releases of MX have required you to do special actions.
 
One might assume that the ease of doing a major update (i.e. where middle part of version number changes) involves greater difficulty.  Most developers would only classify a new release as a major update if there was new functionality being introduced that, depending on what functionality you use, might involve a one-off extra action to prepare for upgrade to that version. It is harder to understand why some MX releases are classified as major version number change, and some as minor version number change.


You may be using an old version of MX that is actually several versions behind, or even still using a beta version released by Steve Loft, don't worry because this article covers upgrading however old a version you are using. You can update skipping some major updates, but as that can be more complex, there is a separate section later with advice on how to update in stages from an early build to a recent build.
The important point to make here is that when you do an update, you should copy in '''ALL''' files from the release distribution you want to run next. This is because there are dependencies between files within a distribution, so missing out any particular file may stop other files from working. However, if you are skipping versions, read the in-between release announcements to see if there are any one-off actions.


= Knowing when a new release is available =
= Knowing when a new release is available =
Line 334: Line 365:
If you won't listen to best practice advice, and have decided to for example modify the provided Cumulus web templates without allocating new names, then installing the whole release distribution will overwrite your edited file(s) with the standard file content provided by the developer. Therefore you need to do a customised approach where you select which files from the distribution to copy into your installation. If you have changed one or more web templates, you might think it safe just to omit the relevant files in the zip within folder '''web''', but some builds change the files in the '''webfiles''' folder too, and you need to retain consistency.
If you won't listen to best practice advice, and have decided to for example modify the provided Cumulus web templates without allocating new names, then installing the whole release distribution will overwrite your edited file(s) with the standard file content provided by the developer. Therefore you need to do a customised approach where you select which files from the distribution to copy into your installation. If you have changed one or more web templates, you might think it safe just to omit the relevant files in the zip within folder '''web''', but some builds change the files in the '''webfiles''' folder too, and you need to retain consistency.


== After an update if you use the standard web template files ==
==== Updating when files within release might overwrite your own edits ====


=== web folder from zip ===
To further explain the customised approach, here are some more examples.


The new web template files will be in your '''web''' folder and MX will process the new files and upload the web pages produced as before with no further action by you.
===== web site files =====


=== webfiles folder from zip ===
If you have edited any files that sit on your '''web site''', then these can remain on your web site. However, if those web pages are generated from templates that you expect MX to process and upload for you, you do need to take special action. Maybe you edited a template 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).


You do need a further action, if any files in this folder have been updated. The updated files must be uploaded to your web site.
The first step is to 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. Do think about changing name of the template file, or placing it in a different folder, and using the '''Extra Files''' settings. That will make it easier for you next time you do an upgrade to a new MX build.


This may be easy to forget if you use the standard web templates, because you thought that upload was a one-off and maybe you cannot remember what you did.  
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 they cannot be overwritten, and the new MX will still find them. It might be that new web tags have been added since whatever build you were running before, and that you decide to edit your customised template file, but that can be done any time after you install the new MX build.


Certain third-party web-pages still use files from that folder, if one of the files they use has been updated, then ensure you have a backup of your web site before you upload the updated file, it should work, but it might not, and you might need to regress.
===== admin interface files =====


Let me go through the files currently in webfiles folder:
If you have done any customisation to the '''interface''' (perhaps you don't like seeing solar in the tables when you don't measure that) then again you can skip over these files when copying. Hopefully 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 if you do overwrite with the release version.
*'''weatherstyle.css''' has not been updated since its last update by Steve Loft in 2009.
*subfolder '''images''' contains 2 pictures that have stayed same since MX launch
*subfolder '''js''' contains one file. The file '''\CumulusMX\webfiles\js\cumuluscharts.js''' has changed in a lot of releases.  The standard web page '''trends.htm''' will only work if the correct version of that file has been uploaded to your web site and placed in a sub-folder "js" of where "trends.htm" is installed.  BCJKiwi's user interface '''charts.php''' also requires the same JavaScript file, so upload the file anytime it is updated in a MX release.
*subfolder '''lib''' currently contains 3 folders:
**'''highstock''' - this folder is no longer needed on your web site
**'''jquery''' - this folder is needed for "trends,htm" to work, but it has not been updated since 2014. Both the files included are obsolete packages, no longer officially available, and there are no plans to replace them.
**'''steelseries''' - this folder has 3 sub-folders, and I can only think of 2 MX releases when anything was changed here, and I don't anticipate any further changes.


== Updating when files within release might overwrite your own edits ==
'''You do have to be careful''', as many releases change the interface in some way, even if the change is not in the file you have customised, it might be in an asociated file, and all the various components of the interface have to work together as a coherent unit. For instance when feels like was added to MX, the api used for sending data from the MX engine to the admin interface was updated. In some releases, a new web page is added to the admin interface, with the consequence that all the navigation menus were adjusted in all web pages. Any HTML page in the admin interface may be edited to refer to a different styling page (so it, and the .css file, must be updated together) or to a different script (so the .HTML, and the .js file, must be updated together).  The settings pages in the admin interface are dependent on the correct pair of json files to define the options or values that appear on that web page, so again all must be consistent. 


=== web site files ===
To sum up, admin interface files are interdependent, and you cannot always update some, but not all, of the admin interface pages.  
If you have edited any files that sit on your '''web site''', 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), 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.


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 they cannot be overwritten and the new MX will still find them.  
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.


=== admin interface files ===
On my site, my own versions of interface files have a "_" (underline character) added to the start of the standard MX file name. This applies to both HTML pages, and JavaScript files that I have edited. I edit the menu items within my edited pages so those all go to my versions where I have a HTML customised page, leaving unchanged the menu items that can still go to a standard MX web page where I don't have my own version of the .HTML page.  This makes it easy for me to navigate between my pages, as all of them link to my other pages.  If I am on a standard MX page and want to go to one of my customised pages, I select the equivalent standard page, then edit the URL to add the underline and get easily to my page.  This naming means I can always use a standard page instead of my customised page when I need to, and I never miss out on any new features.


If you have done any customisation to the '''interface''' (perhaps you don't like seeing solar in the tables when you don't measure that) then again you can skip over these files when copying. Hopefully 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 if you do overwrite with the release version. 
== After an update if you use the standard web template files ==


You do have to be careful, as many releases change the interface in some way and all the various components of the interface have to work together as a coherent unit. For instance when feels like was added to MX, the api used for sending data from the MX engine to the admin interface was updated. In another release, adding a new web page, all the navigation menus were adjusted in all web pages. A HTML page may be edited to refer to a different styling page (so it and the .css file must be updated together) or to a different script (so the .HTML and the .js file must be updated together.  Many web pages are dependent on the correct pair of json files to define the options or values that appear on that web page.  So files are interdependent, and you cannot always update some but not all of the admin interface pages.  
If you do not use the example web template files, provided as standard, with a MX release, the remainder of this section can be ignored.


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.
If you use the third party [[CumulusMX and Cumulus1 UI style Multilingual Websites]] web pages, as maintained by BCJKiwi, follow any instructions in his package as to which of the files in this section are required and any announcements in his forum topic about when such files need to be upgraded.


On my site, my own versions of interface files have a "_" (underline character) added to the standard MX file name (before the "." and the relevant extension). This applies to both HTML pages, and JavaScript files that I have edited. I edit the menu items within my edited pages so those all go to my versions where I have a HTML customised page, leaving unchanged the menu items that can still go to a standard MX web page where I don't have my own version of the .HTML page.  This makes it easy for me to navigate between my pages, as all of them link to my other pages.  If I am on a standard MX page and want to go to one of my customised pages, I select the equivalent standard page, then edit the URL to add the underline and get easily to my page.  This naming means I can always use a standard page instead of my customised page when I need to and I never miss out on any new features.
=== web folder from zip ===


== After update - checking for bugs in MX or mistakes in your installation ==
If you do use the example web templates to produce web pages for your web server, and you have copied all files from the release distribution ....


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.
....MX will find any new web template files in your '''web''' folder,  MX will process those template files, and upload the web pages produced, ''as before with no further action by you''.


Also keep an eye on the support forum for first few days, some releases do have bugs, as developer cannot test all possible configurations.
=== webfiles folder from zip ===


== Updating if you use a virus Checker ==
<br/>
You may find that virus checkers such as Windows Defender reject your new version of MX. They need to be told it is safe.
<big>PLEASE COULD SOMEONE USING LATEST MX RELEASE ENSURE THIS IS KEPT UP TO DATE</big>


== Updating if you use the start/stop management script ==
<br/>


This section contributed by ''Jank'' on support forum.  Note the version on the forum might have been updated from the original included here.
You do need a further action, if any files in this folder have been updated.  The updated files must be uploaded to your web site.


1. look on [[Software|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:
This may be easy to forget if you use the standard web templates, because you thought that upload was a one-off and maybe you cannot remember what you did.  
<pre>cd /tmp
wget https://github.com/cumulusmx/CumulusMX/ ... .zip</pre>


2. Once that download is complete, start cumulusmx.sh with option -u
Certain third-party web-pages still use files from that folder, if one of the files they use has been updated, then ensure you have a backup of your web site before you upload the updated file, it should work, but it might not, and you might need to regress.
<pre>/home/pi/CumulusMX/cumulusmx.sh -u</pre>


3.When asked for the zip file, enter
Let me go through the files currently in webfiles folder:
<pre>/tmp/CumulusMXDist</pre> and hit the TAB Button
*'''weatherstyle.css''' has not been updated since its last update by Steve Loft in 2009.
 
*subfolder '''images''' contains 2 pictures that have stayed same since MX launch
4.Choose the zip file with the CumulusMX update and hit return.
*subfolder '''js''' contains one file or two files (depending on which MX release you are using:
**The standard web page '''trends.htm''' will only work if the correct version of any file here has been uploaded to your web site, and placed in a sub-folder "js" of where "trends.htm" is installed. .
*** BCJKiwi's user interface '''charts.php''' also requires the same JavaScript file (or files?), so upload the file(s0 anytime there is a change in a MX release.
** The file '''\CumulusMX\webfiles\js\cumuluscharts.js''' has changed in a lot of releases, it is updated whenever there is a change in the JSON files used for providing data to the charts, and you must use the right upgrade.
** The file '''historiccharts.js'' (it was introduced from release 3.8.7) is similar to previous script, but drives the historic chart functionality on your web server
*subfolder '''lib''' currently contains 3 folders:
**'''highstock''' - this folder is no longer needed on your web site (and the most recent MX releases have emptied it)
**'''jquery''' - this folder is needed for "trends,htm" to work, but it has not been updated since 2014. Both the files included are obsolete packages, no longer officially available, and there are no plans to replace them.
**'''steelseries''' - this folder has 3 sub-folders, I can only think of 2 MX releases when anything was changed here, and I don't anticipate any further changes.


5. Follow the on screen instructions
= After update - checking for bugs in MX or mistakes in your installation =


6. With each update component .....you can choose: [y]es, [n]o, [A]ll, [N]one, [r]ename
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|MXdiags folder]] to see if any errors are reported.


I would recommend select '''A''' as that will simply replace all files without further action.
In newer releases of MX, also see [[ServiceConsoleLog.txt]]


Also keep an eye on the support forum for first few days, some releases do have bugs, as developer cannot test all possible configurations.


CumulusMX will be restarted after update completes.
== 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.
You can check if the update was successful by using option -s:
<pre> /home/pi/CumulusMX/cumulusmx.sh -s</pre>
Sfws
5,838

edits

Retrieved from "https://www.cumuluswiki.org/a/Special:MobileDiff/7489...7757"

Navigation menu