Upgrading Squore

The Squore installation package can be used to upgrade an existing Squore installation. When an installation is upgraded, the following happens:

  • The new version of Squore Server overwrites the previous one inside the same installation directory

  • The database is upgraded

  • The web server configuration is upgraded

  • The data files are migrated

  • All of your settings are kept, and a clean version of some configuration files is placed on your system next to the original file, with a .new extension. Here are the files:

    • <CLUSTER_DIR>/postgresql.conf

    • <SQUORE_HOME>/config.xml

    • <SQUORE_HOME>/server/bin/standalone.conf on Linux or <SQUORE_HOME>/server/bin/standalone.conf.bat on Windows

    • <SQUORE_HOME>/server/standalone/configuration/standalone.xml

    • <SQUORE_HOME>/server/standalone/configuration/squore-server.properties

    • <SQUORE_HOME>/server/standalone/configuration/application-users.properties

Having .new files can help you compare your files with the defaults from a clean installation.

Upgrading to this Squore 24.0.0 version will only be possible if you are using one of the last 5 previous major versions.

Windows

  • Ensure you have a backup of your data before attempting an upgrade. When an upgrade fails, restore the previous Squore installation and its data before attempting the upgrade again.

  • The java version required by the new version of Squore may be different from the one you were using in your previous installation. An installer screen will prompt you for the path to the new Java installation to use after upgrading.

  • The migration takes place in Squore’s temp folder (as configured in <SQUORE_HOME>/config.xml). Make sure you free up space before starting the upgrade, around 30% of the current database size is needed as additional free space.

  • Folders inside the installation directory are deleted during an upgrade. Ensure your <SQUORE_DATA> folder is not located inside your <SQUORE_HOME> folder. Before you attempt to upgrade Squore, run a full backup of your data (and move it outside <SQUORE_HOME>) using the provided backup scripts described in Backing-Up Squore Data

  • The file postgresql.conf in your database cluster is patched during the upgrade process. If you have modified it manually, verify that the migrated file still contains your modifications.

  • If you are using a local PostgreSQL cluster as your database, ensure that the server and the database are shut down before continuing. If you are using a remote Oracle database cluster not managed by Squore, ensure that Squore Server is stopped and that the database is accessible and accepting connections.

  • No progress information is displayed on screen during the database upgrade phase, which may take a while to complete.

Follow these steps to upgrade your Windows installation:

Running the Windows installer generates a log file in "<SQUORE_HOME>\install.log", which you can consult if you think there is an issue with your installation. When an installation or upgrade fails, the operation is rolled back in an attempt to remove all files in the selected installation folder. When this happens, the log file can be found in "%LOCALAPPDATA%\Temp\install_squore.log" instead.

  1. Run the Windows installer.

  2. Click the Next button to get to the License Agreement screen.

  3. If your previous version was at least Squore 18.0, the previous installation will detected and migrated automatically when you click Next. If your previous version is older, you will have to tell the installer where your old installation is located. Click the Next button to get to the Destination Folder screen.

  4. Browse for the folder containing the old installation and click the Next button.

  5. On the Upgrade screen, the installer confirms that the selected folder contains an older Squore installation.

    SIM inst17 upgrade
    Figure 1. The Upgrade screen

    Click the the Next button button to continue with the upgrade.

  6. If you are running an unsupported Java version, you will see the following screen, where you can specify the path to the new Java version:

    SIM inst upgrade java new
    Figure 2. The Squore Setup screen for the new Java directory

    Specify the path to the new Java installation and click the Next button to continue with the upgrade.

  7. The Confirmation screen is the final step before the upgrade starts. If you are satisfied with your selections and have enough free space to proceed, click Install.

    SIM inst13 Summary
    Figure 3. The Confirmation screen

  8. Wait for the upgrade process to complete and close the wizard by clicking on Finish.

    SIM inst15 Complete
    Figure 4. The Installation Complete screen

Linux

  • Ensure you have a backup of your data before attempting an upgrade. When an upgrade fails, restore the previous Squore installation and its data before attempting the upgrade again.

  • The java version required by the new version of Squore may be different from the one you were using in your previous installation. You can use the -J option to specify the new path to Java in your upgrade command line. For more details on install options, refer to install(1).

  • The migration takes place in Squore’s temp folder (as configured in <SQUORE_HOME>/config.xml). Make sure you free up space before starting the upgrade, around 30% of the current database size is needed as additional free space.

  • Folders inside the installation directory are deleted during an upgrade. Ensure your <SQUORE_DATA> folder is not located inside your <SQUORE_HOME> folder. Before you attempt to upgrade Squore, run a full backup of your data (and move it outside <SQUORE_HOME>) using the provided backup scripts described in Backing-Up Squore Data

  • The file postgresql.conf in your database cluster is patched during the upgrade process. If you have modified it manually, verify that the migrated file still contains your modifications.

  • If you are using a local PostgreSQL cluster as your database, ensure that the server and the database are shut down before continuing. In all other scenarios (a remote Oracle database or PostgreSQL cluster not managed by Squore) ensure that Squore Server is stopped and that the database is accessible and accepting connections.

  • No progress information is displayed on screen during the database upgrade phase, which may take a while to complete.

Follow these steps to upgrade your Linux installation:

  1. Download the Linux installation package.

  2. Extract the archive by running the command:

    cd /tmp
tar xf squore-24.0.0-linux-x86_64.tar.xz

  3. Manually backup your current <SQUORE_HOME>/server/bin/standalone.conf.

  4. Run the upgrade by executing:

    cd /tmp/squore-server/bin
./install -U /path/to/old/installation [options...]

  5. Redeploy your backed-up <SQUORE_HOME>/server/bin/standalone.conf if necessary to reapply your custom configurations.

Manual Upgrade

If the upgrade cannot be performed with the installation package, it is possible to upgrade Squore manually on both Windows and Linux.

Before proceeding with the upgrade :

  1. Create a backup of your current Squore installation

  2. Install a fresh Squore, from scratch, in the version you wish to upgrade to.

If you are using a remote database, backup and restore operations cannot be done automatically and are of the DB administrator responsibility.

Then, follow the procedure below :

  1. Stop Squore :

    <SQUORE_HOME>/bin/sqctl stop

  2. Start database :

    <SQUORE_HOME>/bin/pgctl start

  3. Restore your backup : refer to the Restoring Squore Data section.

  4. Upgrade your database, where version is the Squore version the restored backup is coming from:

    <SQUORE_HOME>/bin/sqadm upgrade-data version

    This command runs silently. It can take from a few minutes to a few hours, depending on the amount of data to migrate, the version you are coming from and your hardware performances.

Equivalent Windows commands are :

  • Stop Squore : stop.bat

  • Start database : start-db.bat

  • Upgrade database : sqadm.bat

The manual upgrade procedure will not keep your configuration changes such as LDAP, JAVA XMX parameter and such. Be sure to report manually all these changes afterward.

Here is a non-exhaustive list of configuration files that are usually modified :

  • <SQUORE_HOME>/config.xml

  • <SQUORE_HOME>/server/bin/standalone.conf

  • <SQUORE_HOME>/server/standalone/configuration/standalone.xml

  • <SQUORE_HOME>/server/standalone/configuration/application-users.properties

  • <SQUORE_HOME>/server/standalone/configuration/squore-server.properties

  • <CLUSTER_DIR>/postgresql.conf