docs/platform/Getting Started/AAI_Developer_Environment_Setup.rst

   1
   2 .. contents::
   3    :depth: 3
   4 .. _dev-setup:
   5
   6
   7 AAI Developer Environment Setup
   8 ================================
   9
  10 For this exercise, I set up a new instance of Ubuntu in Virtualbox and gave it 16G RAM, 200GB dynamically allocated storage, and 3 processors.
  11
  12 1. Install openjdk 8
  13 --------------------
  14  .. code-block:: bash
  15
  16    1. $ sudo apt install openjdk-8-jdk
  17
  18 2. Install single node hadoop/janusgraph
  19 ----------------------------------------
  20  .. code-block:: bash
  21
  22    1. $ wget http://github.com/JanusGraph/janusgraph/releases/download/v0.2.0/janusgraph-0.2.0-hadoop2.zip
  23    2. $ unzip janusgraph-0.2.0-hadoop2.zip
  24    3. $ cd janusgraph-0.2.0-hadoop2/
  25    4. $ ./bin/janusgraph.sh start
  26
  27  Ensure you are not a root user as elasticsearch cannot be run as root.
  28  Response looks like:
  29
  30  .. code-block:: bash
  31
  32    Forking Cassandra...
  33    Running `nodetool statusthrift`... OK (returned exit status 0 and printed string "running").
  34    Forking Elasticsearch...
  35    Connecting to Elasticsearch (127.0.0.1:9200)...... OK (connected to 127.0.0.1:9200).
  36    Forking Gremlin-Server...
  37    Connecting to Gremlin-Server (127.0.0.1:8182).... OK (connected to 127.0.0.1:8182).
  38    Run gremlin.sh to connect.
  39
  40  You can verify whether everything is running by executing
  41
  42  .. code-block:: bash
  43
  44    ./bin/janusgraph.sh status
  45
  46  And the output looks like:
  47
  48  .. code-block:: bash
  49
  50    Gremlin-Server (org.apache.tinkerpop.gremlin.server.GremlinServer) is running with pid 9835
  51    Elasticsearch (org.elasticsearch.bootstrap.Elasticsearch) is running with pid 9567
  52    Cassandra (org.apache.cassandra.service.CassandraDaemon) is running with pid 9207
  53
  54 3. Install haproxy
  55 ------------------
  56
  57  .. code-block:: bash
  58
  59     1. $ sudo apt-get -y install haproxy
  60     2. $ <path-to-haproxy>/haproxy -v
  61
  62  Response should be:
  63
  64  .. code-block:: bash
  65
  66    HA-Proxy version 1.6.3 2015/12/25
  67    Copyright 2000-2015 Willy Tarreau <willy@haproxy.org>
  68
  69  Install the attached :download:`haproxy.cfg <media/haproxy.cfg>` in /etc/haproxy
  70
  71  .. code-block:: bash
  72
  73    $ sudo cp haproxy.cfg /etc/haproxy
  74    $ sudo mkdir /usr/local/etc/haproxy
  75
  76  Install the attached :download:`aai.pem <media/aai.pem>` file in /etc/ssl/private
  77
  78  .. code-block:: bash
  79
  80    $ sudo cp aai.pem /etc/ssl/private/aai.pem
  81    $ sudo chmod 640 /etc/ssl/private/aai.pem
  82    $ sudo chown root:ssl-cert /etc/ssl/private/aai.pem
  83
  84  Add these hostnames to the loopback interface in /etc/hosts:
  85
  86  127.0.0.1 localhost aai-traversal.api.simpledemo.openecomp.org aai-resources.api.simpledemo.openecomp.org aai-traversal.api.simpledemo.onap.org aai-resources.api.simpledemo.onap.org
  87
  88  .. code-block:: bash
  89
  90    $ sudo service haproxy restart
  91
  92 4. Follow the initial setup instructions in `Setting Up Your Development Environment <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`__ e.g.
  93 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------
  94  .. code-block:: bash
  95
  96    $ sudo apt-get install git
  97    $ sudo apt-get install npm
  98    $ sudo apt-get install maven
  99    $ sudo apt-get install docker.io
 100    $ wget https://git.onap.org/oparent/plain/settings.xml
 101    $ mkdir ~/.m2
 102    $ cp settings.xml ~/.m2
 103
 104  If you get an error on some of the repos saying that oparent is
 105  unresolvable, using the example settings.xml file should solve this
 106  problem: `Setting Up Your Development
 107  Environment#MavenExamplesettings.xml
 108  <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment#SettingUpYourDevelopmentEnvironment-MavenExamplesettings.xml>`__
 109
 110 5. Set Up Repos
 111 ---------------
 112
 113  .. code-block:: bash
 114
 115    $ mkdir -p ~/src/aai
 116    $ cd ~/src/aai ; for f in aai-common schema-service resources traversal graphadmin logging-service ; do git clone ssh://<username>@gerrit.onap.org:29418/aai/$f; done
 117
 118 6. Checkout the 'dublin' branch
 119 -------------------------------
 120
 121  .. code-block:: bash
 122
 123     $ cd ~/src/aai ; for f in aai-common schema-service resources traversal graphadmin logging-service ; do (cd $f ; git checkout dublin) done | tee checkoutlog.txt
 124
 125 7. Janus Setup (part 1)
 126 -----------------------
 127
 128  Modify both janus-cached.properties and janus-realtime.properties to the following (for all MS’s that will connect to the local Cassandra backend)
 129
 130  .. code::
 131
 132    storage.backend=cassandra
 133    storage.hostname=localhost
 134    storage.cassandra.keyspace=onap # or different keyspace name of your choosing
 135
 136  Edit the following files:
 137
 138  .. code::
 139
 140    ~/src/aai/resources/aai-resources/src/main/resources/etc/appprops/janusgraph-cached.properties
 141    ~/src/aai/resources/aai-resources/src/main/resources/etc/appprops/janusgraph-realtime.properties
 142    ~/src/aai/traversal/aai-traversal/src/main/resources/etc/appprops/janusgraph-cached.properties
 143    ~/src/aai/traversal/aai-traversal/src/main/resources/etc/appprops/janusgraph-realtime.properties
 144    ~/src/aai/graphadmin/src/main/resources/etc/appprops/janusgraph-cached.properties
 145    ~/src/aai/graphadmin/src/main/resources/etc/appprops/janusgraph-realtime.properties
 146
 147 8. Build all the modules
 148 ------------------------
 149
 150  .. code-block:: bash
 151
 152    $ cd ~/src/aai ; for f in aai-common schema-service resources traversal graphadmin logging-service ; do (cd $f ; mvn versions:set -DnewVersion=0.0.1-TEST-SNAPSHOT && mvn -DskipTests clean install -Daai.schema.version=0.0.1-TEST-SNAPSHOT) done | tee log.txt 2>&1
 153
 154    $ grep -e "SUCCESS" -e "FAILURE" log.txt
 155
 156  And you should see:
 157
 158  .. code::
 159
 160    [INFO] aai-schema ......................................... SUCCESS [ 32.504 s]
 161    [INFO] aai-queries ........................................ SUCCESS [ 6.461 s]
 162    [INFO] aai-schema-service ................................. SUCCESS [02:17 min]
 163    [INFO] BUILD SUCCESS
 164    [INFO] aai-resources ...................................... SUCCESS [ 1.190 s]
 165    [INFO] BUILD SUCCESS
 166    [INFO] aai-resources ...................................... SUCCESS [ 3.210 s]
 167    [INFO] aai-resources ...................................... SUCCESS [ 41.213 s]
 168    [INFO] BUILD SUCCESS
 169    [INFO] aai-traversal ...................................... SUCCESS [ 1.090 s]
 170    [INFO] BUILD SUCCESS
 171    [INFO] aai-traversal ...................................... SUCCESS [ 3.181 s]
 172    [INFO] aai-traversal ...................................... SUCCESS [ 58.001 s]
 173    [INFO] BUILD SUCCESS
 174    [INFO] BUILD SUCCESS
 175    [INFO] BUILD SUCCESS
 176    [INFO] aai-logging-service ................................ SUCCESS [ 1.101 s]
 177    [INFO] BUILD SUCCESS
 178    [INFO] aai-logging-service ................................ SUCCESS [ 5.230 s]
 179    [INFO] Common Logging API ................................. SUCCESS [ 1.995 s]
 180    [INFO] EELF Logging Implementation ........................ SUCCESS [ 4.235 s]
 181    [INFO] Common Logging Distribution ........................ SUCCESS [ 0.530 s]
 182    [INFO] BUILD SUCCESS
 183
 184 9. Janus setup (part 2)
 185 -----------------------
 186
 187  Run this on the local instance on your first time running AAI and whenever using new keyspace or after wiping the data.
 188
 189  Install the schema
 190
 191  .. code-block:: bash
 192
 193     $ (cd ~/src/aai/graphadmin/ && mvn -PrunAjsc -Dstart-class=org.onap.aai.schema.GenTester -Daai.schema.version=0.0.1-TEST-SNAPSHOT -Daai.schema.ingest.version=0.0.1-TEST-SNAPSHOT -DskipTests -Dcheckstyle.skip=true -DAJSC_HOME=$HOME/src/aai/graphadmin -DBUNDLECONFIG_DIR=src/main/resources)
 194
 195  You should see:
 196
 197  .. code::
 198
 199    ---- NOTE --- about to open graph (takes a little while)--------;
 200    -- Loading new schema elements into JanusGraph --
 201    -- graph commit
 202    -- graph shutdown
 203
 204 10. Start the "resources" microservice
 205 --------------------------------------
 206
 207  Resources runs on port 8447.  Go to the resources directory
 208
 209  .. code-block:: bash
 210
 211     $ cd ~/src/aai/resources
 212
 213  Set the debug port to 9447
 214
 215   .. code-block:: bash
 216
 217      $ export MAVEN_OPTS="-Xms1024m -Xmx5120m -XX:PermSize=2024m -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=9447,server=y,suspend=n"
 218
 219  Start the microservice - adjust your build version accordingly
 220
 221  .. code-block:: bash
 222
 223      $ mvn -pl aai-resources -PrunAjsc -Daai.schema.version=0.0.1-TEST-SNAPSHOT -Daai.schema.ingest.version=0.0.1-TEST-SNAPSHOT -DskipTests -Dcheckstyle.skip=true
 224
 225  Should see something like this: Resources Microservice Started
 226
 227
 228 11. Verify the resources microservice
 229 -------------------------------------
 230
 231  This example uses curl from commandline
 232
 233  .. code-block:: bash
 234
 235     $ sudo apt-get install jq  # for pretty output
 236
 237  Download :download:`script - test-complex <media/test-complex>`
 238  Download :download:`data - data-complex.json <media/data-complex.json>`
 239
 240  .. code-block:: bash
 241
 242    $ sh ./test-complex 2>&1 | tee log.txt
 243
 244  Confirm log.txt contains:
 245
 246  .. code-block:: bash
 247
 248     > GET /aai/v16/cloud-infrastructure/complexes HTTP/1.1
 249
 250  .. code-block:: json
 251
 252     {
 253      "requestError": {
 254        "serviceException": {
 255          "messageId": "SVC3001",
 256          "text": "Resource not found for %1 using id %2 (msg=%3) (ec=%4)",
 257          "variables": [
 258            "GET",
 259            "cloud-infrastructure/complexes",
 260            "Node Not Found:No Node of type complex found at: cloud-infrastructure/complexes",
 261            "ERR.5.4.6114"
 262          ]
 263        }
 264      }
 265     }
 266
 267  Then followed by:
 268
 269  .. code-block:: bash
 270
 271     > PUT /aai/v16/cloud-infrastructure/complexes/complex/clli2 HTTP/1.1
 272     > GET /aai/v16/cloud-infrastructure/complexes/complex/clli2 HTTP/1.1
 273
 274  With payload:
 275
 276  .. code-block:: json
 277
 278    {
 279      "physical-location-id": "clli2",
 280      "data-center-code": "example-data-center-code-val-6667",
 281      "complex-name": "clli2",
 282      "identity-url": "example-identity-url-val-28399",
 283      "resource-version": "1543408364646",
 284      "physical-location-type": "example-physical-location-type-val-28399",
 285      "street1": "example-street1-val-28399",
 286      "street2": "example-street2-val-28399",
 287      "city": "example-city-val-28399",
 288      "state": "example-state-val-28399",
 289      "postal-code": "example-postal-code-val-28399",
 290      "country": "example-country-val-28399",
 291      "region": "example-region-val-28399",
 292      "latitude": "1111",
 293      "longitude": "2222",
 294      "elevation": "example-elevation-val-28399",
 295      "lata": "example-lata-val-28399"
 296    }
 297
 298  And finishes with:
 299
 300  .. code-block:: bash
 301
 302     > DELETE /aai/v16/cloud-infrastructure/complexes/complex/clli2?resource-version=1543408364646 HTTP/1.1
 303     > GET /aai/v16/cloud-infrastructure/complexes HTTP/1.1
 304
 305  With the following:
 306
 307  .. code-block:: json
 308
 309      {
 310      "requestError": {
 311        "serviceException": {
 312          "messageId": "SVC3001",
 313          "text": "Resource not found for %1 using id %2 (msg=%3) (ec=%4)",
 314          "variables": [
 315            "GET",
 316            "cloud-infrastructure/complexes",
 317            "Node Not Found:No Node of type complex found at: cloud-infrastructure/complexes",
 318            "ERR.5.4.6114"
 319          ]
 320        }
 321      }
 322    }
 323
 324 12. Start the "traversal" microservice
 325 --------------------------------------
 326
 327  Traversal runs on port 8446.  Go to the traversal directory
 328
 329  .. code-block:: bash
 330
 331     $ cd ~/src/aai/traversal
 332
 333  Set the debug port to 9446
 334
 335     $ export MAVEN_OPTS="-Xms1024m -Xmx5120m -XX:PermSize=2024m -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=9446,server=y,suspend=n"
 336
 337   Start the microservice - adjust your build version accordingly
 338
 339   .. code-block:: bash
 340
 341       $ mvn -pl aai-traversal -PrunAjsc -Daai.schema.version=0.0.1-TEST-SNAPSHOT -Daai.schema.ingest.version=0.0.1-TEST-SNAPSHOT -DskipTests -Dcheckstyle.skip=true
 342
 343   Should see something like this: Traversal Microservice Started
 344