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 .. image:: https://bestpractices.coreinfrastructure.org/projects/1737/badge
   8    :height: 30px
   9    :width: 200 px
  10    :scale: 100 %
  11    :alt: alternate text
  12    :align: right
  13    :target: https://bestpractices.coreinfrastructure.org/projects/1737
  14
  15 Architecture
  16 ============
  17 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.
  18
  19 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.
  20
  21 At this time, Sparky has two views available for use:
  22
  23 .. toctree::
  24    :maxdepth: 1
  25
  26    Graph-based view of entities within AAI <./view_inspect>
  27    Aggregation-based view of VNFs within AAI VNFs <./vnfs>
  28
  29 Interactions
  30 ------------
  31 Sparky requires connections to the following additional services:
  32
  33 Front-end:
  34
  35 - A Sparky back-end to serve the front-end
  36
  37 Back-end:
  38
  39 - An AAI instance as the main driver behind data
  40 - An Elasticsearch instance for data storage (a Synapse service instance is an implicit dependency which populates the Elasticsearch indexes)
  41 - A Search Data Service instance for search functionality
  42 - An eCOMP Portal instance for authentication
  43
  44 Logging
  45 =======
  46 Sparky uses the Logback framework to generate logs. The logback.xml file can be found under the ``src/main/resources/`` folder
  47
  48 Installation
  49 ============
  50
  51 Steps: Back-end
  52 ---------------
  53
  54 Clone Git Repository
  55 ********************
  56 Clone the Sparky back-end Git repository
  57
  58 Build
  59 *****
  60
  61 After cloning the project, build the project by executing the following Maven command from the project's top level directory:
  62
  63 .. code-block:: bash
  64
  65    mvn clean install
  66
  67 After a successful install, build the docker image:
  68
  69 .. code-block:: bash
  70
  71    docker build -t openecomp/sparky target
  72
  73 Deploy
  74 ******
  75
  76 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.
  77
  78 Create the following directories on the host machine:
  79
  80 - /logs
  81 - /opt/app/sparky/appconfig
  82
  83 You will be mounting these as data volumes when you start the Docker container.
  84
  85 Clone Configuration Repository
  86 ******************************
  87
  88 Clone the "test-config" repo to a seperate directory.
  89 Navigate to ``[test-config repo location]/sparky/appconfig`` (will contain files such as ``aai.properties``).
  90
  91 Copy the entire contents of ``[test-config repo location]]/sparky/appconfig`` into the ``/opt/app/sparky/appconfig`` directory you created in an above step.
  92
  93 Steps: Front-end
  94 ----------------
  95
  96 Clone Git Repository
  97 ********************
  98 Clone the ``sparky-fe.git`` Sparky back-end Git repository
  99
 100 Install Required Tools
 101 **********************
 102 You will need to install the following tools:
 103
 104 - node.js, including the Node Package Manager (NPM) (if there issues installing the latest version, try 6.10.1)
 105 - Python 2.7.13
 106
 107 After installing node.js and NPM, you need to install the required node.js packages by executing:
 108
 109 .. code-block:: bash
 110
 111  npm install
 112
 113 Build
 114 *****
 115
 116 **To build the front-end (generate a .war file)**:
 117
 118 Execute:
 119
 120 .. code-block:: bash
 121
 122  gulp build
 123
 124 The build will create a directory called ``dist`` and add the ``aai.war`` file to it.
 125
 126 If changes to the build flow are required, updating ``webpack.config.js`` and ``gulpfile.js`` will likely provide any build tuning that is required.
 127
 128 **To run the front-end:**
 129
 130 Execute:
 131
 132 .. code-block:: bash
 133
 134  npm start
 135
 136 By default the local instance of the UI will be served to ``https://localhost:8001/aai/#/viewInspect``.
 137
 138 This can be configured in the file ``webpack.devConfig.js``.
 139
 140 Deploy
 141 ******
 142
 143 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.
 144
 145 **Create the following directories on the host machine:**
 146
 147 - /logs
 148 - /opt/app/sparky/appconfig
 149
 150 You will be mounting these as data volumes when you start the Docker container.
 151
 152 Configuration
 153 =============
 154
 155 Steps: Back-end
 156 ---------------
 157
 158 Edit property files in /opt/app/sparky/appconfig
 159 ************************************************
 160
 161 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.
 162
 163 **search-service.properties:**
 164
 165 search-service.ipAddress=*[ip address / hostname of the search-data-service that this instance will use]*
 166 search-service.httpPort=[http port of the search-data-service that this instance will use]
 167
 168 **aai.properties:**
 169
 170 aai.rest.host= *[ip address / hostname of the aai that this instance will use]*
 171
 172 aai.rest.port= *[rest port of the aai that this instance will use]*
 173
 174 **elasticsearch.properties:**
 175
 176 elasticsearch.ipAddress= *[ip address / hostname of the elasticsearch that this instance will use*]
 177 elasticsearch.httpPort=*[http port of the elasticsearch that this instance will use*]
 178 elasticsearch.javaApiPort=*[java api port of the elasticsearch that this instance will use*]
 179
 180 **portal/portal.properties:**
 181 **portal/portal-authentication.properties:**
 182
 183 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.