docs/index.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 =============================
   4 Sparky - Inventory UI Service
   5 =============================
   6
   7 Architecture
   8 ============
   9 Sparky a service that interacts with AAI and provides users with a user interface to view and analyze AAI data. The main goal behind Sparky is to provide a clear and user friendly view of AAI data.
  10
  11 It is divided into both a front-end (the code that constructs the GUI) and a back-end (the Java code and other technologies that provide the front-end with its data). When Sparky is to be deployed, a .war file containing the front-end needs to be copied into the ``/src/main/resources/extApps`` directory. The back-end will then use this .war to present the front-end to users.
  12
  13 At this time, Sparky has two views available for use:
  14
  15 `View and Inspect <./VIEW_INSPECT.md>`_ - Graph-based view of entities within AAI
  16
  17 `VNFs <./VNFS.md>`_ - Aggregation-based view of VNFs within AAI
  18
  19 Interactions
  20 ------------
  21 Sparky requires connections to the following additional services:
  22
  23 Front-end:
  24
  25 - A Sparky back-end to serve the front-end
  26
  27 Back-end:
  28
  29 - An AAI instance as the main driver behind data
  30 - An Elasticsearch instance for data storage (a Synapse service instance is an implicit dependency which populates the Elasticsearch indexes)
  31 - A Search Data Service instance for search functionality
  32 - An eCOMP Portal instance for authentication
  33
  34 Logging
  35 =======
  36 Sparky uses the Logback framework to generate logs. The logback.xml file can be found under the ``src/main/resources/`` folder
  37
  38 Installation
  39 ============
  40
  41 Steps: Back-end
  42 ---------------
  43
  44 Clone Git Repository
  45 ********************
  46 Clone the Sparky back-end Git repository
  47
  48 Build
  49 *****
  50
  51 After cloning the project, build the project by executing the following Maven command from the project's top level directory:
  52
  53 .. code-block:: bash
  54
  55    mvn clean install
  56
  57 After a successful install, build the docker image:
  58
  59 .. code-block:: bash
  60
  61    docker build -t openecomp/sparky target
  62
  63 Deploy
  64 ******
  65
  66 Push the Docker image that you have built to your Docker repository and pull it down to the location that you will be running Sparky.
  67
  68 Create the following directories on the host machine:
  69
  70 - /logs
  71 - /opt/app/sparky/appconfig
  72
  73 You will be mounting these as data volumes when you start the Docker container.
  74
  75 Clone Configuration Repository
  76 ******************************
  77
  78 Clone the "test-config" repo to a seperate directory.
  79 Navigate to ``[test-config repo location]/sparky/appconfig`` (will contain files such as ``aai.properties``).
  80
  81 Copy the entire contents of ``[test-config repo location]]/sparky/appconfig`` into the ``/opt/app/sparky/appconfig`` directory you created in an above step.
  82
  83 Steps: Front-end
  84 ----------------
  85
  86 Clone Git Repository
  87 ********************
  88 Clone the ``sparky-fe.git`` Sparky back-end Git repository
  89
  90 Install Required Tools
  91 **********************
  92 You will need to install the following tools:
  93
  94 - node.js, including the Node Package Manager (NPM) (if there issues installing the latest version, try 6.10.1)
  95 - Python 2.7.13
  96
  97 After installing node.js and NPM, you need to install the required node.js packages by executing:
  98
  99 .. code-block:: bash
 100
 101  npm install
 102
 103 Build
 104 *****
 105
 106 **To build the front-end (generate a .war file)**:
 107
 108 Execute:
 109
 110 .. code-block:: bash
 111
 112  gulp build
 113
 114 The build will create a directory called ``dist`` and add the ``aai.war`` file to it.
 115
 116 If changes to the build flow are required, updating ``webpack.config.js`` and ``gulpfile.js`` will likely provide any build tuning that is required.
 117
 118 **To run the front-end:**
 119
 120 Execute:
 121
 122 .. code-block:: bash
 123
 124  npm start
 125
 126 By default the local instance of the UI will be served to ``https://localhost:8001/aai/#/viewInspect``.
 127
 128 This can be configured in the file ``webpack.devConfig.js``.
 129
 130 Deploy
 131 ******
 132
 133 Push the Docker image that you have built to your Docker repository and pull it down to the location that you will be running Sparky.
 134
 135 **Create the following directories on the host machine:**
 136
 137 - /logs
 138 - /opt/app/sparky/appconfig
 139
 140 You will be mounting these as data volumes when you start the Docker container.
 141
 142 Configuration
 143 =============
 144
 145 Steps: Back-end
 146 ---------------
 147
 148 Edit property files in /opt/app/sparky/appconfig
 149 ************************************************
 150
 151 Listed below are the values that will need to be updated to make Sparky operate properly. The configuration files contain comments for contents not listed here.
 152
 153 **search-service.properties:**
 154
 155 search-service.ipAddress=*[ip address / hostname of the search-data-service that this instance will use]*
 156 search-service.httpPort=[http port of the search-data-service that this instance will use]
 157
 158 **aai.properties:**
 159
 160 aai.rest.host= *[ip address / hostname of the aai that this instance will use]*
 161
 162 aai.rest.port= *[rest port of the aai that this instance will use]*
 163
 164 **elasticsearch.properties:**
 165
 166 elasticsearch.ipAddress= *[ip address / hostname of the elasticsearch that this instance will use*]
 167 elasticsearch.httpPort=*[http port of the elasticsearch that this instance will use*]
 168 elasticsearch.javaApiPort=*[java api port of the elasticsearch that this instance will use*]
 169
 170 **portal/portal.properties:**
 171 **portal/portal-authentication.properties:**
 172
 173 If this instance of Sparky will be served in an eCOMP Portal instance, use the two files above to configure against the proper Portal instance.