Change server-specific configuration

Once you’ve deployed the core component kits and any blade kits to the server machines that host your Caplin Platform, you’ll probably need to change the server-specific configuration from the default settings. We explain how to do this here.

In the following steps you’ll be using the dfw command of the Deployment Framework. Before entering any dfw command as ./dfw <command-name>, make sure your current (working) directory is set to the Deployment Framework’s topmost directory.

For a list of dfw commands, click here.
When you’ve changed the configuration of a production system, we recommend that you run the dump command immediately, before restarting the system. The most up-to-date configuration data will then be readily available if Caplin Support need it to help fix a problem with your running system. If you don’t run dump before restarting, you’ll have to stop the running system to get the configuration needed to diagnose a fault, or copy the configuration manually from the various directories where it’s located.

Specify on which servers the core components run

The Deployment Framework requires that every server in your deployment has a full and identical installation of components. Where a core component runs is not decided by where it is installed, but by where it is configured to run. The configuration settings are held in the global/hosts-defn.conf file, but the safest way to change the configuration is by using the command ./dfw hosts

To check what hostnames are configured just run the command ./dfw hosts with no parameters.

You must configure a primary host, and an optional secondary (failover) host, for every core component in your deployment.

  • Liberator

  • Transformer

  • All integration adapters, including permissioning adapters

In a single server deployment, the configured hostname can be set to localhost (which is the default setting), but it’s good practice to always set it to the actual hostname of the server. You can also specify the hostname as the IP address of the server.

Here are some examples of how to change the hostname configuration:

Single server

To specify that Liberator and Transformer should run on myhostname, run the commands below:

$ ./dfw hosts Liberator myhostname
$ ./dfw hosts Transformer myhostname

To specify that adapters should run on myhostname, run the command below for each adapter in your deployment:

$ ./dfw hosts <adapter_blade_name> myhostname

A short cut available to single-server deployments is the blade name 'all'. To specify that all core components run on myhostname, run the single command:

$ ./dfw hosts all myhostname

Multiple servers with no failover

Assume this time that Liberator is on a server machine with hostname myhosta, Transformer is on a different server called myhostb, and there’s a Pricing Adapter blade called myPricingAdapter also on myhostb.

On myhosta, you would configure the host names by entering:

$ ./dfw hosts Liberator myhosta
$ ./dfw hosts Transformer myhostb
$ ./dfw hosts myPricingAdapter myhostb

You can then enter the same commands on myhostb. Alternatively, you could copy the updated file global_config/hosts-defns.conf from myhosta to myhostb, overwriting the version on myhostb (this is quicker and less error prone, especially if you need to update the hostname configuration on several servers).

Multiple servers with failover

Now assume that your Caplin Platform is deployed to two server machines for failover purposes; the primary instances of Liberator, Transformer and the Pricing Adapter run on a machine with hostname myprimaryhost, and the failover (and/or load balancing) instances run on mysecondaryhost.

On myprimaryhost, you would configure the host names by entering:

$ ./dfw hosts Liberator myprimaryhost mysecondaryhost
$ ./dfw hosts Transformer myprimaryhost mysecondaryhost
$ ./dfw hosts myPricingAdapter myprimaryhost mysecondaryhost

You can then enter the same commands on mysecondaryhost. Alternatively, you could copy the updated file global_config/hosts-defns.conf from myprimaryhost to mysecondaryhost, overwriting the version on mysecondaryhost.

More complex failover setup

Here’s a more complex failover configuration: Liberator is deployed to primaryhosta and secondaryhostb, and Transformer and the Pricing Adapter are deployed to primaryhostb and secondaryhostb.

On primaryhosta, you would configure the host names by entering:

$ ./dfw hosts Liberator primaryhosta secondaryhostb
$ ./dfw hosts Transformer primaryhostb secondaryhostb
$ ./dfw hosts myPricingAdapter primaryhostb secondaryhostb

You can then copy the updated file global_config/hosts-defns.conf from primaryhosta to secondaryhosta, primaryhostb and secondaryhostb, overwriting the version on each destination machine.

Change configuration macros

The configuration of a server component’s environment is defined by macros in the file global_config/environment-defaults.conf. These macros determine such things as Liberator’s HTTP and HTTPS port numbers; Liberator and Transformer’s DataSource IDs; DataSource port numbers; JMX port numbers; and Java environment settings. You should review the macro definitions in this file and decide which, if any, of these definitions need to be changed for your deployment. For a list of the configuration macros that can be used in environment-defaults.conf, and the configuration items that they set, see Configuration macros and items.

To override a default configuration setting, copy the corresponding macro from global_config/environment-defaults.conf to global_config/environment.conf and update its value there. The environment.conf file includes the environment-defaults.conf file, so add your overriding macros after the line where environment-defaults.conf is included.

In a multi-server deployment, you can edit and save global_config/environment.conf on one server machine and then copy it to the Deployment Framework on each of the other server machines.

Don’t change the settings in global_config/environment-defaults.conf.
You can define a configuration macro in global_config/environment.conf multiple times, but only the last definition is effective.

See Configuration macros and items for a full list of configuration macros you can change. As an example, here are two of the macros you may need to change:

  • Java Virtual Machine location

  • Liberator’s HTTP and HTTPS port numbers

Java Virtual Machine location

If Java-based features are activated (for example, the LiberatorJMX blade), Liberator attempts to load a Java Virtual Machine (JVM) when it starts up. Liberator looks for a JVM relative to the path in the JAVA_HOME environment variable. For help in setting the JAVA_HOME environment variable on Microsoft Windows, Red Hat Linux, and Mac OS, see Installing Java.

If the JVM is in a non-standard location in relation to the path defined in JAVA_HOME, you will need to supply the Deployment Framework with the full path to a JVM. To specify the full path to the JVM, use the ./dfw java command from the command line.

The ./dfw java command sets the value of the JVM_LOCATION value in global_config/environment.conf . If you copy global_config/environment.conf to other servers in a multi-server deployment, check that the value of JVM_LOCATION is correct for these servers too.

Liberator’s HTTP and HTTPS port numbers

Search environment-defaults.conf for all configuration macros that have names containing the text PORT. These macros specify port numbers that must be available on the server machine where the Platform component runs. Here’s an example of the port number definitions for Liberator’s HTTP and HTTPS connections.

...
#
# http/https definitions
#
define LIBERATOR${THIS_LEG}_HTTPPORT                    ${THIS_LEG}8080
define LIBERATOR${THIS_LEG}_HTTPSPORT                   ${THIS_LEG}8081
...

Asuming THIS_LEG is defined as 1, the macro LIBERATOR1_HTTPPORT is set to 18080, and the macro LIBERATOR1_HTTPSPORT is set to 18081.

If ports 18080 and 18081 are not available on the server machine on which the Liberator runs, you would define these macros in environment.conf to set port numbers that are available on that server, such as ${THIS_LEG}8090 and ${THIS_LEG}8091.

For more about this, see How can I…​ Change Liberator and Transformer port numbers.

Consult your system administrator if you don’t know what port numbers are available on a particular server machine.

Override other component configuration

In addition to the Liberator and Transformer environment settings in global_config/environment.conf, the directory global_config/overrides contains writeable configuration files that override other configuration settings for core components and blades. For example, the Liberator and Transformer kits come with override files in

  • global_config/overrides/servers/Liberator/etc/

  • global_config/overrides/servers/Transformer/etc/

You can edit these files as required. For example, say you want increase the Liberator’s logging level from the default of INFO to DEBUG. You would change the log-level configuration item in global_config/overrides/servers/Liberator/etc/rttpd.conf to

log-level DEBUG

Another example is the Liberator’s license file location, which you can override by setting the license-file configuration item in the rttp.conf overrides file.

See also: