# On Premise to On Premise In-place Upgrade Procedures

## From Clarity LIMS Version 6.2 to 6.3

This section provides the steps required to upgrade an existing on-premise deployment of Clarity LIMS v6.2 to a RedHat Enterprise Linux/Oracle Linux compatible on-premise deployment of Clarity LIMS v6.3.

For installation requirements, see [technical-requirements](https://help.claritylims.illumina.com/clarity-lims-v6.3-and-lablink-v2.5/technical-overview/technical-requirements "mention").

If you have questions about the upgrade procedure, contact the Illumina Support team.

### Migration Paths

The following table shows the applicable migration paths.

| From                                     | To              | Notes |
| ---------------------------------------- | --------------- | ----- |
| <p>PostgreSQL:</p><p>v6.2 On-premise</p> | v6.3 On-premise | -     |

### **Prerequisites**

Before proceeding with the in-place upgrade from Clarity LIMS v6.2 to v6.3, note on the following:

* Your system must meet the requirements listed in [technical-requirements](https://help.claritylims.illumina.com/clarity-lims-v6.3-and-lablink-v2.5/technical-overview/technical-requirements "mention").
* All standard operating system (OS) security updates must have been applied.
* The command **hostname -f** must resolve to the fully qualified domain name (FQDN) of the server. For details, see the [#confirm-hostname-resolution](https://help.claritylims.illumina.com/clarity-lims-v6.3-and-lablink-v2.5/pre-installation-requirements#confirm-hostname-resolution "mention") section of [pre-installation-requirements](https://help.claritylims.illumina.com/clarity-lims-v6.3-and-lablink-v2.5/on-premise-deployments/pre-installation-requirements "mention").
* Make sure that all standard OS security updates have been applied.
* Make sure that all user accounts have email addresses associated with them. Users must reset their passwords after the upgrade.

### **Upgrade Pre-validation**

To assist with validating the system before an upgrade, install the **UpgradePreValidation** RPM on the **existing server**.

* This RPM is installed temporarily, and provides tools to help check the system before an upgrade.
* If validation is successful, you can remove this RPM and proceed with the upgrade.

1. Install the **UpgradePreValidation** RPM.
   * As the **root** user, run the following command:

     ```
     yum --enablerepo=GLS_Clarity63 install ClarityLIMS-UpgradePreValidation
     ```
2. \[Optional] Set up Secret Utility.
   * If ClarityLIMS-SecretUtil was installed previously, run the following command to set up Secret Utility as the **glsjboss** user:

     ```
     ./opt/gls/clarity/config/pending/05_configure_claritylims_secretutil.sh
     ```

     **NOTE**: Using a vault is the safer way of storing application secrets. If using a vault is not possible, the configuration script supports file-based storage.

     For more information on the prompts, see [#configuration-script](https://help.claritylims.illumina.com/clarity-lims-v6.3-and-lablink-v2.5/installation/guide-to-secret-management#configuration-script "mention") section of [guide-to-secret-management](https://help.claritylims.illumina.com/clarity-lims-v6.3-and-lablink-v2.5/installation/guide-to-secret-management "mention").
3. Run the validation script as follows.
   1. Make sure that the Clarity LIMS server is running.
   2. As the **root** user, run the following command:

      ```
      bash /opt/gls/ClarityUpgradeValidation/bin/validate.sh
      ```
   3. Review the output of the script to determine if you can proceed with the upgrade. If the script outlines any issues with the potential upgrade, review the generated log files and contact the Illumina Support team for further assistance.
4. Remove the **PreValidation** RPM.

   Remove the **PreValidation** RPM only after you confirm that you can upgrade. If you are unsure, consult the Illumina Support team.

   * As the **root** user, run the following command:

     ```
     yum remove ClarityLIMS-UpgradePreValidation
     ```

### **Upgrade steps**

1. [#shut-down-clarity-lims-components](#shut-down-clarity-lims-components "mention")
2. [#backup-the-database-and-clarity-lims](#backup-the-database-and-clarity-lims "mention")
3. [#upgrade-clarity-lims-components](#upgrade-clarity-lims-components "mention")
4. [#install-or-upgrade-lablink](#install-or-upgrade-lablink "mention")
5. [#Reinstall-Clarity-LIMS-Integration:Sequencer-API-RPM](#Reinstall-Clarity-LIMS-Integration:Sequencer-API-RPM "mention")
6. [#upgrade-postgresql-database-server](#upgrade-postgresql-database-server "mention")
7. [#start-the-clarity-lims-services](#start-the-clarity-lims-services "mention")
8. [#optional-upgrade-clarity-lims-integrations](#optional-upgrade-clarity-lims-integrations "mention")
9. [#check-clarity-lims-components](#check-clarity-lims-components "mention")
10. [#validate-the-installation](#validate-the-installation "mention")

#### **Shut Down Clarity LIMS Components**

1. Determine if any of the remote automation workers (AI nodes) are running.
   * As the **glsjboss** user, run the following command:

     Substitute the variables as appropriate for the specific environment.

     Copy

     ```
     java -jar /opt/gls/clarity/tools/ai-monitor/ai-monitor.jar -u <apiuser> -p <password> -i https://<apihost>/api/ -n
     ```
   * Make a note of any remote automation workers, and let them complete their current commands.

     **NOTE**: As of Clarity LIMS v5, the term **AI node** has been replaced with **automation worker**.
2. Stop any and all integration services.
   * Find all the integration services and stop them, as described in the integration documentation.
3. Shut down the Clarity LIMS services.
   * As the **root** user, run the following command:

     Copy

     ```
     /opt/gls/clarity/bin/run_clarity.sh stop
     ```

     * If a service is already stopped, it will be ignored.
     * If any service fails to stop, the script will exit and no further services will be stopped.

{% hint style="info" %}
Any Clarity LIMS components still running should be shut down. Use the following commands to force stop these components if the previous commands did not lead to Tomcat stopping.

**Tomcat**

1. Check if there is a need to force stop the tomcat application:

   `pgrep jsvc`
2. As the **root** user, force stop the **tomcat** processes:

   `pkill jsvc`
   {% endhint %}

#### **Backup the Database and Clarity LIMS**

1. Back up Postgresql database:

   On the PostgreSQL server, best practice recommends backing up the database using the **pg\_dump** utility.

   The following example assumes the following:

   * The database server and the application server are on the same server.
   * The **pg\_dump** utility is accessible to the **glsjboss** user.

     ***Example***

     The Postgres DBA uses the following commands to create a database backup in the **glsjboss** home directory. Substitute the variables as appropriate for the specific environment.

     * As the **glsjboss** user:

       ```
       cd ~glsjboss
       mkdir -p backups/database
       pg_dump -U <database_user> -b -Ft <database_name> -f ~glsjboss/backups/database/clarity-old_version-`date +%Y%m%d%H%M`.tar
       ```
2. Backup Clarity LIMS
   * On the Clarity LIMS server, back up the contents of the folder **/opt/gls/clarity/glscontents/.**
   * As the **glsjboss** or **root** user run the following commands:

     ```
     cd ~glsjboss
     mkdir -p backups/clarity
     tar czf ~glsjboss/backups/clarity/glscontents-old_version-`date +%Y%m%d$H$M`.tar.gz /opt/gls/clarity/glscontents/
     ```

#### **Upgrade Clarity LIMS Components**

1. As the **root** user, run the following command:

   ```
   yum --enablerepo=GLS_Clarity63 update "ClarityLIMS-App"
   ```
2. As the **glsjboss** user, run the following command:

   ```
   /opt/gls/clarity/config/configuration_test.sh
   ```

   * This script analyzes the system and lists any required configuration steps. Make sure to carefully apply the instructions provided in the output of the scripts.

     ***Example:***

     ```
     As root run the sequence
     su - glsjboss -c /opt/gls/clarity/config/pending/27_update_claritylims_platform.sh
     su - glsjboss -c /opt/gls/clarity/config/pending/28_update_claritylims_tenant.sh
     /opt/gls/clarity/config/pending/32_root_configure_rabbitmq.sh
     /opt/gls/clarity/config/pending/33_root_configure_elasticsearch.sh
     /opt/gls/clarity/config/pending/40_root_install_proxy.sh
     ```

   **NOTE**: Update **/opt/gls/clarity/tomcat/current/lib/activity-management-ui-config.groovy** If your database server is standalone or remote. Use the following code snippet:

   ```
   multiTenantDataSource {
     urlTemplate="jdbc:postgresql://<Replace me: Remote DB IP>:<Replace me: Remote DB Port>/{0}"
     ... other properties ...
   }

   ... other properties ...

   dataSource {
     ... other properties ...
     url="jdbc:postgresql://<Replace me: Remote DB IP>:<Replace me: Remote DB Port>/{tenantLookupDB}"
   }    
   ```
3. Check that all scripts have been run. As **glsjboss** user run any that are remaining:

   ```
   su - glsjboss -c /opt/gls/clarity/config/configuration_test.sh
   ```

#### **Install or Upgrade LabLink**

LabLink v2.5 is compatible with Clarity LIMS v6.3.

**Install LabLink 2.5**

**NOTE**: This step is only required if installing Lablink for the first time.

Before completing the following steps, make sure that a database named lablink is created with the same database user as Clarity LIMS database.

1. Install the **LabLink** RPM. Make sure that you have the correct repo enabled.
   * On the instance, as the **root** user, run the following command:

     ```
     yum --enablerepo=GLS_Clarity63 install ClarityLIMS-LabLink
     ```
2. Run the pending initialization script.
   * As the **glsjboss user**, run the following command:

     ```
     bash /opt/gls/clarity/config/pending/60_initialize_lablink.sh
     ```
3. The script prompts for a Google reCAPTCHA URL, site key, and secret key.
   * Google reCAPTCHA URL: <https://www.google.com/recaptcha/>
   * Google reCAPTCHA site key and secret key: View these keys from the Google **reCAPTCHA Admin Console**, under **Settings**.

     **NOTE**: If you prefer not to use reCAPTCHA, leave the site-key and secret-key fields blank when running the configuration script. LabLink does not display the reCAPTCHA when these fields are left blank. You can also use your own reCAPTCHA accounts when configuring LabLink.
   * To reconfigure LabLink (without initializing the database), run the following command as the **glsjboss** user:

     `bash /opt/gls/clarity/config/configure_lablink.sh`

**Upgrade LabLink 2.5**

Lablink must be upgraded to the latest version if there is an order version installed.

Upgrade the **LabLink** RPM. Make sure that you have the correct repo enabled.

On the instance, as the **root** user, run the following command:

```
yum --enablerepo=GLS_Clarity63 update ClarityLIMS-LabLink
```

#### **Reinstall Clarity LIMS Integration: Sequencer API RPM**

**NOTE**: This step is only required if **BaseSpaceLIMS-sequencer-api** RPM is installed on the server. The RPM needs to be re-installed to resolve a known issue for version 6.3.

Run the following command to identify if the Sequencer API RPM is installed:

```
yum list installed | grep BaseSpaceLIMS-sequencer-api
```

Use the following command to reinstall the Sequencer API RPM. Make sure that the same version is being reinstalled.

```
yum --enablerepo=GLS_Clarity63 reinstall BaseSpaceLIMS-sequencer-api
```

#### **Upgrade PostgreSQL database server**

Upgrade your PostgreSQL database server to v15.6. Consult a DBA to perform the upgrade.

#### **Start the Clarity LIMS services**

Use the **run\_clarity.sh** script to start all services in the required order as follow:

* Elasticsearch
* RabbitMQ
* Search Indexing
* Tomcat
* httpd/Apache proxy
* AI in the required order

As the **root** user, run the following command:

```
/opt/gls/clarity/bin/run_clarity.sh start
```

* After the script has completed, all Clarity LIMS services should be ready for use.

#### **\[Optional] Upgrade Clarity LIMS Integrations**

**NOTE:** This step is required only if Integration is needed.

Start the integration services.

* Find all the integration services and stop them, as described in the integration documentation.

#### Check Clarity LIMS Components

1. Determine the components that are running.

   * As the **glsjboss or root** user, run the following command:
     * Tomcat:

       ```
       ps -ef | grep jsvc
       ```
     * Automation workers:

       ```
       ps -ef | grep automat
       ```
     * Sequencing services:

       ```
       ps -ef | grep seq
       ```

   Take note of the component that is running.
2. \[Optional] Restart remote automation workers.
   * Manually restart each of the remote automation worker from its local machine.

#### Validate the Installation <a href="#validate-the-installation" id="validate-the-installation"></a>

1. Log in to Clarity LIMS.
2. Make sure that Clarity LIMS is operating by performing your own validation steps.