docs/platform/installation.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 Installation and Developer Setup
   4 ================================
   5
   6 Project Structure
   7 -----------------
   8
   9 Sparky is structured with a top level project that contains two sub-projects (application and service projects). The application project contains the configuration and spring application code that customizes and runs sparky as an application. The service project contains the core sparky code that provides functionality for sparky-fe requests and synchronization.
  10
  11 In regards to the front-end (sparky-fe), sparky-be serves up the sparky-fe web content and sparky-be deals with all inter-microservice communications.
  12
  13 Clone, Build, & Configure
  14 =========================
  15
  16 Clone & Build
  17 -------------
  18
  19 Clone the sparky-be repository into a directory of your choice.
  20
  21 .. code-block:: bash
  22
  23     git clone ssh://<username>@gerrit.onap.org:29418/aai/sparky-be
  24
  25 After cloning the project (sparky-be), build the project by executing the following Maven command from the project's top level directory:
  26
  27 .. code-block:: bash
  28
  29    mvn clean install
  30
  31 Configuration
  32 -------------
  33
  34 All configuration for running sparky is found in ``<working directory>/sparkybe-onap-application/config``.
  35
  36 Profiles
  37 --------
  38
  39 *application.properties* is the main configuration point for the sparky application. Within this file the *spring.profiles* are set. Each spring profile has configuration that will be loaded into an associated spring bean. The currently available profiles:
  40
  41   * camel
  42   * http | ssl
  43   * portal
  44   * fe-dev | fe-prod
  45   * oxm-default | oxm-override
  46   * resources | gizmo
  47   * sync
  48   * oxm-schema-dev | oxm-schema-prod
  49
  50 Profile descriptions:
  51
  52   * camel - Enables spring-boot camel routing rules
  53   * http - Sets Sparky's communication protocol to HTTP
  54   * ssl - Sets Sparky's communication protocol to HTTPS
  55   * portal - Adds ONAP portal processing to Sparky's flow
  56   * fe-dev - Exposes the static folder for UI development when running Sparky locally (target/static)
  57   * fe-prod - Exposes the standard path for the UI in the docker container
  58   * oxm-default - Sets the default version and version list of OXM files to be used
  59   * oxm-override - Sets a custom version and version list of OXM files to be used
  60   * resources - Sparky will use aai-resources (microservice) as the primary source of inventory information
  61   * gizmo - Sparky will use gizmo (microservice) as the primary source of inventory information
  62   * sync - Will cause Sparky to run any configured synchronizers to populate index data in a single large transaction
  63   * oxm-schema-dev - Sets the location to find the OXM files within a development environment
  64   * oxm-schema-prod - Sets the location to find the OXM files within a deployed environment
  65
  66 The idea behind the profiles is to create a simple approach to adjusting runtime behavior without needing to edit large xml files (see **Spring Beans** below). Ahead of running Sparky, some of the profiles will need to be edited to work within your environment (e.g. set where your custom OXM files need to be loaded from).
  67
  68 Spring Beans
  69 ------------
  70
  71 The *spring-beans* directory contains all the .xml bean representations that will be auto-wired at runtime. Some of the beans are associated with a single profile (see "profile=" in header of bean declaration), and others will be loaded with differing values depending the profile used.
  72
  73 Scanning through the beans and cross-referencing with their associated Java classes is a good way of getting familiar with the startup and runtime of Sparky.
  74
  75 Authorization
  76 -------------
  77
  78 Within the "auth" directory are any certs needed to communicate within the environment you are currently working in (remember Sparky can be configured to run using HTTP).
  79
  80 Filters
  81 -------
  82
  83 The "filters" directory contains the JSON descriptor files that describe the filters used in the VNFs view.
  84
  85 Logging
  86 -------
  87
  88 Sparky uses the Logback framework to generate logs. The logback.xml is contained in the "logging" directory.
  89
  90 Running Locally
  91 ===============
  92
  93 The configuration described in this section will be in reference to running Sparky through Eclipse. The same steps can be applied to running via bash/cmd with minor tweaks.
  94
  95 Sparky should be built ahead of running (``mvn clean install``). It's useful to add a build configuration to Eclipse to build Sparky.
  96
  97 The run configuration should contain the following:
  98
  99 * The configuration should be created based off of the "Maven Build" template
 100 * "Main" tab
 101     * Build directory - ${workspace_loc:/sparky-be/sparkybe-onap-application}
 102     * Goals - spring-boot:run
 103     * Parameter table
 104         * name: CONFIG_HOME value: ${workspace_loc:/sparky-be/sparkybe-onap-application}/config
 105         * name: APP_HOME value: ${workspace_loc:/sparky-be/sparkybe-onap-application}
 106
 107 Deploying Sparky
 108 ================
 109
 110 At time of writing (Oct 2018) Sparky is primarily deployed into a Kubernetes environment or a "pure" docker environment using custom chef parametrization. How you want to deploy Sparky is up to you. At a high level, the cleanest approach is ensuring your configured property (profiles) files are copied into the docker container so the Spring context has access to the values which will in turn start Sparky using your configured values.
 111
 112 See ``sparky-be/sparkybe-onap-application/src/main/docker`` -> Dockerfile for details on how Sparky runs within a Docker container.
 113
 114 Front-End (sparky-fe) Details
 115 =============================
 116
 117 Clone, Build, & Configure
 118 -------------------------
 119
 120 Clone the sparky-fe repository into a directory of your choice.
 121
 122 Dependencies
 123 ------------
 124 You will need to install the following tools:
 125
 126 * node.js, including the Node Package Manager (NPM) (if there issues installing the latest version, try 6.10.1)
 127 * Python 2.7.13
 128
 129 After installing node.js and NPM, you need to install the required node.js packages by navigating to the top level sparky-fe directory and executing:
 130
 131 .. code-block:: bash
 132
 133  npm install
 134
 135 Build
 136 -----
 137
 138 To build sparky-fe (generate a .war file):
 139
 140 Execute:
 141
 142 .. code-block:: bash
 143
 144  gulp build
 145
 146 The build will create a directory called ``dist`` and add the ``aai.war`` file to it.
 147
 148 If changes to the build flow are required, updating ``webpack.config.js`` and ``gulpfile.js`` will likely provide any build tuning that is required.
 149
 150 Running sparky-fe Locally
 151 =========================
 152
 153 Execute:
 154
 155 .. code-block:: bash
 156
 157  npm start
 158
 159 By default the local instance of the UI will be served to ``http(s)://localhost:8001/``.
 160
 161 Deploy sparky-fe
 162 ================
 163
 164 If you have access to a container repository (e.g. Nexus), push the .war image that you have built to your repository and configure your sparky-be ``sparkybe-onap-application/pom.xml`` to pull your sparky-fe image.