Before you begin

Execute the following steps before beginning the AtScale upgrade procedure:

1. Make sure the version of AtScale you are running is 2021.3.x!

   In case you are using an earlier version you must first upgrade to 2021.3.x. For details, see Upgrading Stand-Alone AtScale (referred to as Upgrade Guide).

2. Make sure that your AtScale Engine system has enough disk space.

   As part of the upgrade procedure described in this document, AtScale will upgrade and replicate the internal AtScale database. This can have significant disk space requirements depending on the size of the AtScale database. Execute the following steps to check the amount of needed disk space:

   1. Check the size of the Postgres database using the following command: du -sh /opt/atscale/data/database

   2. Check the available space in the Operating System partition where AtScale is installed using the following command: df -h

   3. The available space should be a minimum of 2 to 3 times greater than the current AtScale Postgres database size (as recorded in the first step).

   4. If there is not enough available space: stop, and do not attempt to move forward with the upgrade until resolving the disk space issue.

      If needed, space can be freed by removing extra log files in the /opt/atscale/log/database directory. If you are unable to free up enough space, contact AtScale Support for additional assistance to see if there are other options to proceed forward with the upgrade.

3. Perform a backup of the AtScale Database; if desired, you can also make a full backup of the AtScale system.

   It is recommended that this backup be transferred off of the host to a secure file location. For details, see Backing up and Restoring AtScale Database Instances and Backing up and Restoring AtScale.

4. Obtain certificates.

   Check if you are using Secure LDAP on AtScale, and if any certificates need to be imported into the truststore.jks or cacerts files on AtScale. If yes, obtain and store these certificates. You will need to re-import them into AtScale at the conclusion of this procedure.

5. Follow and complete the Prerequisite Installation Steps.

Procedure

1. Follow the steps from the Install the AtScale Installer Package section of the Upgrade Guide.

   Do not activate AtScale yet!

2. Stop AtScale services using the /opt/atscale/bin/atscale_stop command.

3. Obtain the system locale by running the localectl command.

   For example, you can see the following result: System Locale: LANG=en_US.UTF-8

   The locale is identified as the value after LANG=. In the above example, the system locale is en_US.UTF-8.

4. Run the installer/database-upgrade.sh tool from the newly installed (but not yet activated) AtScale version directory.

   In case you obtained the system locale in the previous step, you should specify it with the --locale argument (in the example here, en_US.UTF-8):

   /opt/atscale/versions/<NEW_2021.4.X_ATSCALE_VERSION>/bin/installer/database-upgrade.sh --locale "en_US.UTF-8"

   Running the tool ports data from the old PostgreSQL 9.6.22 data directory at /opt/atscale/data/database to the new PostgreSQL 14.0 data directory at /opt/atscale/data/database-14.

5. Make sure the tool completed its job successfully by checking the logs at /opt/atscale/log/database/database_upgrade.

   In case the tool failed: review the failure message, and then check the More information section below for next steps.

6. Run the following command to activate AtScale; for details, see the Activate AtScale section of the Upgrade Guide.

   cd /opt/atscale/versions/<package_version>

   ./bin/configurator.sh --activate

   Enter y when asked "Do you want to apply these settings?"

   Note: In case you see a message like the one shown below, enter y to cancel the activation. Then run the database-upgrade.sh tool as described in the previous steps.

   
   

   The old AtScale database directory, /opt/atscale/data/database,

   exists and the new one, /opt/atscale/data/database-14,

   has either not yet been created or is still empty.

   
   

   If you are upgrading AtScale, please exit and run

   /opt/atscale/versions/2021.4.0.4230/bin/installer/database-upgrade.sh

   before continuing with the Configurator.

   
   

   Do you wish to exit in order to run /opt/atscale/versions/2021.4.0.4230/bin/installer/database-upgrade? (y/N):

7. Import certificates.

   If Secure LDAP is used in your AtScale environment, and if the LDAP certificates were imported into AtScale to allow connection to the Secure LDAP environment, then the certificates will need to be re-imported in AtScale. Follow this procedure:

   1. Execute the atscale_stop command.
   2. Import the certificates into AtScale's cacerts file and run the configurator.sh -apply command as described in Before you begin: Importing a Certificate.
   3. Verify that LDAPS connectivity is working.

8. Complete the upgrade by following the steps from the What to do next section of the Upgrade Guide.

More information

Note the following about the database-upgrade.sh tool:

• Running it more than once is fine, since subsequent runs will fail with a warning stating that the database has already been initialized and is likely upgraded.

• If a full re-run of the tool is needed, first move or delete the /opt/atscale/data/database-14 and then run the tool again.

• If the tool continues to fail, contact AtScale Support for assistance.

• In case the tool fails and you want to restore AtScale, the AtScale services can be restarted using the /opt/ascale/bin/atscale_start command.

• If you want to see additional details while running the tool you can use the --help argument.

  /opt/atscale/versions/<NEW_2021.4.X_ATSCALE_VERSION>/bin/installer/database-upgrade.sh --help

Consider that the old /opt/atscale/data/database directory will no longer be used after the AtScale upgrade. It can be removed once everything in the upgraded AtScale is running as expected.