GPII Services Configuration
Contents
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.
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.
The source code for the core framework and all platform independent components can be found here: GPII Universal
All platform specific components can be found in the following repositories:
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.
GPII Server
gpii.server component is one of the building blocks of the GPII framework you are deploying. It represents a single instance of a Node.js http server.
It serves as a container for one or more gpii.apps (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 gpii.server can be found here: gpii.server
GPII App
gpii.app component is a component that represents a single purpose app deployed within a particular gpii.server. 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, gpii.apps themselves.
The source code for the gpii.app can be found here: gpii.app
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
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/configsif all your GPII 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 levelconfigsdirectory (Note: you might have to create it) within the appropriate platform specific repository. - If you are creating configuration for a single
gpii.app, you need to save it in theconfigsdirectory that corresponds to the location of that GPII app. Currently all GPII apps are located inuniversal/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 gpii app}/configs.
Basic configuration
A single gpii.server and no gpii.apps will look like this:
{
"typeName": "your configuration name",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": { // List of components to be deployed.
"gpii server component": { // The name of the server component.
"type": "gpii.server" // The type of the server component.
}
}
}
}
Multiple servers
Two gpii.servers with no gpii.apps will look like this:
{
"typeName": "your configuration name",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"server one": {
"type": "gpii.server"
},
"server two": {
"type": "gpii.server"
}
}
}
}
One server with one app
A single gpii.server that contains a gpii.app will look like this:
{
"typeName": "your configuration name",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"server": {
"type": "gpii.server",
"components": {
"gpii app component": {
"type": "gpii.app" // For example: "gpii.preferencesServer"
}
}
}
}
}
}
One server with several apps
A single gpii.server that contains two gpii.apps will look like this:
{
"typeName": "your configuration name",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"server": {
"type": "gpii.server",
"components": {
"gpii app component": {
"type": "gpii.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).
{
"typeName": "your configuration name",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"gpii server component": {
"type": "gpii.server",
"options": {
// GPII Server options
"logging": true,
"port": 80
}
}
}
}
}
{
"typeName": "your configuration name",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"server": {
"type": "gpii.server",
"components": {
"gpii app component": {
"type": "gpii.app",
"options": {
"some option": "some option value" // GPII App option
}
}
}
}
}
}
}
Includes
Configuration files are capable of including other existing configuration files to avoid duplication:
{
"typeName": "your configuration name",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"server": {
"type": "gpii.server"
}
}
},
"includes": [
"relative path to another config file"
]
}
Demands (Advanced)
There is another indirect way of configuring all components in the deployment that are not necessarily a gpii.server or a gpii.app. It is done via specific configuration blocks called "demands".
{
"typeName": "your configuration name", // (*)
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"server": {
"type": "gpii.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 GPII apps or all of GPII architecture.
Preferences Server (Production)
{
"typeName": "preferencesServer.production",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"server": {
"type": "gpii.server",
"options": {
"logging": false,
"components": {
"preferencesServer": {
"type": "gpii.preferencesServer",
"options": {
"userSourceUrl": "http://localhost:5984/user/%token"
}
}
}
}
}
}
},
"demands": [{
"demandingName": "rawUserSource",
"contextNames": "gpii.preferencesServer",
"demandSpec": {
"funcName": "gpii.dataSource.CouchDB"
}
}],
"includes": [
"./base.json"
]
}
Preferences Server (Development)
{
"typeName": "preferencesServer.development",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"server": {
"type": "gpii.server",
"options": {
"logging": true,
"components": {
"preferencesServer": {
"type": "gpii.preferencesServer",
"options": {
"userSourceUrl": "file://%root/../../../testData/preferences/%token.json"
}
}
}
}
}
}
},
"demands": [{
"demandingName": "gpii.urlExpander",
"contextNames": "gpii.preferencesServer",
"demandSpec": {
"funcName": "gpii.urlExpander.development"
}
}, {
"demandingName": "rawUserSource",
"contextNames": "gpii.preferencesServer",
"demandSpec": {
"funcName": "gpii.dataSource.URL"
}
}],
"includes": [
"./base.json"
]
}
Preferences Server (base)
{
"demands": [{
"demandingName": "gpii.requests.request.handler",
"contextNames": "userGet",
"demandSpec": {
"options": {
"invokers": {
"handle": {
"funcName": "gpii.requests.request.handler.userGet",
"args": ["{requestProxy}", "{request}.req.params.token", "{preferencesServer}.userSource"]
}
}
}
}
}, {
"demandingName": "gpii.requests.request.handler",
"contextNames": "userPost",
"demandSpec": {
"options": {
"invokers": {
"handle": {
"funcName": "gpii.requests.request.handler.userPost",
"args": ["{requestProxy}", "{request}.req", "{preferencesServer}.userSource"]
}
}
}
}
}, {
"demandingName": "userSource",
"contextNames": "gpii.preferencesServer",
"demandSpec": {
"options": {
"components": {
"rawSource": "{rawUserSource}"
}
}
}
}]
}
Match Maker (Development)
{
"typeName": "matchMaker.development",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"server": {
"type": "gpii.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": "gpii.urlExpander",
"contextNames": "gpii.matchMaker",
"demandSpec": {
"funcName": "gpii.urlExpander.development"
}
}, {
"demandingName": "rawOntologyServer",
"contextNames": "gpii.matchMaker",
"demandSpec": {
"funcName": "gpii.ontologyServer.development"
}
}],
"includes": [
"./base.json"
]
}
All of GPII (Development)
{
"typeName": "flowManager.preferencesServer.solutionsRegistry.deviceReporter.matchMaker.ontologyServer.development",
"options": {
"gradeNames": ["autoInit", "fluid.littleComponent"],
"components": {
"server": {
"type": "gpii.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"
]
}
Deploying GPII Architecture Components
Once configuration file is ready it is trivial to deploy the configuration on your platform.
To run it, execute the following command in your terminal:
[NODE_ENV={environment}] node {universal}/gpii/node_modules/gpiiFramework/init.js path/to/a/folder/with/your/config
Options
- environment should correspond to the name of your config file. Default value is 'development'
- universal is the location of the universal repository
Examples
-
node gpii/node_modules/gpiiFramework/init.js gpii/node_modules/preferencesServer/configs/ -
NODE_ENV=production node gpii/node_modules/gpiiFramework/init.js gpii/node_modules/matchMaker/configs/ -
NODE_ENV=ps.sr.production node gpii/node_modules/gpiiFramework/init.js gpii/configs/
