Skip to main content

Distributed deployment of Contrast

A distributed configuration of Contrast deploys the database and application server to separate servers. Use a distributed configuration if you:

  • Plan to use more than 100 connected agents

    Without a distributed configuration for this situation, you are likely to experience performance issues.

  • Want to use load-balancing for better performance and scalability

  • Require additional administration and management

Distributed configuration example

This example shows a configuration for installing Contrast in a Linux environment at /usr/local/contrast. Your organization may use different environments or have different guidelines on where to install third-party software.

The example shows a configuration using these servers:

  • A load-balancer

  • A database server

  • Two application servers running the Contrast application.

    You can more servers, as needed.

DistributedDeploymentContrast__7_.png

Before you begin

  • Distributed deployment requires an understanding of your environment and the loads it can easily handle.

    To determine whether it's best to use a distributed deployment of Contrast or a dedicated instance, contact Support.

  • If you are already using Contrast, use your existing instance as Application Server 1 and be sure it uses a distributed database configuration. Before you continue, you should:

    • If you don't already have one, create a distributed MySQL environment.

    • Determine the version of Contrast running on Application Server 1 by looking at the contents of the $CONTRAST_HOME/VERSION file.

    • If the installer you plan to use to create Application Server 2 is using a higher version of Contrast than Application Server 1, you must first upgrade Application Server 1 to the same version.

  • If you are new to Contrast, you should:

    • Install and configure MySQL on the database server, as described in steps 1 through 8 in Create a distributed MySQL environment.

    • Install Contrast on Application Server 1 with a distributed database configuration. For example:

      Choose a MySQL database configuration.
Default [1, Enter], Distributed [2]2
Host
[localhost]
<enter hostname of MySQL server>

Port
[13306]
<enter port to be used to access MySQL server - usually 3306>

Credentials
Username
<enter name of MySQL user that was created for Contrast>

Password
<enter password for MySQL user>

Set up distributed servers

  1. Copy the following files from Application Server 1 to a temporary location on Application Server 2:

    • $CONTRAST_HOME/data/conf/server.properties

    • The associated Server KeyStore file if you configured Application Server 1 for HTTPS.

  2. If you configured Single Sign On (SSO) on Application Server 1, complete these steps:

    1. Run the encrypted properties editor against $CONTRAST_HOME/data/conf/saml.properties to retrieve the configured values. Enter q at the prompt (you aren't changing any values). For example:

      $ bin/edit-properties -e data/esapi/ -f data/conf/saml.properties

authenticator.saml.keystore.default.key           : some_alias
authenticator.saml.secret.url                     :
authenticator.saml.keystore.path                  : /path/to/samlKeystore.jks
authenticator.saml.keystore.password              : changeit
authenticator.saml.keystore.passwordMap           : some_alias=changeit

Enter the name of the property to edit [q to Quit]: q

    2. Create a new file named saml.properties.cleartext containing the values you retrieved above, but formatted with an = replacing the :, for example:

      authenticator.saml.keystore.default.key=some_alias
authenticator.saml.secret.url=
authenticator.saml.keystore.path=/path/to/samlKeystore.jks
authenticator.saml.keystore.password=changeit
authenticator.saml.keystore.passwordMap=some_alias=changeit

    3. Copy the associated SAML KeyStore from Application Server 1 to a temporary location on Application Server 2.

  3. Install Contrast on Application Server 2 with the same distributed configuration that you used for Application Server 1.

  4. When the installation has completed, stop the Contrast Server on this Application Server.

  5. Place the server.properties file, the associated Server Keystore, the saml.properties.cleartext file and the associated SAML KeyStore (where applicable) in the same directories on Application Server 2 (usually $CONTRAST_HOME/data/conf/)

  6. Start the Contrast Server on Application Server 2.

  7. Test the default users created by the application to be sure they work with both Contrast Application Servers (1 and 2).

  8. Set up a load balancer (like NGINX) on the fourth server. If you choose NGINX, use the basic installation instructions.

    Note

    Contrast requires sticky or persistent sessions for better performance. For example, with an NGINX load balancer, use the Ip Hash method to guarantee that requests from the same address get to the same server if it’s available.

  9. Once you set up the server, you must configure Contrast to point to your load balancer. To do this, edit the /data/conf/general.properties file on each node. Change the teamserver.url value in the YAML config file to that of the load balancer and restart the Contrast application server.

    If you are doing health checks for the load balancer, use this URL:

    <CONTRAST_SERVER>/Contrast/api/public/ng/information

    where <CONTRAST_SERVER> is the host name of the Contrast application server.

    Important

    Agents use the Contrast URL to communicate back to the application. Contrast attempts to determine the hostname and pre-populate this value. If clients on the network can't resolve the hostname you provide, they won't communicate back to the server. Please set this value to a Contrast host or load balancer that the agent hosts can reach.

    When installation is complete, Contrast begins an initial configuration. It can take two to three minutes to fully start up.

  10. To check configuration progress, watch server.log and contrast.log. When the server successfully starts, you will see something like this in server.log:

    260916 20.18.25,837 {} {} {} INFO  (Server.java:303) Contrast TeamServer Ready -
In this section: