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.


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.

    • Get Contrast application version numbers by looking in the VERSION file in /usr/local/contrast/VERSION . Get the Contrast database version using this command:

      select `version` from schema_version ORDER BY `installed_on` DESC LIMIT 1;

      You need the version numbers to determine the order of tasks.

      For example, if the application version is 3.3.2 and the database is version, you can say the versions are the same because it's safe to drop .012 from the database version number. Because of this, an existing application server A can run with a separate database B on version 3.3.2. If you want to install application version 3.4.2 onto a new application server C and connect it to database B, you will need to either stop or update server A before installing version 3.4.2 on server C.

  • If you are new to Contrast, you should:

  • Install and configure MySQL on the database server according to Contrast system requirements. Create a MySQL user who has permissions to connect remotely. You will use these credentials to connect to Contrast.

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

  • Select the option for a distributed MySQL instance. Point the database creation to the database server, for example:

    Choose a MySQL database configuration.
    Default [1, Enter], Distributed [2]2
    <enter hostname of Mysql server>
    <enter mysql password for contrast account>

Set up distributed servers

  1. Create a TAR file from the Application Server 1's configuration files:

    • data/conf/

    • data/esapi/

    • data/contrast

    • data/initialized

    • data/contrast/lic

    • webapp/Contrast.war


    Use a command similar to the following example:

    $ cd /usr/local/contrast
    $ tar -czvf ~/ctdc.tar.gz data/agents data/conf data/contrast.lic data/esapi/ data/.initialized data/.contrast webapp/Contrast.war/.contrast VERSION
  2. Install Contrast on Application Server 2.

    Complete the installation process as a privileged user.

    • On Windows, right-click on the installer and select Run as administrator.

    • On Linux, use a sudo command to launch the installer.


    Full or Application Only Install
    Choose the desired installation type:
    Full install [1, Enter], Application Server Only [2]

    Select Application Server Only and use the TAR file you created in the previous step. Do the same for any additional application servers you want to add to the distributed configuration.

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

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


    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.

  5. Once you set up the server, you must configure Contrast to point to your load balancer. To do this, edit the /data/conf/ 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:


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


    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.

  6. 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  ( Contrast TeamServer Ready -