README.md

   1 # Search Data Service Micro Service
   2
   3 [![alt text](https://bestpractices.coreinfrastructure.org/projects/1737/badge)](https://bestpractices.coreinfrastructure.org/projects/1737)
   4
   5 ## Overview
   6 The _Search Data Service_ acts as an abstraction layer for clients which have a need to interact with data which is most suitably persisted in a searchable document store.  The purpose of imposing an abstraction service between the client and the document store itself is to decouple clients from any direct knowledge of any specific document store technology, allowing the underlying technology to be swapped out without a direct impact to any clients which interact with search data.
   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 _Search Data Service_.
  11
  12 [Index API](./INDEXES.md) - Details regarding manipulating document indexes.
  13
  14 [Document API](./DOCUMENTS.md) - Details regarding manipulating documents.
  15
  16 [Search API](./SEARCH.md) - Details regarding querying the data set.
  17
  18 [Bulk API](./BULK.md) - Details regarding submitted bulk operation requests.
  19
  20
  21 ## Getting Started
  22
  23 ### Building The Micro Service
  24
  25 After cloning the project, execute the following Maven command from the project's top level directory to build the project:
  26
  27     > mvn clean install
  28
  29 Now, you can build your Docker image:
  30
  31     > docker build -t openecomp/search-data-service target
  32
  33 ### Deploying The Micro Service
  34
  35 Push the Docker image that you have built to your Docker repository and pull it down to the location that you will be running the search service from.
  36
  37 Note that the current version of the _Search Data Service_ uses _ElasticSearch_ as its document store back end.  You must therefore deploy an instance of ElasticSearch and make it accessible to the _Search Data Service_.
  38
  39 **Create the following directories on the host machine:**
  40
  41     /logs
  42     /opt/app/search-data-service/appconfig
  43
  44 You will be mounting these as data volumes when you start the Docker container.
  45
  46 **Populate these directories as follows:**
  47
  48 ##### Contents of /opt/app/search-data-service/appconfig
  49
  50 The following files must be present in this directory on the host machine:
  51
  52 _analysis-config.json_
  53 Create this file with exactly the contents below:
  54
  55
  56     [
  57         {
  58                 "name": "whitespace_analyzer",
  59                 "description": "A standard whitespace analyzer.",
  60                 "behaviours": [
  61                         "Tokenize the text using white space characters as delimeters.",
  62                         "Convert all characters to lower case.",
  63                         "Convert all alphanumeric and symbolic Unicode characters above the first 127 ASCII characters into their ASCII equivalents."
  64                 ],
  65                 "tokenizer": "whitespace",
  66                 "filters": [
  67                         "lowercase",
  68                         "asciifolding"
  69                 ]
  70         },
  71         {
  72                 "name": "ngram_analyzer",
  73                 "description": "An analyzer which performs ngram filtering on the data stream.",
  74                 "behaviours": [
  75                         "Tokenize the text using white space characters as delimeters.",
  76                         "Convert all characters to lower case.",
  77                         "Convert all alphanumeric and symbolic Unicode characters above the first 127 ASCII characters into their ASCII equivalents.",
  78                         "Apply ngram filtering using the following values for minimum and maximum size in codepoints of a single n-gram: minimum = 1, maximum = 2."
  79                 ],
  80                 "tokenizer": "whitespace",
  81                 "filters": [
  82                         "lowercase",
  83                         "asciifolding",
  84                         "ngram_filter"
  85                 ]
  86         }
  87     ]
  88
  89 _filter-config.json:_
  90
  91 Create this file with exactly the contents below:
  92
  93     [
  94         {
  95                 "name": "ngram_filter",
  96                 "description": "Custom NGram Filter.",
  97                 "configuration": " \"type\": \"nGram\", \"min_gram\": 1, \"max_gram\": 50, \"token_chars\": [ \"letter\", \"digit\", \"punctuation\", \"symbol\" ]"
  98         }
  99     ]
 100
 101 _elastic-search.properties_
 102
 103 This properties file configures the _Search Data Service_ for communication with ElasticSearch.
 104 The contents of this file will be determined by your ElasticSearch deployment:
 105
 106     es.cluster-name=<<name of your ElasticSearch cluster>>
 107     es.ip-address=<<IP address of your ElasticSearch instance>>
 108     es.http-port=9200
 109     # Optional parameters
 110     es.uri-scheme=<<either http or https>>
 111     es.trust-store=<<key store containing the certs of trusted servers>>
 112     es.trust-store-password=<<encrypted passsword to open the trust store>>
 113     es.key-store=<<key store containing the client cert>>
 114     es.key-store-password=<<encrypted passsword to open the client key store>>
 115     es.auth-user=<<username for HTTP Basic Authentication>>
 116     es.auth-password=<<encrypted passsword for HTTP Basic Authentication>>
 117
 118
 119 ##### Contents of the /opt/app/search-data-service/app-config/auth Directory
 120
 121 The following files must be present in this directory on the host machine:
 122
 123 _search\_policy.json_
 124
 125 Create a policy file defining the roles and users that will be allowed to access the _Search Data Service_.  This is a JSON format file which will look something like the following example:
 126
 127     {
 128         "roles": [
 129             {
 130                 "name": "admin",
 131                 "functions": [
 132                     {
 133                         "name": "search", "methods": [ { "name": "GET" },{ "name": "DELETE" }, { "name": "PUT" }, { "name": "POST" } ]
 134                     }
 135                 ],
 136                 "users": [
 137                     {
 138                         "username": "CN=searchadmin, OU=My Organization Unit, O=, L=Sometown, ST=SomeProvince, C=CA"
 139                     }
 140                 ]
 141             }
 142         ]
 143     }
 144
 145 _tomcat\_keystore_
 146
 147 Create a keystore with this name containing whatever CA certificates that you want your instance of the _Search Data Service_ to accept for HTTPS traffic.
 148
 149 **Start the service:**
 150
 151 You can now start the Docker container for the _Search Data Service_, in the following manner:
 152
 153         docker run -d \
 154             -p 9509:9509 \
 155                 -e CONFIG_HOME=/opt/app/search-data-service/config/ \
 156                 -e KEY_STORE_PASSWORD={{obfuscated password}} \
 157                 -e KEY_MANAGER_PASSWORD=OBF:{{obfuscated password}} \
 158             -v /logs:/opt/aai/logroot/AAI-SDB \
 159             -v /opt/app/search-data-service/appconfig:/opt/app/search-data-service/config \
 160             --name search-data-service \
 161             {{your docker repo}}/search-data-service
 162
 163 Where,
 164
 165     {{your docker repo}} = The Docker repository you have published your Search Data Service image to.
 166     {{obfuscated password}} = The password for your key store/key manager after running it through the Jetty obfuscation tool.
 167
 168
 169
 170