Creating and customizing runtime servers

Use the server create command to create your runtime servers. You must then edit the bootstrap.properties and server.xml files to specify port numbers, the catalog endpoints, and define your security (keystore, user registry, server administration authorization roles, and authorization roles for the REST API). Use the objectGridDeployment.xml file to set grid replicas and partitions.

1. Open a command window and go to the <InstallDir>/runtime/wlp/bin directory.
2. Create a runtime server by running the server create command.

   For example, on Windows:

   server create runtimeServer1 --template=cisContainer

   For example, on Linux®:

   ./server create runtimeServer1 --template=cisContainer

   Where:

   runtimeServer1 is the name of the server that you want to create.

   cisContainer is the name of the template.

3. Repeat steps 1 and 2 until all of the runtime servers in your topology are created.
4. Open the <WLP_USER_DIR>/servers/server_name/server.xml file in a suitable editor.
   1. Add the basic or LDAP user registry configuration.

      <basicRegistry id="basic" realm="SimpleRealm">
         <user name="SimpleAdmin" password="abcdefg"/>
         <group name="SimpleAdministratorsGroup">
            <member name="SimpleAdmin"/>
         </group>
      </basicRegistry>

      For more information, see LDAP with Liberty profile.

   2. Configure an administrator role for server administration.

      <administrator-role>
         <group>SimpleAdministratorsGroup</group>
      </administrator-role>

   3. Configure authorization roles for the REST API.

      
      <authorization-roles id="iaAuthorization">
         <security-role name="iaRESTWriter">
            <group name="SimpleAdministratorsGroup"/>  
         </security-role>
         <security-role name="iaRESTReader">
            <group name="SimpleReviewersGroup"/>  
         </security-role>
      </authorization-roles>

5. Add the relevant catalog server host name and port values to the elasticCacheCatalogCluster element.
   The server.xml file contains a TODO comment with a list of three host names for the computers where the catalog servers are launched. Uncomment the lines and replace the template values with your own server values. The following example lists three catalog server host names all with a port value of 2809.

   
   <server host="CATALOG01" port="2809"/>
   <server host="CATALOG02" port="2809"/>
   <server host="CATALOG03" port="2809"/>

6. Open the<WLP_USER_DIR>/servers/server_name/jvm.options file in a suitable editor.
   The maximum memory allocation setting for Xmx and Xms is set to 28 gigabytes (28G). Modify this value to suit your environment.

   Note: If Xmx is modified, Xms must be the same or lower than Xmx.
7. Optional: Open the <WLP_USER_DIR>/servers/server_name/jvm.options file. The -XX:MaxDirectMemorySize option sets a limit on the amount of memory that can be reserved for all Direct Byte Buffers. Where size is the limit on memory that can be reserved for all Direct Byte Buffers. The default value is 1024m, modify this value to suit your environment.
8. Open the <WLP_USER_DIR>/servers/server_name/grids/objectGridDeployment.xml file in a suitable editor.

   Table 1. Object grid settings

   Setting	Description
   developmentMode	Set developmentMode to false in production or realistic testing environments.
   maxAsyncReplicas	Asynchronous partition replicas allow the system to recover quickly in an HA/CA situation. Set the value to 1 for HA or 0 for non-HA. The number of asynchronous replicas is automatically reduced for small clusters.
   maxSyncReplicas	Synchronous partition replicas allow the system to handle HA/CA situations without losing data. maxSyncReplicas is set to the number of hosts, which you can lose at the same time, and still not lose data. Set the value to 1 for HA. Setting it higher incurs significant extra overhead. The number of synchronous replicas is automatically reduced for small clusters.
   minSyncReplicas	Always set the value to 0 for HA, so that the system can run, even if you have no replica.
   numInitialContainers	numInitialContainers is the number of servers that are required for the system to start. A good HA value is one less than the number of servers in your cluster (a value of 3 is adequate for most HA clusters), but it must be set lower for clusters with 1 or 2 servers.
   numberOfPartitions	Calculate the value for numberOfPartitions by adding up all the cores (CPUs) in the cluster, double it and then round it up to the next prime number. For example, if you start with 4 16-cores, but you think that eventually you might need 8, set numberOfPartitions to 257.
   writeBehind	If you have a DBMS that is HA, add the writeBehind parameter to the iaMaps mapSet and set the value to T20;C200. Asynchronous write-behind is better for performance. Because of the in-memory redundancy, data integrity is not an issue with a write-behind policy, except when the DBMS becomes inaccessible. If a DBMS becomes inaccessible, shut off inbound events before you shut down the entire cluster. In a low-volume non-high availability (HA) topology, or if you are concerned about whole-site loss, you can remove the writeBehind parameter and keep the backing database synchronously up-to-date.

   1. Specify the maximum number of synchronous replicas for each partition in the map set.
      Set maxSyncReplicas to a value greater than 0 to support high availability. Set the value to the maximum number of servers that can be lost simultaneously, while still maintaining high availability. The recommended value for maxSyncReplicas is 1. Setting maxSyncReplicas to a value that is higher than 1 has a large impact on processing performance and memory capacity requirements. Make sure to set the maxSyncReplicas attribute to the same value in every mapSet element.
   2. Specify the maximum number of asynchronous replicas for each partition.
      Asynchronous replicas of each partition can help the system recover more quickly from the loss of a server. However, asynchronous replicas can be detrimental if you have a few hosts. If you have 4 or more runtime servers in your topology, the recommended value for maxAsyncReplicas is 1. If you have 3 or fewer runtime servers in your topology, the recommended value for maxAsyncReplicas is 0.
   3. Optional: Specify the number of partitions for the map set. This number must remain fixed.
      Set the numberOfPartitions attribute of the mapSet element for iaMaps and iaPreloadMaps.

      Set the value so that it is appropriate for the anticipated capacity of your data grid; include projected growth requirements. If you plan to expand, specify a greater value. The value can be calculated by using the following formula.

      the number of runtime servers x the number of cores per server x 2

      Round the result up to the next prime number. For example, if you have five high-capacity servers with 16-core processors each and expect to double your capacity later, an optimum value is 10 x 16 x 2 = 320. Then, round the value up to the next prime, which is 331.

      Do not modify the objectGridDeployment.xml file while the cluster is active. For more information about sizing your grid to match your scaling requirements, see Scalability overview in the WebSphere® eXtreme Scale documentation.

      The following extract of objectGridDeployment.xml shows an eXtreme Scale configuration for a non-High Availability (HA) Insight Server on a single host, where the number of partitions is the total number of runtime servers (1) multiplied by the number of cores, times two, and then rounded up to the next prime number.

      
      <objectgridDeployment objectgridName="com.ibm.ia">
         <mapSet name="iaMaps" 
                 numberOfPartitions="19" 
                 numInitialContainers="1" 
                 minSyncReplicas="0" 
                 maxSyncReplicas="0" 
                 maxAsyncReplicas="0" 
                 developmentMode="false">     
          ...   
         </mapSet>
      </objectgridDeployment>
      <objectgridDeployment objectgridName="com.ibm.ia.preload">
         <mapSet name="iaPreloadMaps" 
                 numberOfPartitions="19" 
                 numInitialContainers="1" 
                 minSyncReplicas="0" 
                 maxSyncReplicas="0" 
                 maxAsyncReplicas="0" 
                 developmentMode="false">
          ...
         </mapSet>
      </objectgridDeployment>
      ...

      The following extract of objectGridDeployment.xml shows an eXtreme Scale configuration for a HA Insight Server topology.

      
      <objectgridDeployment objectgridName="com.ibm.ia">
         <mapSet name="iaMaps" 
                 numberOfPartitions="131" 
                 numInitialContainers="3" 
                 minSyncReplicas="0" 
                 maxSyncReplicas="1" 
                 maxAsyncReplicas="1" 
                 developmentMode="false">    
          ...   
         </mapSet>
      </objectgridDeployment>
      <objectgridDeployment objectgridName="com.ibm.ia.preload">
         <mapSet name="iaPreloadMaps" 
                 numberOfPartitions="131" 
                 numInitialContainers="3" 
                 minSyncReplicas="0" 
                 maxSyncReplicas="1" 
                 maxAsyncReplicas="1" 
                 developmentMode="false">     
          ...   
         </mapSet>
      </objectgridDeployment>
      ...

      Important: Do not modify the child elements of the mapSet element.
   4. Set the numInitialContainers attribute to the number of servers that must be available before the cluster begins processing.
      To ensure high availability, the minimum value for numInitialContainers is equal to maxSyncReplicas + maxAsyncReplicas + 1. The value that you set can be anywhere between the minimum and the total number of servers in your cluster.