Service definition

Every application must have a *-service-definitions.xml file. This is where you specify the ports of the various processes. These are used to communicate internally between processes.

<configuration>
  <service host="localhost" name="GENESIS_CLUSTER" port="8510"/>
  <service host="localhost" name="GENESIS_WEBMON" port="8511"/>
  <service host="localhost" name="GENESIS_WEB_ADAPTER" port="8512"/>
</configuration>

By default, this file is located in the cfg folder.

After genesisInstall

As part of the build process, or when genesisInstall is executed, your application's -service-definitions.xml file is compiled into a system-wide $GC/global-service-definitions.xml.

Here is an example of a global-service-definitions.xml file where we have the auth, genesis and gcom products installed:

<configuration>
  <service external="false" host="localhost" name="GENESIS_AUTH_DATASERVER" port="8502" secure="false"/>
  <service external="false" host="localhost" name="GENESIS_AUTH_MANAGER" port="8501" secure="false"/>
  <service external="false" host="localhost" name="GENESIS_AUTH_PERMS" port="8503" secure="false"/>
  <service external="false" host="localhost" name="GENESIS_CLUSTER" port="8510" secure="false"/>
  <service external="false" host="localhost" name="GENESIS_WEBMON" port="8511" secure="false"/>
  <service external="false" host="localhost" name="GENESIS_ROUTER" port="8512" secure="false"/>
  <service external="false" host="localhost" name="GCOM_DATA_SERVER" port="8570" secure="false"/>
  <service external="false" host="localhost" name="GCOM_REQUEST_SERVER" port="8571" secure="false"/>
</configuration>

If the process lives on a different server, then set the external attribute to "true". For example:

<configuration>
  <service host="hostname" name="GENESIS_CLUSTER" port="8510" external="true"/>
</configuration>

Enabling SSL for processes

To enable SSL for a process, set the secure attribute to "true" on the process in the -service-definitions.xml file. For example:

<configuration>
  <service host="localhost" name="GCOM_REQUEST_SERVER" port="8571" secure="true"/>
</configuration>

You must also edit the genesis-system-definition.kts file, as specified in the example below:

systemDefinition {
  global {
    item(name = "DefaultKeystoreLocation", value = "/home/applicationName/keystore.jks")
    item(name = "DefaultKeystorePassword", value = "Password123")
    item(name = "DefaultCertificate", value = "/home/applicationName/certificate.crt")
  }
}

warning

The global-service-definitions.xml file and the processes.xml file are are erased and re-generated every time you run genesisInstall. (You should never change the generated files, because any changes will be lost the next time you run genesisInstall.)

Therefore, it is essential that you set the *-service-definitions.xml file this way for every service or module for which you want to enable SSL.

Overriding ports at runtime

The ports that each service uses can be overridden at runtime with an environment variable.

This is particularly useful when you want to run a single build across multiple environments that have different port requirements (i.e. multiple apps running on a single host).

To override the port, just use the environment variable {PROCESS_NAME}_PORT={PORT}.

So for example, if you wanted the GENESIS_ROUTER to run on port 22222 you would use GENESIS_ROUTER_PORT=22222.

This guide doesn't cover how to use environment variables, but there are many guides online such as How to Set an Environment Variable in Linux that explain how they work.

API

In this page, we look at details of the functions that enable you to interact with the Genesis services that can be specified in the *-service-definition.xml file.

Functions

Name	Signature	Description
getServiceDetails	@NotNull ServiceDetails getServiceDetails(String processName) throws GenesisConfigurationException	Get service details for a given process name.
getServiceMap	Map<String, ServiceDetails> getServiceMap() throws GenesisConfigurationException	Get services map with: key = serviceName, value = details
getServices	List<ServiceDetails> getServices() throws GenesisConfigurationException	Get list of services.
getStartedServices	List<ServiceDetails> getStartedServices() throws GenesisConfigurationException	Get list of started services.