Difference between revisions of "GPII Services Configuration"

From wiki.gpii
Jump to: navigation, search
m (Description)
m (Kasper Galschiot Markus moved page Configuration to GPII Services Configuration: Clearer title)
 
(20 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
= Description =
 
= Description =
  
The GPII architecture is designed to be flexible and highly configurable. It consists of many components that can be configured without modifying their implementation, or swapped out entirely for other implementations. This configuration is done by creating new or editing existing JSON configuration files that describe various components for specific GPII deployment types.
+
The GPII/Kettle architecture is designed to be flexible and highly configurable. It consists of many components that can be configured without modifying their implementation, or swapped out entirely for other implementations. This configuration is done by creating new or editing existing JSON configuration files that describe various components for specific GPII/Kettle deployment types.
  
 
With the help of these configuration files, developers can configure which components are deployed and with what settings. Examples of such configurations include:
 
With the help of these configuration files, developers can configure which components are deployed and with what settings. Examples of such configurations include:
Line 10: Line 10:
 
This page contains all the necessary information on how to configure various components (Flow Manager, Match Maker, Device Reporter, etc) within the GPII framework.
 
This page contains all the necessary information on how to configure various components (Flow Manager, Match Maker, Device Reporter, etc) within the GPII framework.
  
The source code for the core framework and all platform independent components can be found here: [https://github.com/GPII/universal GPII Universal]
+
----
 +
----
 +
== Getting Started ==
 +
 
 +
In order to proceed with the configuration and deployment tasks, please make sure that your development environment is set up: [http://wiki.gpii.net/index.php/Setting_Up_Your_Development_Environment Setting Up Your Development Environment].
 +
 
 +
 
 +
The source code for the core framework and all platform independent components can be found here: [https://github.com/GPII/universal GPII Universal], [https://github.com/GPII/kettle Kettle].
  
 
All platform specific components can be found in the following repositories:
 
All platform specific components can be found in the following repositories:
----
+
 
 
* [https://github.com/GPII/android GPII Android]
 
* [https://github.com/GPII/android GPII Android]
 
* [https://github.com/GPII/linux GPII Linux]
 
* [https://github.com/GPII/linux GPII Linux]
Line 20: Line 27:
 
----
 
----
 
----
 
----
In order to proceed with the configuration and deployment tasks, please make sure that your development environment is set up: [http://wiki.gpii.net/index.php/Setting_Up_Your_Development_Environment Setting Up Your Development Environment].
 
----
 
----
 
  
== GPII Server ==
+
== Kettle Server ==
 +
 
 +
The <code>kettle.server</code> component is one of the building blocks of the Kettle framework you are deploying. It represents a single instance of a [http://nodejs.org/ Node.js] http server.
 +
 
 +
It serves as a container for one or more <code>kettle.app</code>s (see below). Developers have the option of deploying a number of Kettle servers that themselves contain one or more Kettle apps.
  
<code>gpii.server</code> component is one of the building blocks of the GPII framework you are deploying. It represents a single instance of a [http://nodejs.org/ Node.js] http server.
+
The source code for the <code>kettle.server</code> can be found here: [https://github.com/fluid-project/kettle/blob/master/lib/server.js kettle.server]. Documentation can be found here: [http://wiki.fluidproject.org/display/kettle].
  
It serves as a container for one or more <code>gpii.app</code>s (see below). Developers have the option of deploying a number of GPII servers that themselves contain one or more GPII apps.
+
----
 +
----
  
The source code for the <code>gpii.server</code> can be found here: [https://github.com/GPII/universal/blob/master/gpii/node_modules/gpiiFramework/server.js gpii.server]
+
== Kettle App ==
  
== GPII App ==
+
The <code>kettle.app</code> component is a component that represents a single purpose app deployed within a particular <code>kettle.server</code>. The majority of the existing components within the Kettle architecture that support the HTTP API (such as the Flow Manager, Device Reporter, Match Maker, Preferences Server, Solutions Registry, etc) are, in fact, <code>kettle.app</code>s themselves.
  
<code>gpii.app</code> component is a component that represents a single purpose app deployed within a particular <code>gpii.server</code>. Majority of the existing components within the GPII architecture that support the HTTP API (such as the Flow Manager, Device Reporter, Match Maker, Preferences Server, Solutions Registry, etc) are, in fact, <code>gpii.app</code>s themselves.
+
The source code for the <code>kettle.app</code> can be found here: [https://github.com/fluid-project/kettle/blob/master/lib/app.js kettle.app]. Documentation can be found here: [http://wiki.fluidproject.org/display/kettle].
  
The source code for the <code>gpii.app</code> can be found here: [https://github.com/GPII/universal/blob/master/gpii/node_modules/gpiiFramework/app.js gpii.app]
+
To configure a specific Kettle deployment, you will be setting up the appropriate Kettle servers and Kettle apps required for the deployment.
  
 
----
 
----
 
----
 
----
Creating a new configuration or editing an existing one for a specific GPII deployment essentially means setting up the appropriate GPII servers and GPII apps for a single deployment.
 
----
 
----
 
  
= Creating Configuration File  =
+
 
 +
= Creating a Configuration File  =
  
 
There are several conventions in regards to where your configuration file should go:
 
There are several conventions in regards to where your configuration file should go:
  
* If you are creating configuration for multiple apps, consider putting it in <code>universal/gpii/configs</code> if all your GPII apps are defined in a [https://github.com/GPII/universal GPII Universal] repository. If one or more apps are defined in a platform specific repository, your configuration files should go into a top level <code>configs</code> directory (Note: you might have to create it) within the appropriate platform specific repository.
+
* If you are creating configuration for multiple apps, consider putting it in <code>universal/gpii/configs</code> if all your Kettle apps are defined in a [https://github.com/GPII/universal GPII Universal] repository. If one or more apps are defined in a platform specific repository, your configuration files should go into a top level <code>configs</code> directory (Note: you might have to create it) within the appropriate platform specific repository.
* If you are creating configuration for a single <code>gpii.app</code>, you need to save it in the <code>configs</code> directory that corresponds to the location of that GPII app. Currently all GPII apps are located in <code>universal/gpii/node_modules</code> (e.g. Preferences Server, Solutions Registry, etc). Thus, the config file should be located at this path: <code>universal/gpii/node_modules/{some gpii app}/configs</code>.
+
* If you are creating configuration for a single <code>kettle.app</code>, you need to save it in the <code>configs</code> directory that corresponds to the location of that Kettle app. Currently, all Kettle apps are located in <code>universal/gpii/node_modules</code> (e.g. Preferences Server, Solutions Registry, etc). Thus, the config file should be located at this path: <code>universal/gpii/node_modules/{some kettle app}/configs</code>.
  
 
==== Basic configuration ====
 
==== Basic configuration ====
A single <code>gpii.server</code> and no <code>gpii.app</code>s will look like this:
+
A single <code>kettle.server</code> and no <code>kettle.app</code>s.
 +
 
 +
This configuration will deploy a single empty server container:
 
<pre>
 
<pre>
 
{
 
{
Line 59: Line 68:
 
         "gradeNames": ["autoInit", "fluid.littleComponent"],
 
         "gradeNames": ["autoInit", "fluid.littleComponent"],
 
         "components": {                // List of components to be deployed.
 
         "components": {                // List of components to be deployed.
             "gpii server component": { // The name of the server component.
+
             "kettle server component": { // The name of the server component.
                 "type": "gpii.server"  // The type of the server component.
+
                 "type": "kettle.server"  // The type of the server component.
 
             }
 
             }
 
         }
 
         }
Line 68: Line 77:
  
 
==== Multiple servers ====
 
==== Multiple servers ====
Two <code>gpii.server</code>s with no <code>gpii.app</code>s will look like this:
+
Two <code>kettle.server</code>s with no <code>kettle.app</code>s.
 +
 
 +
This configuration will deploy two empty server containers.
 
<pre>
 
<pre>
 
{
 
{
Line 76: Line 87:
 
         "components": {
 
         "components": {
 
             "server one": {
 
             "server one": {
                 "type": "gpii.server"
+
                 "type": "kettle.server"
 
             },
 
             },
 
             "server two": {
 
             "server two": {
                 "type": "gpii.server"
+
                 "type": "kettle.server"
 
             }
 
             }
 
         }
 
         }
Line 87: Line 98:
  
 
==== One server with one app ====
 
==== One server with one app ====
A single <code>gpii.server</code> that contains a <code>gpii.app</code> will look like this:
+
A single <code>kettle.server</code> that contains a <code>kettle.app</code>.
 +
 
 +
This configuration will deploy a single server with an empty app that does nothing.
 
<pre>
 
<pre>
 
{
 
{
Line 95: Line 108:
 
         "components": {
 
         "components": {
 
             "server": {
 
             "server": {
                 "type": "gpii.server",
+
                 "type": "kettle.server",
 
                 "components": {
 
                 "components": {
                     "gpii app component": {
+
                     "kettle app component": {
                         "type": "gpii.app" // For example: "gpii.preferencesServer"
+
                         "type": "kettle.app" // For example: "gpii.preferencesServer"
 
                     }
 
                     }
 
                 }
 
                 }
Line 108: Line 121:
  
 
==== One server with several apps ====
 
==== One server with several apps ====
A single <code>gpii.server</code> that contains two <code>gpii.app</code>s will look like this:
+
A single <code>kettle.server</code> that contains two <code>kettle.app</code>s.
 +
 
 +
This configuration will deploy a single server with two empty apps that do nothing.
 
<pre>
 
<pre>
 
{
 
{
Line 116: Line 131:
 
         "components": {
 
         "components": {
 
             "server": {
 
             "server": {
                 "type": "gpii.server",
+
                 "type": "kettle.server",
 
                 "components": {
 
                 "components": {
                     "gpii app component": {
+
                     "kettle app component": {
                         "type": "gpii.app"
+
                         "type": "kettle.app"
 
                     },
 
                     },
 
                     "preferencesServer": {
 
                     "preferencesServer": {
Line 133: Line 148:
 
==== Options ====
 
==== Options ====
 
Each GPII component is capable of interpreting optional parameters passed to it (these options are meant to override the default setting found in the actual component definition).
 
Each GPII component is capable of interpreting optional parameters passed to it (these options are meant to override the default setting found in the actual component definition).
 +
* This configuration will deploy a server on port 80 with logging enabled
 
<pre>
 
<pre>
 
{
 
{
Line 139: Line 155:
 
         "gradeNames": ["autoInit", "fluid.littleComponent"],
 
         "gradeNames": ["autoInit", "fluid.littleComponent"],
 
         "components": {
 
         "components": {
             "gpii server component": {
+
             "kettle server component": {
                 "type": "gpii.server",
+
                 "type": "kettle.server",
 
                 "options": {
 
                 "options": {
                     // GPII Server options
+
                     // Kettle Server options
 
                     "logging": true,
 
                     "logging": true,
 
                     "port": 80
 
                     "port": 80
Line 151: Line 167:
 
}
 
}
 
</pre>
 
</pre>
 +
* This configuration will deploy a server with an app that has "some option" setting set to "some option value"
 
<pre>
 
<pre>
 
{
 
{
Line 158: Line 175:
 
         "components": {
 
         "components": {
 
             "server": {
 
             "server": {
                 "type": "gpii.server",
+
                 "type": "kettle.server",
 
                 "components": {
 
                 "components": {
                     "gpii app component": {
+
                     "kettle app component": {
                         "type": "gpii.app",
+
                         "type": "kettle.app",
 
                         "options": {
 
                         "options": {
                             "some option": "some option value" // GPII App option
+
                             "some option": "some option value" // Kettle App option
 
                         }
 
                         }
 
                     }
 
                     }
Line 174: Line 191:
  
 
==== Includes ====
 
==== Includes ====
Configuration files are capable of including other existing configuration files to avoid duplication:
+
Configuration files are capable of including other existing configuration files to avoid duplication.
 +
 
 +
This configuration will deploy a server and also load and process the contents of all configuration files mentioned in 'includes' section.
 
<pre>
 
<pre>
 
{
 
{
Line 182: Line 201:
 
         "components": {
 
         "components": {
 
             "server": {
 
             "server": {
                 "type": "gpii.server"
+
                 "type": "kettle.server"
 
             }
 
             }
 
         }
 
         }
Line 189: Line 208:
 
         "relative path to another config file"
 
         "relative path to another config file"
 
     ]
 
     ]
 +
}
 +
</pre>
 +
 +
'''NOTE'''
 +
The content of included files is essentially merged with the content of the base file. To add applications to the server specified in the base file, the server name – the key used for the server in the base file – must be used in the included file as well.
 +
 +
For example:
 +
Base file:
 +
<pre>
 +
{
 +
    "typeName": "my.gpii.config",
 +
    "options": {
 +
        "gradeNames": ["autoInit", "fluid.littleComponent"],
 +
        "components": {
 +
            "myServer": { // <<<<<==== note server "name"
 +
                "type": "kettle.server"
 +
            }
 +
        }
 +
    },
 +
    "includes": [
 +
        "configs/extra.json"
 +
    ]
 +
}
 +
</pre>
 +
Included file:
 +
<pre>
 +
{
 +
    "typeName": "my.gpii.extraStuff",
 +
    "options": {
 +
        "gradeNames": ["autoInit", "fluid.littleComponent"],
 +
        "components": {
 +
            "myServer": { // <<<<<==== same server "name"
 +
                "type": "kettle.server",
 +
                "options": {
 +
                    "components": {
 +
                        "myApp": { // this app is added to the server
 +
                            "type": "my.gpii.app",
 +
                            "options": {
 +
                                ...
 +
                            }
 +
                        }
 +
                    }
 +
                }
 +
            }
 +
        }
 +
    }
 
}
 
}
 
</pre>
 
</pre>
  
 
==== Demands (Advanced) ====
 
==== Demands (Advanced) ====
There is another indirect way of configuring all components in the deployment that are not necessarily a <code>gpii.server</code> or a <code>gpii.app</code>. It is done via specific configuration blocks called "demands".
+
There is another indirect way of configuring all components in the deployment that are not necessarily a <code>kettle.server</code> or a <code>kettle.app</code>. It is done via specific configuration blocks called "demands".
 +
 
 +
This configuration will deploy a server and also set a "some option" setting set to "some option value" for a "component name we want to configure" when it is created as part of "your configuration name" configuration.
 
<pre>
 
<pre>
 
{
 
{
Line 201: Line 268:
 
         "components": {
 
         "components": {
 
             "server": {
 
             "server": {
                 "type": "gpii.server"
+
                 "type": "kettle.server"
 
             }
 
             }
 
         }
 
         }
Line 220: Line 287:
 
</pre>
 
</pre>
 
For more details on how to write demands blocks, see [http://wiki.fluidproject.org/display/Infusion14/Demands+Specifications Demands Specifications]
 
For more details on how to write demands blocks, see [http://wiki.fluidproject.org/display/Infusion14/Demands+Specifications Demands Specifications]
 
  
 
= Examples of Existing Configuration Files  =
 
= Examples of Existing Configuration Files  =
  
Below are examples of some of the existing configuration files that are currently used to deploy single GPII apps or all of GPII architecture.
+
Below are examples of some of the existing configuration files that are currently used to deploy single Kettle apps or all of GPII architecture.
  
 
==== [https://github.com/GPII/universal/blob/master/gpii/node_modules/preferencesServer/configs/production.json Preferences Server (Production)] ====
 
==== [https://github.com/GPII/universal/blob/master/gpii/node_modules/preferencesServer/configs/production.json Preferences Server (Production)] ====
 +
 +
This configuration deploys a preferences server app in a single server container (with logging disabled). We also configure the location of the users store to be at <code>"http://localhost:5984/user/%token"</code>. Type of the user store is set to Couch DB (*).
 +
 
<pre>
 
<pre>
 
{
 
{
Line 234: Line 303:
 
         "components": {
 
         "components": {
 
             "server": {
 
             "server": {
                 "type": "gpii.server",
+
                 "type": "kettle.server",
 
                 "options": {
 
                 "options": {
 
                     "logging": false,
 
                     "logging": false,
Line 253: Line 322:
 
         "contextNames": "gpii.preferencesServer",
 
         "contextNames": "gpii.preferencesServer",
 
         "demandSpec": {
 
         "demandSpec": {
             "funcName": "gpii.dataSource.CouchDB"
+
             "funcName": "kettle.dataSource.CouchDB" // (*)
 
         }
 
         }
 
     }],
 
     }],
Line 263: Line 332:
  
 
==== [https://github.com/GPII/universal/blob/master/gpii/node_modules/preferencesServer/configs/development.json Preferences Server (Development)] ====
 
==== [https://github.com/GPII/universal/blob/master/gpii/node_modules/preferencesServer/configs/development.json Preferences Server (Development)] ====
 +
 +
This configuration deploys a preferences server app in a single server container (with logging enabled). We also configure the location of the users store to be at <code>"file://%root/../../../testData/preferences/%token.json"</code>. Type of the user store is set to File (e.g. file path) (*).
 +
 
<pre>
 
<pre>
 
{
 
{
Line 270: Line 342:
 
         "components": {
 
         "components": {
 
             "server": {
 
             "server": {
                 "type": "gpii.server",
+
                 "type": "kettle.server",
 
                 "options": {
 
                 "options": {
 
                     "logging": true,
 
                     "logging": true,
Line 286: Line 358:
 
     },
 
     },
 
     "demands": [{
 
     "demands": [{
         "demandingName": "gpii.urlExpander",
+
         "demandingName": "kettle.urlExpander",
 
         "contextNames": "gpii.preferencesServer",
 
         "contextNames": "gpii.preferencesServer",
 
         "demandSpec": {
 
         "demandSpec": {
             "funcName": "gpii.urlExpander.development"
+
             "funcName": "kettle.urlExpander.development"
 
         }
 
         }
 
     }, {
 
     }, {
Line 295: Line 367:
 
         "contextNames": "gpii.preferencesServer",
 
         "contextNames": "gpii.preferencesServer",
 
         "demandSpec": {
 
         "demandSpec": {
             "funcName": "gpii.dataSource.URL"
+
             "funcName": "kettle.dataSource.URL" // (*)
 
         }
 
         }
 
     }],
 
     }],
Line 305: Line 377:
  
 
==== [https://github.com/GPII/universal/blob/master/gpii/node_modules/preferencesServer/configs/base.json Preferences Server (base)] ====
 
==== [https://github.com/GPII/universal/blob/master/gpii/node_modules/preferencesServer/configs/base.json Preferences Server (base)] ====
 +
 +
This configuration defines request handlers specification common between all types of preferences servers.
 +
 
<pre>
 
<pre>
 
{
 
{
 
     "demands": [{
 
     "demands": [{
         "demandingName": "gpii.requests.request.handler",
+
         "demandingName": "kettle.requests.request.handler",
 
         "contextNames": "userGet",
 
         "contextNames": "userGet",
 
         "demandSpec": {
 
         "demandSpec": {
Line 314: Line 389:
 
                 "invokers": {
 
                 "invokers": {
 
                     "handle": {
 
                     "handle": {
                         "funcName": "gpii.requests.request.handler.userGet",
+
                         "funcName": "kettle.requests.request.handler.userGet",
 
                         "args": ["{requestProxy}", "{request}.req.params.token", "{preferencesServer}.userSource"]
 
                         "args": ["{requestProxy}", "{request}.req.params.token", "{preferencesServer}.userSource"]
 
                     }
 
                     }
Line 321: Line 396:
 
         }
 
         }
 
     }, {
 
     }, {
         "demandingName": "gpii.requests.request.handler",
+
         "demandingName": "kettle.requests.request.handler",
 
         "contextNames": "userPost",
 
         "contextNames": "userPost",
 
         "demandSpec": {
 
         "demandSpec": {
Line 327: Line 402:
 
                 "invokers": {
 
                 "invokers": {
 
                     "handle": {
 
                     "handle": {
                         "funcName": "gpii.requests.request.handler.userPost",
+
                         "funcName": "kettle.requests.request.handler.userPost",
 
                         "args": ["{requestProxy}", "{request}.req", "{preferencesServer}.userSource"]
 
                         "args": ["{requestProxy}", "{request}.req", "{preferencesServer}.userSource"]
 
                     }
 
                     }
Line 343: Line 418:
 
             }
 
             }
 
         }
 
         }
     }]
+
     }],
 +
    "modules": [
 +
        "preferencesServer"
 +
    ]
 
}
 
}
 
</pre>
 
</pre>
  
 
==== [https://github.com/GPII/universal/blob/master/gpii/node_modules/matchMaker/configs/development.json Match Maker (Development)] ====
 
==== [https://github.com/GPII/universal/blob/master/gpii/node_modules/matchMaker/configs/development.json Match Maker (Development)] ====
 +
 +
This configuration deploys a match maker app in a single server container (with logging enabled). We also configure the locations of the solutions registry to be at <code>"file://%root/../../../testData/solutions/%os.json"</code> and the ontology server to be at <code>"file://%root/../../../testData/ontologies/ontologies.json"</code>.
 +
 
<pre>
 
<pre>
 
{
 
{
Line 355: Line 436:
 
         "components": {
 
         "components": {
 
             "server": {
 
             "server": {
                 "type": "gpii.server",
+
                 "type": "kettle.server",
 
                 "options": {
 
                 "options": {
 
                     "logging": true,
 
                     "logging": true,
Line 372: Line 453:
 
     },
 
     },
 
     "demands": [{
 
     "demands": [{
         "demandingName": "gpii.urlExpander",
+
         "demandingName": "kettle.urlExpander",
 
         "contextNames": "gpii.matchMaker",
 
         "contextNames": "gpii.matchMaker",
 
         "demandSpec": {
 
         "demandSpec": {
             "funcName": "gpii.urlExpander.development"
+
             "funcName": "kettle.urlExpander.development"
 
         }
 
         }
 
     }, {
 
     }, {
Line 391: Line 472:
  
 
==== [https://github.com/GPII/universal/blob/master/gpii/configs/fm.ps.sr.dr.mm.os.development.json All of GPII (Development)] ====
 
==== [https://github.com/GPII/universal/blob/master/gpii/configs/fm.ps.sr.dr.mm.os.development.json All of GPII (Development)] ====
 +
 +
We load and process all config files mentioned in 'includes' list and thus deploy a device reporter, a flow manager, a match maker, an ontology server, a preferences server and a solutions registry.
 +
 
<pre>
 
<pre>
 
{
 
{
Line 398: Line 482:
 
         "components": {
 
         "components": {
 
             "server": {
 
             "server": {
                 "type": "gpii.server",
+
                 "type": "kettle.server",
 
                 "options": {
 
                 "options": {
 
                     "logging": true,
 
                     "logging": true,
Line 417: Line 501:
 
</pre>
 
</pre>
  
= Deploying GPII Architecture Components =
+
= See Also =
  
Once configuration file is ready it is trivial to deploy the configuration on your platform.
+
[[Deploying GPII Architecture Components]]
 
 
To run it, execute the following command in your terminal:
 
 
 
<code>[NODE_ENV={environment}] node {universal}/gpii/node_modules/gpiiFramework/init.js path/to/a/folder/with/your/config</code>
 
 
 
==== Options ====
 
* '''environment''' should correspond to the name of your config file. Default value is 'development'
 
* '''universal''' is the location of the universal repository
 
  
==== Examples ====
+
[[Category:GPII Architecture]]
* <code>node gpii/node_modules/gpiiFramework/init.js gpii/node_modules/preferencesServer/configs/</code>
 
* <code>NODE_ENV=production node gpii/node_modules/gpiiFramework/init.js gpii/node_modules/matchMaker/configs/</code>
 
* <code>NODE_ENV=ps.sr.production node gpii/node_modules/gpiiFramework/init.js gpii/configs/</code>
 

Latest revision as of 20:44, 16 March 2014

Description

The GPII/Kettle architecture is designed to be flexible and highly configurable. It consists of many components that can be configured without modifying their implementation, or swapped out entirely for other implementations. This configuration is done by creating new or editing existing JSON configuration files that describe various components for specific GPII/Kettle deployment types.

With the help of these configuration files, developers can configure which components are deployed and with what settings. Examples of such configurations include:

  • Configuring URL locations for GPII resources
  • Configuring Match Maker strategies
  • Registering events and event listeners within various workflows

This page contains all the necessary information on how to configure various components (Flow Manager, Match Maker, Device Reporter, etc) within the GPII framework.



Getting Started

In order to proceed with the configuration and deployment tasks, please make sure that your development environment is set up: Setting Up Your Development Environment.


The source code for the core framework and all platform independent components can be found here: GPII Universal, Kettle.

All platform specific components can be found in the following repositories:



Kettle Server

The kettle.server component is one of the building blocks of the Kettle framework you are deploying. It represents a single instance of a Node.js http server.

It serves as a container for one or more kettle.apps (see below). Developers have the option of deploying a number of Kettle servers that themselves contain one or more Kettle apps.

The source code for the kettle.server can be found here: kettle.server. Documentation can be found here: [1].



Kettle App

The kettle.app component is a component that represents a single purpose app deployed within a particular kettle.server. The majority of the existing components within the Kettle architecture that support the HTTP API (such as the Flow Manager, Device Reporter, Match Maker, Preferences Server, Solutions Registry, etc) are, in fact, kettle.apps themselves.

The source code for the kettle.app can be found here: kettle.app. Documentation can be found here: [2].

To configure a specific Kettle deployment, you will be setting up the appropriate Kettle servers and Kettle apps required for the deployment.




Creating a Configuration File

There are several conventions in regards to where your configuration file should go:

  • If you are creating configuration for multiple apps, consider putting it in universal/gpii/configs if all your Kettle apps are defined in a GPII Universal repository. If one or more apps are defined in a platform specific repository, your configuration files should go into a top level configs directory (Note: you might have to create it) within the appropriate platform specific repository.
  • If you are creating configuration for a single kettle.app, you need to save it in the configs directory that corresponds to the location of that Kettle app. Currently, all Kettle apps are located in universal/gpii/node_modules (e.g. Preferences Server, Solutions Registry, etc). Thus, the config file should be located at this path: universal/gpii/node_modules/{some kettle app}/configs.

Basic configuration

A single kettle.server and no kettle.apps.

This configuration will deploy a single empty server container:

{
    "typeName": "your configuration name",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {                // List of components to be deployed.
            "kettle server component": { // The name of the server component.
                "type": "kettle.server"  // The type of the server component.
            }
        }
    }
}

Multiple servers

Two kettle.servers with no kettle.apps.

This configuration will deploy two empty server containers.

{
    "typeName": "your configuration name",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "server one": {
                "type": "kettle.server"
            },
            "server two": {
                "type": "kettle.server"
            }
        }
    }
}

One server with one app

A single kettle.server that contains a kettle.app.

This configuration will deploy a single server with an empty app that does nothing.

{
    "typeName": "your configuration name",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "server": {
                "type": "kettle.server",
                "components": {
                    "kettle app component": {
                        "type": "kettle.app" // For example: "gpii.preferencesServer"
                    }
                }
            }
        }
    }
}

One server with several apps

A single kettle.server that contains two kettle.apps.

This configuration will deploy a single server with two empty apps that do nothing.

{
    "typeName": "your configuration name",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "server": {
                "type": "kettle.server",
                "components": {
                    "kettle app component": {
                        "type": "kettle.app"
                    },
                    "preferencesServer": {
                        "type": "gpii.preferencesServer"
                    }
                }
            }
        }
    }
}

Options

Each GPII component is capable of interpreting optional parameters passed to it (these options are meant to override the default setting found in the actual component definition).

  • This configuration will deploy a server on port 80 with logging enabled
{
    "typeName": "your configuration name",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "kettle server component": {
                "type": "kettle.server",
                "options": {
                    // Kettle Server options
                    "logging": true,
                    "port": 80
                }
            }
        }
    }
}
  • This configuration will deploy a server with an app that has "some option" setting set to "some option value"
{
    "typeName": "your configuration name",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "server": {
                "type": "kettle.server",
                "components": {
                    "kettle app component": {
                        "type": "kettle.app",
                        "options": {
                            "some option": "some option value" // Kettle App option
                        }
                    }
                }
            }
        }
    }
}

Includes

Configuration files are capable of including other existing configuration files to avoid duplication.

This configuration will deploy a server and also load and process the contents of all configuration files mentioned in 'includes' section.

{
    "typeName": "your configuration name",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "server": {
                "type": "kettle.server"
            }
        }
    },
    "includes": [
        "relative path to another config file"
    ]
}

NOTE The content of included files is essentially merged with the content of the base file. To add applications to the server specified in the base file, the server name – the key used for the server in the base file – must be used in the included file as well.

For example: Base file:

{
    "typeName": "my.gpii.config",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "myServer": { // <<<<<==== note server "name"
                "type": "kettle.server"
            }
        }
    },
    "includes": [
        "configs/extra.json"
    ]
}

Included file:

{
    "typeName": "my.gpii.extraStuff",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "myServer": { // <<<<<==== same server "name"
                "type": "kettle.server",
                "options": {
                    "components": {
                        "myApp": { // this app is added to the server
                            "type": "my.gpii.app",
                            "options": {
                                ...
                            }
                        }
                    }
                }
            }
        }
    }
}

Demands (Advanced)

There is another indirect way of configuring all components in the deployment that are not necessarily a kettle.server or a kettle.app. It is done via specific configuration blocks called "demands".

This configuration will deploy a server and also set a "some option" setting set to "some option value" for a "component name we want to configure" when it is created as part of "your configuration name" configuration.

{
    "typeName": "your configuration name", // (*)
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "server": {
                "type": "kettle.server"
            }
        }
    },
    "demands": [{
        "demandingName": "component name we want to configure",
        // Context in which the component is initialized, in this case
        // it is under the "your configuration name" (*) context.
        "contextNames": "your configuration name",
        "demandSpec": {
            // Component configuration goes here:
            "options": {
                "some option": "some option value"
            }
        }
    }]
}

For more details on how to write demands blocks, see Demands Specifications

Examples of Existing Configuration Files

Below are examples of some of the existing configuration files that are currently used to deploy single Kettle apps or all of GPII architecture.

Preferences Server (Production)

This configuration deploys a preferences server app in a single server container (with logging disabled). We also configure the location of the users store to be at "http://localhost:5984/user/%token". Type of the user store is set to Couch DB (*).

{
    "typeName": "preferencesServer.production",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "server": {
                "type": "kettle.server",
                "options": {
                    "logging": false,
                    "components": {
                        "preferencesServer": {
                            "type": "gpii.preferencesServer",
                            "options": {
                                "userSourceUrl": "http://localhost:5984/user/%token"
                            }
                        }
                    }
                }
            }
        }
    },
    "demands": [{
        "demandingName": "rawUserSource",
        "contextNames": "gpii.preferencesServer",
        "demandSpec": {
            "funcName": "kettle.dataSource.CouchDB" // (*)
        }
    }],
    "includes": [
        "./base.json"
    ]
}

Preferences Server (Development)

This configuration deploys a preferences server app in a single server container (with logging enabled). We also configure the location of the users store to be at "file://%root/../../../testData/preferences/%token.json". Type of the user store is set to File (e.g. file path) (*).

{
    "typeName": "preferencesServer.development",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "server": {
                "type": "kettle.server",
                "options": {
                    "logging": true,
                    "components": {
                        "preferencesServer": {
                            "type": "gpii.preferencesServer",
                            "options": {
                                "userSourceUrl": "file://%root/../../../testData/preferences/%token.json"
                            }
                        }
                    }
                }
            }
        }
    },
    "demands": [{
        "demandingName": "kettle.urlExpander",
        "contextNames": "gpii.preferencesServer",
        "demandSpec": {
            "funcName": "kettle.urlExpander.development"
        }
    }, {
        "demandingName": "rawUserSource",
        "contextNames": "gpii.preferencesServer",
        "demandSpec": {
            "funcName": "kettle.dataSource.URL" // (*)
        }
    }],
    "includes": [
        "./base.json"
    ]
}

Preferences Server (base)

This configuration defines request handlers specification common between all types of preferences servers.

{
    "demands": [{
        "demandingName": "kettle.requests.request.handler",
        "contextNames": "userGet",
        "demandSpec": {
            "options": {
                "invokers": {
                    "handle": {
                        "funcName": "kettle.requests.request.handler.userGet",
                        "args": ["{requestProxy}", "{request}.req.params.token", "{preferencesServer}.userSource"]
                    }
                }
            }
        }
    }, {
        "demandingName": "kettle.requests.request.handler",
        "contextNames": "userPost",
        "demandSpec": {
            "options": {
                "invokers": {
                    "handle": {
                        "funcName": "kettle.requests.request.handler.userPost",
                        "args": ["{requestProxy}", "{request}.req", "{preferencesServer}.userSource"]
                    }
                }
            }
        }
    }, {
        "demandingName": "userSource",
        "contextNames": "gpii.preferencesServer",
        "demandSpec": {
            "options": {
                "components": {
                    "rawSource": "{rawUserSource}"
                }
            }
        }
    }],
    "modules": [
        "preferencesServer"
    ]
}

Match Maker (Development)

This configuration deploys a match maker app in a single server container (with logging enabled). We also configure the locations of the solutions registry to be at "file://%root/../../../testData/solutions/%os.json" and the ontology server to be at "file://%root/../../../testData/ontologies/ontologies.json".

{
    "typeName": "matchMaker.development",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "server": {
                "type": "kettle.server",
                "options": {
                    "logging": true,
                    "components": {
                        "matchMaker": {
                            "type": "gpii.matchMaker",
                            "options": {
                                "solutionsReporterUrl": "file://%root/../../../testData/solutions/%os.json",
                                "ontologyServerUrl": "file://%root/../../../testData/ontologies/ontologies.json"
                            }
                        }
                    }
                }
            }
        }
    },
    "demands": [{
        "demandingName": "kettle.urlExpander",
        "contextNames": "gpii.matchMaker",
        "demandSpec": {
            "funcName": "kettle.urlExpander.development"
        }
    }, {
        "demandingName": "rawOntologyServer",
        "contextNames": "gpii.matchMaker",
        "demandSpec": {
            "funcName": "gpii.ontologyServer.development"
        }
    }],
    "includes": [
        "./base.json"
    ]
}

All of GPII (Development)

We load and process all config files mentioned in 'includes' list and thus deploy a device reporter, a flow manager, a match maker, an ontology server, a preferences server and a solutions registry.

{
    "typeName": "flowManager.preferencesServer.solutionsRegistry.deviceReporter.matchMaker.ontologyServer.development",
    "options": {
        "gradeNames": ["autoInit", "fluid.littleComponent"],
        "components": {
            "server": {
                "type": "kettle.server",
                "options": {
                    "logging": true,
                    "port": 8081
                }
            }
        }
    },
    "includes": [
        "../node_modules/deviceReporter/configs/development.json",
        "../node_modules/flowManager/configs/development.json",
        "../node_modules/matchMaker/configs/development.json",
        "../node_modules/ontologyServer/configs/development.json",
        "../node_modules/preferencesServer/configs/development.json",
        "../node_modules/solutionsRegistry/configs/development.json"
    ]
}

See Also

Deploying GPII Architecture Components