Cidram: How to upgrade to latest version

[uksitebuilder]

As per subject, how to upgrade to latest version without losing any configuration, installed modules, etc?

[Maikuolan]

Hi @uksitebuilder, :-)

To help me answer that as best as possible, could I clarify the context(/s) of your current installation(/s)? (e.g., whether installed manually via the documented manual installation methods, whether installed via Composer, installed via the WordPress plugins dashboard, or installed by some other method entirely and so on, and whether running as single-domain or multi-domain installations, etc). I would offer slightly different advice, and suggest a slightly different process, depending on some of these details.

Cheers. :-)

[uksitebuilder]

Hi,

Yes, it is single domain, manual install via documented manual installation method

Kind Regards
Simon

[Maikuolan]

Sorry for the delayed reply. Busy with work and other offline commitments quite a bit over the past week.

Final question: Are you currently on v1, looking to upgrade to the latest v2 version (i.e., looking to perform a major version upgrade)? Or are you looking to upgrade to the latest version for your currently used major version (i.e., either already using v2, or using v1 and looking to upgrade only to the latest v1 version, therefore making this either a minor or patch version upgrade)?

If the latter (i.e., the intended upgrade won't be changing the currently used major version), the easiest way to upgrade would be to simply enable the front-end (if not already enabled), access the front-end updates page, and click "update all" (thereby automatically updating everything to the latest available versions for whichever major version is currently in use with no more needed than a single click of a button). Doing so won't change any of your configuration, and won't change which components/modules/etc are installed (doing so will only update them to their latest available versions). The front-end can then be disabled again after performing the update if keeping it disabled is preferable (e.g., because of security concerns, or because it isn't needed/wanted/etc).

If the former (i.e., the intended update will be changing the currently used major version), I'm planning to eventually implement a similar solution for that, in order to allow users to easily and automatically update to the latest available version across major versions, but I haven't figured out a specific deadline for that yet. I'm also planning to eventually write up a migration guide for users, but haven't had time to finish that yet either.

The main problem there is that there have been some changes implemented between v1 and v2 which the mechanism provided by front-end updates page isn't yet capable of patching automatically, and, although it's definitely very possible to do it all manually, and not exceedingly difficult to do, it's just barely difficult enough that I anticipate I'll end up with a number of users complaining to me about it, or about things going wrong during the process, if I was to tell them all that that's the "official" way that they need to do it (so, I'm hoping to come up with something that I could offer as a somewhat less difficult, more convenient alternative, before writing up that migration guide).

For the moment though, sticking with your current major version shouldn't be a problem, as the main difference between v1 and v2 is the minimum required PHP version, and that v2 takes advantage of some things introduced since newer PHP versions (e.g., scalar parameter type hints, return type hints, etc), which can't be added to v1 due to being locked into a lower minimum PHP version requirement, and there aren't yet any differences between v1 and v2 in regards to features, functionality, etc (though that'll likely change in the future, in the event that we decide we want to implement something to CIDRAM that just isn't possible to implement for the older PHP versions). The "CLI-mode" feature available in v1 was also removed since v2, because nobody was using it, and it's pointless keeping features that nobody uses (but that also shouldn't be a problem, seeing as nobody was using it). Basically, if you're looking at performing a major version upgrade, it should be much easier to do in the near future than it is to do right now, so, if it isn't super urgent, and if you don't want to deal with a lot of hassle, I'd recommend just performing minor and patch updates for the moment, and then revisit the possibility of performing a major update in maybe a month or so.

Otherwise though, if you'd like to have a go at doing a manual major version upgrade and don't mind the hassle:

• Perform a full backup of your current CIDRAM installation (e.g., by downloading it, creating a ZIP archive of it, etc). You'll need this in case something goes wrong during the upgrade process, and also to retain your configuration and other data.
• Temporarily disable your hooks.
• Completely uninstall your current CIDRAM installation.
• Reinstall CIDRAM from the latest available version.
• From your backup, copy vault/cache.dat (less important than the others; contains things like statistical information, IP tracking information, etc; mightn't exist, depending on whether any of the supplementary cache options have been customised; don't need to worry about it if it doesn't exist, or if you don't want to retain that particular data), vault/cidramblocklists.dat, vault/config.ini (contains all your configuration; the most important file in this list; will lose your configuration if you skip this file), vault/fe_assets/frontend.dat (if it exists.. but if it doesn't, don't worry about it; contains front-end login information; probably won't exist if you normally keep the front-end disabled), vault/ignore.dat (if you recall ever modifying this file; otherwise, if you've never touched it, don't worry about it), vault/modules.dat, and vault/themes.dat across to your new installation (replacing any existing counterparts in your new installation). If you've ever written any custom signature files yourself (including if you've ever written custom signatures into ipv4_custom.dat or ipv6_custom.dat before) or written any custom modules yourself, copy across the files for those, too. If you want to be able to access old log data specifically from the CIDRAM front-end, copy across the files for those, too (but if you don't care specifically about using the front-end logs page to view log data, or don't need to keep old log files around for any particular other reason, you can skip those). Don't copy across anything else.
• Referring to the tree at the top of the "CONFIGURATION OPTIONS" section of the documentation, for any options/directives that include a small, bracketed "v1" (as an example: logfile_apache (v1: logfileApache)), if you've customised any of those particular options/directives in your own configuration, you'll need to rename them in your own configuration from their old v1 name to the new v2 name (or alternatively, if you normally use the front-end configuration page to customise your configuration, you could manually re-enter the appropriate values for the pertinent options/directives). For any that you haven't customised, you don't need to do anything.
• After (but not before) doing the above, enable the front-end (if not already enabled), access the front-end updates page, and click "repair all". This will check the list of which modules and signature files should be installed, automatically reinstall any missing files from the remote upstream source, and automatically patch any corrupt/damaged/outdated files that it detects in the installation. Don't forget to disable the front-end again afterwards if you don't normally use, or don't want to use the front-end.
• Enable all the previously disabled hooks.

That should be everything, but I would recommend testing it, and briefly eyeballing over it all to make sure it "looks right", just in case anything goes wrong. :-)

[uksitebuilder]

Thanks

[Dibbyo456]

@Maikuolan is v2 faster than v1?

[Maikuolan]

@Dibbyo456 AFAICT from my own testing and my own experiences, plus accounting for the reduced footprint by way of the small number of things in v1 which were removed since v2, v2 is slightly faster than v1, but we're talking faster by maybe a few milliseconds on average. The difference is a point in favour towards upgrading to v2, but not a particularly significant point.

[Dibbyo456]

but we're talking faster by maybe a few milliseconds on average

😄

For months I wanted to migrate to v2 but due to lack of _how-to-upgrade docs_ I did not. Thank you for the upgrade docs, I will pull the gun tonight. 😊

[Maikuolan]

I will pull the gun tonight. 😊

Awesome! Good luck and I hope that all goes well. :-)

[Dibbyo456]

Just wanted to let you know, that I have now successfully upgraded to v2 on my production server.
I made sure everything is in order in my localhost first. After sanity check, I rsynced the files to my server. Everything seems to working as of now.. 🥰