README.md

   1 # Synapse Micro Service
   2
   3 [![alt text](https://bestpractices.coreinfrastructure.org/projects/1737/badge)](https://bestpractices.coreinfrastructure.org/projects/1737)
   4
   5 ## Overview
   6 The Synapse microservice (data router service) acts as a message broker between different sources of information and business logic within the context of AAI. The goal is to provide an extensible framework that can stitch sources of data and business logic together to satisfy use cases through configuration and minimal coding.
   7
   8 Please refer to the following sub-sections for more detailed information:
   9
  10 [High Level Concepts](./CONCEPTS.md) - Discussion of the high level concepts and building blocks of the _SYNAPSE_ Data Router service.
  11
  12 [Synapse Functions](./FUNCTIONS.md) - Discussion of the high level use cases that Synapse can fulfill upon deployment and configuration
  13
  14 ## Getting Started
  15
  16 ### Building The Micro Service
  17
  18 After cloning the project, execute the following Maven command from the project's top level directory to build the project:
  19
  20     > mvn clean install
  21
  22 Now, you can build your Docker image:
  23
  24     > docker build -t onap/datarouter-service target
  25
  26 ### Deploying The Micro Service
  27
  28 Push the Docker image that you have built to your Docker repository and pull it down to the location that you will be running Synapse from.
  29
  30 Note that in order to take advantage of some of the base functionality of Synapse, you will need to have the following:
  31
  32 * optional access to DMaaP in order to pull data off of configured topics
  33 * optional access to a search service installation in order to be able to write indexable data
  34
  35
  36 **Create the following directories on the host machine:**
  37
  38     /logs
  39     /opt/app/datarouter-service/appconfig
  40
  41 You will be mounting these as data volumes when you start the Docker container.
  42
  43 **Populate these directories as follows:**
  44
  45 ##### Contents of /opt/app/datarouter-service/appconfig
  46
  47 The purpose of this configuration directory is to maintain general configuration files for the _Synapse_ data routing service.
  48 The following files must be present in this directory on the host machine:
  49
  50 _data-router.properties_
  51
  52 This file currently requires no configuration but should still remain for future use cases
  53
  54 ##### Contents of the /opt/app/datarouter-service/app-config/auth Directory
  55
  56 The purpose of this configuration directory is to maintain configuration files specific to authentication/authorization for the _Synapse_ data routing service.
  57 The following files must be present in this directory on the host machine:
  58
  59 _data-router\_policy.json_
  60
  61 Create a policy file defining the roles and users that will be allowed to access _Synapse_ data routing service.  This is a JSON format file which will look something like the following example:
  62
  63     {
  64         "roles": [
  65             {
  66                 "name": "admin",
  67                 "functions": [
  68                     {
  69                         "name": "search", "methods": [ { "name": "GET" },{ "name": "DELETE" }, { "name": "PUT" }, { "name": "POST" } ]
  70                     }
  71                 ],
  72                 "users": [
  73                     {
  74                         "username": "CN=synapseadmin, OU=My Organization Unit, O=, L=Sometown, ST=SomeProvince, C=CA"
  75                     }
  76                 ]
  77             }
  78         ]
  79     }
  80
  81 _tomcat\_keystore_
  82
  83 Create a keystore with this name containing whatever CA certificates that you want your instance of the _Synapse_ data routing service to accept for HTTPS traffic.
  84
  85 _search-certificate_
  86
  87 Provide a certificate that will allow the _Synapse_ data routing service to communicate with the configured search service via HTTPS
  88
  89 ##### Contents of the /opt/app/datarouter-service/app-config/model Directory
  90
  91 The purpose of this configuration directory is to maintain model configuration files for the _Synapse_ data routing service.
  92 The following files must be present in this directory on the host machine:
  93
  94 _aai_oxm_(.*).xml_
  95
  96 Any AAI OXM model files must be placed in the model directory and be named with the aai_oxm_ prefix. ex: aai_oxm_v9.xml. These files are used for use cases that are model driven.
  97
  98 ##### Contents of the /opt/app/datarouter-service/dynamic/conf Directory
  99
 100 The purpose of this configuration directory is to maintain configuration spring bean files specific to _Synapse_ use cases. Please refer to [Synapse Functions](./FUNCTIONS.md) for information on specific use cases.
 101
 102
 103 ##### Contents of the /opt/app/datarouter-service/dynamic/routes Directory
 104
 105 The purpose of this configuration directory is to maintain Camel route files specific to _Synapse_ use cases.  Please refer to [Synapse Functions](./FUNCTIONS.md) for information on specific use cases.
 106
 107 **Start the service:**
 108
 109 You can now start the Docker container for the _Synapse_ data router service, in the following manner:
 110
 111         docker run -d \
 112             -p 9502:9502 \
 113                 -e CONFIG_HOME=/opt/app/datarouter-service/config/ \
 114                 -e KEY_STORE_PASSWORD=OBF:{{obfuscated password}} \
 115                 -e KEY_MANAGER_PASSWORD=OBF:{{obfuscated password}} \
 116                 -e MAX_HEAP={{jvmmaxheap}} \
 117             -v /logs:/opt/aai/logroot/AAI-DR \
 118             -v /opt/app/datarouter-service/appconfig:/opt/app/datarouter-service/config \
 119             --name datarouter-service \
 120             {{your docker repo}}/datarouter-service
 121
 122 Where,
 123
 124     {{your docker repo}} = The Docker repository you have published the Synapse Data Router Service image to.
 125     {{obfuscated password}} = The password for your key store/key manager after running it through the Jetty obfuscation tool.
 126     {{jvmmaxheap}} = The max heap size of the JVM for the microservice
 127
 128
 129
 130