The new installer for Confluence and JIRA on Windows simplifies upgrades, but it also overwrites added or modified files in your program directory. If you have added or modified a lot of files, it can be tedious to restore those modifications after the upgrade. To that end, I’ve written a simple powershell script which will back up all of the modified files and then optionally restore the files once the upgrade is complete.
Atlassian Installer Behavior
The installer provided by Atlassian will look at the program directory for JIRA or Confluence and build a list of all the files which have been added, modified, or removed from a base install. Commonly modified files include conf\server.xml or WEB-INF\web.xml for changing the port number, SSL settings, etc. If there are any modifications, the installer will show you a list of the files of each “class” and it will also write a text file with the same list in the directory above the program directory.
They give you this list because the installer will overwrite all of those files, and it’s up to you to put them back or merge the changes back in. In my experience so far, I have not had trouble just copying the old files back. I have not yet seen changes in the XML files that necessitated merging changes or making the changes in a different way (even in the change to Confluence 4), but it's bound to happen at some point so keep an eye out.
I have definitely seen these changes. You have to be particularly careful with WEB-INF\web.xml as this one seems to change a lot, and using an old version of the file could cause problems starting, or it could start but certain features may be broken (it can be hard to track down), so I recommend just reintegrating the changes here. Typically it’s changes described in Step 5 of this document.
Powershell to the Rescue
Usage:
Backup Parameter Set:
Handle-Modifications.ps1 -Path <String> [-Backup] [-BackupPath <String>]
Restore Parameter Set:
Handle-Modifications.ps1 -Path <String> [-Restore] [-RestorePath <String>] [-BackupOverwrittenFiles]
Parameters:
-Path
Path refers to the program directory for Confluence or JIRA. Examples:
C:\Program Files\Atlassian\JIRA C:\Confluence\Program
-Backup
Indicates that you are backing up the modifications. You run a backup after you have started the installer, where it shows the modifications on the screen. At this point the installer is paused, and the modifications text file has already been created.
-BackupPath
Defaults to upgrade. This is the relative directory that will serve as the base of the backups created by this script. It will be created one level up from the Path value. For example, if your path is C:\Confluence\Program and you leave the default of upgrade, then the base backup path will be C:\Confluence\upgrade.
Within that path, a directory named for the current version will be created and within that, a directory named original will hold the files being backed up in their original structure. So if the original file:
C:\Confluence\Program\jre\lib\security\cacerts
were to be backed up, its path would end up like this:
C:\Confluence\upgrade\4.2.8-modifications\original\jre\lib\security\cacerts
-Restore
Indicates that you are restoring the latest set of backed up modifications. You run a restore after the upgrade is complete. At this point the installer should have overwritten everything, and you should have shut down the product if the installer started it automatically.
-RestorePath
Defaults to upgrade. This the equivalent of -BackupPath above. The script will search for the *-modifications folder with the highest version number, and it will restore those files to the correct structure in -Path.
-BackupOverwrittenFiles
Defaults to $true. If this is true, any files that would be overwritten by a -Restore operation will also be backed up. This is useful in case there were changes in the upgrade that make the old versions unusable as a drop-in replacement, and in that case you may need to manually merge your old changes into the newer file. This should help prevent you from having to reinstall the newer version.
It will put the files in a directory called restored at the same level of the original directory described in the -BackupPath description. Example:
C:\Confluence\upgrade\4.2.8-modifications\restored\jre\lib\security\cacerts
(this would be a backup of the new one that was installed with the upgrade, which would not contain any of your modifications)
If for some reason you need to run this script twice, you might want to set this to $false on the second+ run to avoid filling the restored directory with your modified files, as this script will overwrite them without asking.
Workflow
The basic outline of when you run the script looks like this:
-
Begin the upgrade by running the installer. It will look for and find a previous version.
-
Get to the point where the installer is showing you the modifications.
-
Run the script in Backup mode:
Handle-Modifications.ps1 -Path "C:\Confluence\Program" -Backup -
Confirm that your files were actually backed up!
-
Continue the upgrade until finished.
-
If the installer started the product, make sure it’s settled and then stop it gracefully.
-
Run the script in Restore mode:
Handle-Modifications.ps1 -Path "C:\Confluence\Program" -Restore -
Optionally, instead of restoring with the script, manually move or merge your files back.
Handle-Modifications.ps1