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