Testing upgrades on a cloned virtual machine

You can perform a test upgrade of your production server that is hosted on a virtual machine (VM).


  1. Stop the production server.
  2. Stop the production VM.
  3. Clone the production VM.
  4. Clone the database:
    Contact your database administrators (DBAs) to clone the database. Your DBA must backup the existing database and restore it to a new database that can be accessed from the newly cloned HCL Launch server. If more assistance is needed than your DBA can provide, use your support case for assistance.
  5. Clone the application data (appdata) folder:
    The location of your appdata is defined by the server.appdata.dir property in the server's installed.properties file.
    Most application data folders are mount points to an external file system. If your application data folder is external to the HCL Launch server, clone the application data folder. Point your cloned HCL Launch server to the cloned application data folder to avoid using the application data folder of your production server.
    If your application data folder is large and you do not want to clone it for your test environment, you can skip cloning the application data folder and start a new one. If you chose not to clone the application data folder, no production component versions can be used nor can you view any production step output (both are stored in the application data folder). New component versions must be created to deploy.
    If you choose not to clone the application data folder, copy the other application data folder files like:
    • Custom email notification templates, if you want to test them after you upgrade the clone.
    • The plug-ins directory.
    • If you want to verify the clone's health before you perform an upgrade, copy the patches. During an upgrade, HCL Launch turns off any patches by appending ".off" to the patch name.
  6. If HCL Launch is configured to use S3 storage, which is available starting with v7.0.5, clone the S3 bucket if you want to use the same component versions artifacts as the production server.
    Note: You can skip this step if you prefer to create new component version artifacts.
  7. Start the production VM.
  8. Start the production server.
  9. Start the cloned VM.
  10. Modify the cloned database.
    1. For high availability (HA) configurations only:
      Remove the web cluster configuration from the database, if applicable, by deleting all the contents of the ds_server table. If you need assistance deleting the contents, contact your DBA.
      Note: Versions prior to 7.0.0 do not have a ds_server table.
    2. To stop automatic component version imports, run the following SQL to update the components in the database:
  11. Modify the appropriate property values in the clone’s installed.properties (and secured-installed.properties file in newer versions) file.
    The following properties must be modified to the values that are appropriate for the cloned server:
    Property Description
    hibernate.connection.url The URL of the cloned database.
    hibernate.connection.username The username used to access the cloned database.
    hibernate.connection.password The password of the user used to access the cloned database.
    Note: The password is stored in plain text until the cloned server is started. After the cloned is successfully started, the password is encrypted. In later versions of HCL Launch, this value is stored in the secured-installed.properties file.
    server.external.web.url The URL of the cloned server.
    install.server.web.host The hostname of the cloned server.
    server.appdata.dir The location of the cloned application data folder.
    agentcomm.uri Update the hostname with the clone's name.
    encryption.keystore.alias Update only if you copied the encryption.keystore from production to the clone. Set it to the same value as the production server's value.

    If you are using S3 storage, you might have to modify the S3 storage properties, or ensure they are correct for your cloned S3 bucket:

  12. Start the clone server.
    Note: Use the machine IP address to access the HCL Launch UI for the next step.
  13. Make additional changes to the clone.
    1. Click Settings > System Settings from the web UI:
      • Set the External Agent URL and External User URL.

      • Remove the Mail Server Settings information.

    2. Delete any scheduled jobs from the calendar.
    3. Create new agents for testing.
      Although production agent information exists in the cloned database, the production agents show offline in the clone because the agents are configured to connect only to the production server. To test deployments after you upgrade, you have to create new agents for the cloned environment.
    4. To license the clone, contact your HCL sales representative to obtain a temporary license.