Configuring Instances

The created instances have default out of the box configuration, except for the ports and licenses that you provided. This is a good starting point, but you will want to customize the configuration based on your application requirements.

The best way to customize products configuration using composite templates is to first perform the necessary configuration on a live runtime instance using Command Central Web UI and capture it into the template.

Here is the generalized process which can be done using Command Central Web UI and CLI.

General Process of Developing Configurations

1. Open Command Central Web UI
2. Open Configuration tab for this instance and examine available configurations
3. Create or update the configuration in the given category
4. Use Export button of the configuration to get the configuration in the YAML format
5. Add the configuration type, instance and data to the composite template runtime instance configuration
6. Cleanup and parameterize the configuration definition as necessary
7. Test by applying the template to another installation or instance
8. Use Command Central Web UI Configuration Compare view to confirm desired results
9. Repeat for other configurations

The product configuration support for each product varies and depends on the product's SPM Plugin capabilities. Information about the supported configuration can be found in the Command Central Supportability Matrix

Example: Configuring Memory using Web UI

Let's configure Integration Server and Universal Messaging memory using the CC Web UI.

1. Ensure both Integration Server and Universal Messaging instances are running. If not, start them using CC Web UI and wait until they are both up and return ONLINE status.

2. Open IS-inst1 component Configuration tab and select Memory configuration. NOTE: if you don't see Memory configuration there, use browser refresh icon and/or refresh icon on the configuration screen.

3. Take note of the values for "Initial heap size" and "Maximum heap size". Click Edit button and change initial and maximum size to be lower than default ones. Apply/Save the configuration change.

Note: At this point, you manually used the CC Web UI to change the memory configuration values for the IS instance.

Continuing example: Configuring Memory using template(s) and property file(s)

You may want to automate changing configuration using templates. Continue with the next steps to see how you can do this.

4. Click the Export button to get the Memory configuration as YAML template fragment.

5. Edit the template.yaml file. Change version: to 0.8 and add a reason (e.g. - 0.8 Added configurations) to the the changes: list.

6. Copy the exported (YAML) configuration into your template for the given instance runtime component id, configuration type id and configuration instance id.

7. Replace values for memory configuration with variables that can be set at runtime

8. Repeat the above steps for Universal Messaging instance memory configuration.

The final template with memory configuration for IS and UM instances should look like this:

alias: tutorial
description: How to install and update main products
version: 0.8
changes:
  - 0.1 Initial draft
  - 0.2 Added input parameters
  - 0.3 Added local node bootstrap
  - 0.4 Added products/plugins installation
  - 0.5 Added fix installation
  - 0.6 Added main products and fix installation
  - 0.7 Added licenses and runtime instances
  - 0.8 Added configurations

environments:
  default:
    install.dir:  ${}                              # SPM installation directory
    spm.port:     8192                             # SPM connection port
    spm.alias:    dev${spm.port}                   # SPM alias
    repo.product: ${}                              # Product repo
    repo.fix:     ${}                              # Fixes repository
    spm.fixes:    ALL                              # Default list of fixes to install
    is.fixes:     ALL                              # Set of IS fixes
    um.fixes:     ALL                              # Set of UM fixes
    is.license.key: ${}                            # Alias for IS license key
    um.license.key: ${}                            # Alias for UM license key

    # configuration
    is.memory.init: 128
    is.memory.max:  512
    um.memory.init: 128
    um.memory.max:  512

layers:                                            # LAYERS definition
  default:                                         # default repos for all layers
    productRepo: ${repo.product}                   # product repository
    fixRepo:     ${repo.fix}                       # fix repository
  management:                                      # management layer with SPMs
    templates:   [plugins]                         # templates to apply to this layer
  messaging:
    templates:   [um]                              # templates to apply to this layer
  integration:
    templates:   [is]                              # templates to apply to this layer

templates:                                         # TEMPLATES definition
  plugins:                                         # template alias
    products:                                      # product list to install
      ISspm:                                       # Platform Manager Plug-Ins / IS
      NUMspm:                                      # Platform Manager Plug-Ins / UM
    fixes: ${spm.fixes}                            # fixes to install
  is:                                              # template alias
    licenses:                                      # copy license from the license repository to a template location
         "IntegrationServer/config/licenseKey.xml": ${is.license.key}
    products:                                      # product list to install
      integrationServer:                           # Integration Server productId
        inst1:                                     # instance name to create or update
          primary.port:     5551
          diagnostic.port:  5552
          jmx.port:         5553
          license.file: IntegrationServer/config/licenseKey.xml
          configuration:
            OSGI-IS_inst1:
              COMMON-MEMORY:
                COMMON-MEMORY:
                  InitSize: '${is.memory.init}'
                  MaxSize: '${is.memory.max}'
    fixes: ${is.fixes}                             # fixes to install

  um:                                              # template alias
    licenses:                                      # copy license from the license repository to a template location
          "UniversalMessaging/server/templates/licence.xml": ${um.license.key}
    products:                                      # product list to install
      NUMRealmServer:                              # Universal Messaging productId
        inst1:                                     # instance name to create or update
          instance.port:    9001
          instance.ip:      localhost
          runtimeComponentId: Universal-Messaging-${instance.name}
          license.file: UniversalMessaging/server/templates/licence.xml
          configuration:
            Universal-Messaging-inst1:
              COMMON-MEMORY:
                COMMON-MEMORY:
                  InitSize: '${um.memory.init}'
                  MaxSize: '${um.memory.max}'
    fixes: ${um.fixes}                             # fixes to install

nodes:                                             # NODES definition
  default:                                          # defaults for any environment type
   default:                                        # default node definition
     port: ${spm.port}                             # SPM connection HTTP/S port
     secure: false                                 # do not use SSL port
     bootstrapInfo:
       installDir: ${install.dir}                  # installation directory
       installer:  ${cc.installer}                 # cc installer that can be found in cc_home/profiles/CCE/data/installers

   ${spm.alias}:                                   # definition for specific nodeAlias
     host: localhost                               # Use localhost

provision:                                         # PROVISIONing mapping of layers to nodes
  default:                                         # default environment type
    management:  ${spm.alias}                      # management layer is single node
    messaging:   ${spm.alias}                      # messaging layer is single node
    integration: ${spm.alias}                      # integration layer is single node

Edit the environment/default/env.properties and provide values for *.memory.* properties to test the configuration. Set the init and max memory values to the original parameter values (before you saved the changes in the Web UI). For the all other settings - keep the configuration values from the previous stages.

The final env.properties file should look like this:

Note: Keep in mind the values for your parameters may be different depending on your operating system, installation location and/or instance names.

install.dir=${user.home}/sag/${spm.alias}

# MUST use one of these!

# Defaults for Windows
# cc.installer=cc-def-10.1-fix5-w64.zip 
 
# Defaults for Linux
cc.installer=cc-def-10.1-fix5-lnxamd64.sh
 
# Defaults for Mac
# cc.installer=cc-def-10.1-fix5-osx.sh

is.license.key=YOUR_LICENSE_KEY
um.license.key=YOUR_LICENSE_KEY

# customize memory configurations for your environment
is.memory.init=256
is.memory.max=1024
um.memory.init=1024
um.memory.max=1024

Save the changes to template.yaml and env.properties.

Testing Configuration

To verify that the template with property file changes the memory for the Integration Serve and Universal Messaging realm, apply the template using the following command:

[user@linuxbox tutorial]$ ant up
...
BUILD SUCCESSFUL
Total time: ....

After applying the configuration changes using the template, go back into the CC Web UI and refresh the configuration page(s).

If you have not achieved the goals of this tutorial stage, use the following command to checkout everything that needed to be done so far. Make a note about your modifications of environment/default/env.properties because the version that you'll check out will overwrite them.

[user@linuxbox tutorial]$ git checkout stage-08a
Switched to branch 'stage-08a'

Experiment

Configure default Messaging IS_UM_CONNECTION alias with valid UM URL. Add it to the template with parameterized UM server URL and other properties as needed.

integrationServer-${instance.name}:      # runtimeComponentId
  COMMON-WMMESSAGING:                    # configurationTypeId
    COMMON-WMMESSAGING-IS_UM_CONNECTION: # configurationInstanceId
      Messaging:                         # configuration data
        "@alias": IS_UM_CONNECTION
        Description: Default UM connection"
        ClientPrefix: "IS_UM"
        ShareClientPrefix: "false"
        Enabled: true
        Provider:
          "@type": UM
          URL: "${is.um.url}"
          MaxRetryAttempts: '5'
          RetryInterval: '30000'
          Auth:
            '@type': none

The final template with default Messaging IS_UM_CONNECTION alias with valid UM URL should look like this:

alias: tutorial
description: How to install and update main products
version: 0.8
changes:
  - 0.1 Initial draft
  - 0.2 Added input parameters
  - 0.3 Added local node bootstrap
  - 0.4 Added products/plugins installation
  - 0.5 Added fix installation
  - 0.6 Added main products and fix installation
  - 0.7 Added licenses and runtime instances
  - 0.8 Added configurations
   
environments:
  default:
    install.dir:  ${}                              # SPM installation directory
    spm.port:     8192                             # SPM connection port
    spm.alias:    dev${spm.port}                   # SPM alias
    repo.product: ${}                              # Product repo
    repo.fix:     ${}                              # Fixes repository
    spm.fixes:    ALL                              # Default list of fixes to install
    is.fixes:     ALL                              # Set of IS fixes 
    um.fixes:     ALL                              # Set of UM fixes 
    is.license.key: ${}                            # Alias for IS license key
    um.license.key: ${}                            # Alias for UM license key   

    # configuration
    is.memory.init: 128
    is.memory.max:  512
    um.memory.init: 128
    um.memory.max:  512

    um.instance.port: 9001
    is.um.url: "nsp://localhost:${um.instance.port}" # proper UM URL

layers:                                            # LAYERS definition
  default:                                         # default repos for all layers
    productRepo: ${repo.product}                   # product repository
    fixRepo:     ${repo.fix}                       # fix repository
  management:                                      # management layer with SPMs
    templates:   [plugins]                         # templates to apply to this layer
  messaging:
    templates:   [um]                              # templates to apply to this layer
  integration:
    templates:   [is]                              # templates to apply to this layer

templates:                                         # TEMPLATES definition
  plugins:                                         # template alias
    products:                                      # product list to install
      ISspm:                                       # Platform Manager Plug-Ins / IS
      NUMspm:                                      # Platform Manager Plug-Ins / UM
    fixes: ${spm.fixes}                            # fixes to install
  is:                                              # template alias
    licenses:                                      # copy lincense from the license repository to a template location
      "IntegrationServer/config/licenseKey.xml": ${is.license.key} 
    products:                                      # product list to install
      integrationServer:                           # Integration Server productId
        inst1:                                     # instance name to create or update
          primary.port:     5551
          diagnostic.port:  5552
          jmx.port:         5553
          license.file: IntegrationServer/config/licenseKey.xml
          configuration:
            OSGI-IS_inst1:
              COMMON-MEMORY:
                COMMON-MEMORY:
                  InitSize: '${is.memory.init}'
                  MaxSize: '${is.memory.max}'
            integrationServer-inst1:
              COMMON-WMMESSAGING:
                COMMON-WMMESSAGING-IS_UM_CONNECTION:
                  Messaging:
                    '@alias': IS_UM_CONNECTION
                    Description: "Default UM connection"
                    ClientPrefix: "IS_UM"
                    ShareClientPrefix: 'false'
                    Enabled: 'true'
                    Provider:
                      '@type': UM
                      URL: ${is.um.url}
                      MaxRetryAttempts: '5'
                      RetryInterval: '30000'
                      Auth:
                        '@type': none
    fixes: ${is.fixes}                             # fixes to install
  um:                                              # template alias
    licenses:                                      # copy lincense from the license repository to a template location
      "UniversalMessaging/server/templates/licence.xml": ${um.license.key}     
    products:                                      # product list to install
      NUMRealmServer:                              # Universal Messaging productId
        inst1:                                     # instance name to create or update
          instance.port:    ${um.instance.port}
          instance.ip:      localhost
          runtimeComponentId: Universal-Messaging-${instance.name}
          license.file: UniversalMessaging/server/templates/licence.xml
          configuration:
            Universal-Messaging-inst1:
              COMMON-MEMORY:
                COMMON-MEMORY:
                  InitSize: '${um.memory.init}'
                  MaxSize: '${um.memory.max}'
    fixes: ${um.fixes}                             # fixes to install

nodes:                                             # NODES definition
 default:                                          # defaults for any environment type
   default:                                        # default node definition
     port: ${spm.port}                             # SPM connection HTTP/S port
     secure: false                                 # do not use SSL port
     bootstrapInfo:
       installDir: ${install.dir}                  # installation directory
       installer:  ${cc.installer}                 # cc installer that can be found in cc_home/profiles/CCE/data/installers     

   ${spm.alias}:                                   # definition for specific nodeAlias
     host: localhost                               # Use localhost 
 
provision:                                         # PROVISIONing mapping of layers to nodes
  default:                                         # default environment type
    management:  ${spm.alias}                      # management layer is single node
    messaging:   ${spm.alias}                      # messaging layer is single node
    integration: ${spm.alias}                      # integration layer is single node

If you have not achieved the goals of this tutorial stage, use the following command to checkout everything that needed to be done so far. Make a note about your modifications of environment/default/env.properties because the version that you'll check out will overwrite them.

[user@linuxbox tutorial]$ git checkout stage-08b -f
Switched to branch 'stage-08b'

Test Strategies

There are different ways how you can test your template configuration implementation:

1. You can parameterize major aspects of the configuration and re-apply the template with different parameter values and verify the changes get applied successfully
2. You can delete configuration instances or even runtime instances and re-apply the template to create and configure them as designed
3. You can create new runtime instances and compare their configuration with your source instances.
4. You can provision new environments, for example, Test, and compare Dev and Test Installations and Configurations using CC Web UI. This is the option we'll explore later.

Summary

Congratulations! Now you know how to configure any runtime instance using supported configurations.