Install Synchronizer using the sync.yml file

The following section describes how to define values for the Synchronizer parameters using the /opt/sync/conf/sync.yml file. This can be done automatically (in simple environments), or manually (in complex environments).

When you are done, run the installation script.

Automatically populate values in simple environments

In simple environments (for example to test the Synchronizer), you can run a script on your ALM Octane server to automatically populate parameters in the /opt/sync/conf/sync.yml file, using default ALM Octane configuration values. The script takes values from the ALM Octane installation files and uses them to populate the Synchronizer parameters with default values.

  1. Run the following command on your ALM Octane server:

    /opt/octane/install/enablesync.sh http://<Synchronizer host>:<Synchronizer port>/

  2. The script generates a sync.yml file. Copy this file to /opt/sync/conf/, replacing the existing sync.yml.

  3. If necessary, edit the values in sync.yml to match your environment, as described in Synchronizer parameter reference.

    For example, the script assumes that Synchronizer is installed in /opt/sync/, and uses port 8080. If you use a different port, edit the corresponding value in sync.yml.

    Note: If you are installing the Synchronizer (on-premises) with version 15.1.20, make sure the that the connectionString parameter in the sync.yml file looks similar to the examples below:

    • jdbc:mercury:sqlserver://dbserver1:1433
    • jdbc:mercury:oracle://db_sever_host:1521;servicename:ORCL

Manually define values in complex production environments

If you are working in a complex production environment including cluster nodes, you must define the /opt/sync/conf/sync.yml parameter values manually.

Fill in the parameters as described in Synchronizer parameter reference.

Note: If you are working in SSO mode, see also Using Synchronizer with SSO.

Install and start the Synchronizer

You can now install the Synchronizer and start the Synchronizer service.

  1. Save a backup copy of the sync.yml file. When you run install.sh in the next step, sensitive data such as passwords are replaced by encrypted values, and the encryption seed is removed from the sync.yml file. If the installation fails, you can restore the backup file and troubleshoot any issues.

  2. Within /opt/sync/install, execute the install.sh script under a desired user. (You may need to set install.sh as executable. )

      Note:
    • Make sure that ALM Octane is running before you execute the install.sh script.

    • If you need to connect to servers over a secure channel, configure trust before executing the install.sh script. For details, see Configure trust.

    If the sudo command is used to run the script as root, make sure the root user has the necessary environment variables set (mainly JAVA_HOME), or use the –E option in the sudo command: sudo -E ./install.sh.

    This runs the setup tool which configures the database, and populates configuration files inside the distribution. It also registers the service as an OS service if executed under root.

  3. Start the Synchronizer service:

    <install_dir>/wrapper/octane-sync start

    Alternatively, run the following:

    service octane-sync start

    To verify success, look at the Synchronizer service logs: /opt/sync/logs/wrapper.log.

    You can also run the following command: tail -f /opt/sync/logs/wrapper.log and wait until you see the message server is ready.

Back to top

Using Synchronizer with SSO

The following procedure enables you to use Synchronizer with SSO. This requires an API key and secret with Site Admin roles.

If you upgrade from an earlier version of ALM Octane, and you previously generated a priory API key and secret, you do not to perform any action.

To use Synchronizer with SSO:

  1. Log in to ALM Octane as a site admin with SSO, and generate an API Access key:

    1. In the Admin Settings section, select a space.
    2. In the Site area, open the API Access tab.
    3. Click + API access.
    4. In the Add API access dialog box, enter a name and description.
    5. Click Add. A popup window indicates that the access was registered. Copy the client ID and secret to the clipboard.
  2. In your sync.yml file, add a new section after the distributed cache section, with a blank line before and after this new section. Copy the following text and enter the corresponding values:

    sp:
        authenticationType: sso
        ssoSpBaseUrl: <AUTHENTICATION_SERVICE_URL>
        ssoOauthClientId: <THE_CLIENT_ID>
        ssoOauthClientSecret: <THE_CLIENT_SECRET>
    

    Note that the values for ssoSpBaseUrl, ssoOauthClientId, and ssoOauthClientSecret must match those in the sso.conf file.

  3. Verify that the fields serviceApiKey and serviceApiSecret in the Integration section contain an API key and secret that have a Site Admin role.

  4. The sso section properties: redirectToAuthPageUrl, master, domain, loginUrl, and logoutUrl can be removed. Do not remove InitString.

Back to top

Next steps: