README.md

   1 # ONAP SDC
   2
   3 ## Introduction
   4
   5 SDC is the ONAP visual modeling and design tool. It creates internal metadata that describes assets used by all ONAP components, both at design time and run time.
   6
   7 The SDC manages the content of a catalog and logical assemblies of selected catalog items to completely define how and when VNFs are realized in a target environment.
   8 A complete virtual assembly of specific catalog items, together with selected workflows and instance configuration data, completely defines how the deployment, activation, and life-cycle management of VNFs are accomplished.
   9
  10 SDC manages four levels of assets:
  11
  12 * Resource - A fundamental capability, implemented either entirely in software, or as software that interacts with a hardware device.
  13 Each Resource is a combination of one or more Virtual Function Components (VFCs), along with all the information necessary to instantiate, update, delete and manage the Resource.
  14 * Service - A well-formed object comprising one or more Resources. Service Designers create Services from Resources, and include all of the information about the Service needed to instantiate, update, delete and manage the Service.
  15
  16 The key output of SDC is a set of models containing descriptions of asset capabilities and instructions to manage them. These models are stored in the SDC Master Reference Catalog for the entire enterprise to use.
  17
  18 There are four major components of SDC:
  19
  20 * Catalog - The repository for assets at the Resource, Service and Product levels. Assets are added to the Catalog using the Design Studio.
  21 * Design Studio - Used to create, modify and add Resource, Service and Product definitions in the Catalog.
  22 * Certification Studio - Available in a future release, is used to test new assets at all levels. It will be used for sandbox experimentation, and will include support for automated testing.
  23 * Distribution Studio - Used to deploy certified assets. From the Distribution studio, new Product assets, including their underlying Resources and Services, are deployed into lab environments for testing purposes, and into production after certification is complete. In a future release, there will be a way to export Product information to external Business Support Systems for customer ordering and billing.
  24
  25 ## Git Configuration
  26
  27 Note that if you're working on Windows, it's important to enable long paths for your machine; otherwise git won't be able to handle some files.
  28
  29 In order to do so just add this section to your global git.config file under the `[core]` key:
  30
  31     longpaths = true
  32
  33 ## Compiling the Project
  34
  35 SDC is built from several projects while the parent "sdc" contains the main pom.xml for all of them:
  36 - asdctool              - set of utilities used for scheme creation and data migration in SDC
  37 - catalog-be            - backend code
  38 - catalog-fe            - frontend java code (servlet, proxy)
  39 - catalog-dao           - database layer
  40 - catalog-model         - data model of the application
  41 - catalog-ui            - front end code (javascript, html, css)
  42 - common                - set of utilities used by the onboarding project
  43 - common-app-api        - common code for frontend and backend
  44 - common-be             - utilities, datatypes and enums
  45 - security-utils        - handle encryption/decryption of passwords
  46 - onboarding-be         - onboarding backend code
  47 - onboarding-ui         - onboarding frontend code
  48 - test-apis-ci          - the automation framework used by SDC for API based testing
  49 - ui-ci                 - the automation framework used by SDC for UI based testing, based on Selenium
  50 - sdc-os-chef           - chefs scripts used for docker creation and startup
  51 - utils                 - set of dev utils used for working with the project locally
  52
  53
  54 In order to build all the projects, as mentioned in the onap wiki https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment, the settings.xml (https://git.onap.org/oparent/plain/settings.xml) from the oparent project must be installed in your ~/.m2 folder and referenced by your IDE.
  55 Once maven is set up properly, go to sdc project and run the command: `mvn clean install`
  56
  57 Currently SDC build process also supports docker building.
  58 Note that if you're working on Windows, you'll need to define an environment variable on your machine with key `DOCKER_HOST` and value: `tcp://<ip_address>:2375` in order to build and upload local dockers to a local environment.
  59
  60 For the dockers to be built during the build process use the "docker" profile by adding `-P docker` to the `mvn clean install` command
  61
  62 More flags to use in the build process are:
  63 * -DskipTests - Skips unit tests execution
  64 * -DskipUICleanup=true - Skips deleting the UI folders
  65 * -Djacoco.skip=true - Skips running jacoco tests
  66 * -DskipPMD - Skips creating a PMD report
  67
  68 **using those flags will speed up the building process of the project**
  69
  70 ## Accessing SDC
  71
  72 In order to access the sdc from your local vagrant environment you'll need to run the webseal_simulator docker.
  73 This can be achieved by using the command: `/data/scripts/simulator_docker_run.sh`
  74
  75 To access the simulator just go to this url: `http://<ip_address>:8285/login`
  76
  77 For more information regarding using the webseal_simulator please refer to the following guide: [SDC Simulator](https://wiki.onap.org/display/DW/SDC+Simulator)
  78
  79 ## Accessing SDC UI in Dev Mode
  80
  81 In order to access the SDC UI from your dev environment you need to do the following:
  82
  83 1. Go to file `webpack.server.js` found under the catalog-ui folder in the main sdc project and update the "localhost" variable to be the ip of your local vagrant machine.
  84 2. Navigate to the catalog-ui folder and run the command: `npm start -- --env.role <wanted_role>` with the wanted role to login to SDC as.
  85
  86 ## SDC Containers
  87
  88 The following table shows the SDC containers found on the vagrant after a successful build:
  89
  90 | Name                | Description                                                                                                                                   |
  91 |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
  92 | sdc-cs              | The Docker contains our Cassandra server. On docker startup the Cassandra server is started.                                                  |
  93 | sdc-cs-init         | The docker contains the logic for creating the needed schemas for SDC catalog server,  On docker startup, the schemes are created.            |
  94 | sdc-cs-onboard-init | The docker contains the logic for creating the needed schemas for SDC onboarding server, On docker startup, the schemes are created.          |
  95 | sdc-es              | The Docker contains Elastic Search server. On docker startup, Elastic Search server is started.                                               |
  96 | sdc-init-es         | The Docker contains the logic for creating the needed mapping for SDC and the views for kibana. On docker startup, the mapping is created.    |
  97 | sdc-onboard-BE      | The Docker contains the onboarding Backend Jetty server. On docker startup, the Jetty server is started with the application.                 |
  98 | sdc-BE              | The Docker contains the catalog Backend Jetty server. On docker startup, the Jetty server is started with the application.                    |
  99 | sdc-BE-init         | The docker contains the logic for importing the SDC Tosca normative types and the logic for configuring external users for SDC external APIs. |
 100 |                     | On startup, the docker executes the rest calls to the catalog server.                                                                         |
 101 | sdc-FE              | The Docker contains the SDC Fronted Jetty server. On docker startup, the Jetty server is started with our application.                        |
 102
 103 For further information and an image explaining the containers dependency map please refer to the following page: [SDC Docker Diagram](https://wiki.onap.org/display/DW/SDC+Troubleshooting)
 104
 105 ## Testing the Project
 106
 107 The dockers that are responsible for running automation tests in the local environment are built as part of SDC docker profile build.
 108
 109 In order to run the automation tests when starting the dockers on the machine, there are 2 flags to use:
 110
 111 * -tad - Use this flag to run the default suite of API tests
 112 * -tud - Use this flag to run the default suite of UI tests
 113
 114 This link lists all the commands in the vagrant-onap: [Vagrant Common Commands](https://wiki.onap.org/display/DW/SDC+Vagrant+Common+Commands)
 115
 116 SDC docker_run script is documented here: [SDC docker_run Script Usage](https://wiki.onap.org/display/DW/SDC+docker_run+Script+Usage)
 117
 118 For more information regarding testing the project please refer to the following guide: [SDC Sanity](https://wiki.onap.org/display/DW/SDC+Sanity)
 119
 120 ## SDC on OOM
 121
 122 For more information regarding SDC on OOM please refer to the following page: [SDC on OOM](https://wiki.onap.org/display/DW/SDC+on+OOM)
 123
 124 ## Frontend Local Env - onboarding
 125
 126 ### Steps:
 127
 128 Install nodejs & gulp
 129 1. download nodejs from here: https://nodejs.org/en/ (take the "current" version with latest features) & install it.
 130 2. install gulp by running the following command: npm install --global gulp-cli
 131
 132 ### Install DOX-UI a:
 133
 134 1. pull for latest changes
 135 2. go to folder dox-sequence-diagram-ui
 136 3. run npm install
 137 4. wait for it...
 138 5. go to folder dox-ui
 139 6. run npm install
 140 7. create a copy of devConfig.defaults.json file and name it devConfig.json (we already configured git to ignore it so it will not be pushed)
 141 8. in that file, populate the fields of the IP addresses of your BE machine you'd like to connect (pay attention, it is a JSON file): For example http://<host>:<port>
 142 9. after everything is successful, run gulp
 143 10. after server is up, your favorite UI will wait for you at: http://localhost:9000/sdc1/proxy-designer1#/onboardVendor
 144
 145 ### Troubleshooting:
 146
 147 | Problem                       |   Why is this happening | Solution                                                                                   |
 148 |-------------------------------|-------------------------|--------------------------------------------------------------------------------------------|
 149 | npm cannot reach destination  | onboarding proxy        | When within onboarding network, you should set onboarding proxy to NPM as the following:   |
 150 |                               |                         | npm config set proxy http://genproxy:8080                                                  |
 151 |                               |                         | npm config set https-proxy http://genproxy:8080                                            |
 152 |                               |                         |                                                                                            |
 153 | git protocol is blocked       | onboarding network      | When within onboarding network, you should set globally that when git                      |
 154 | and cannot connect            | rules for protocols     | protocol is used, it will be replaced with "https"                                         |
 155 |                               |                         | git config --global url."https://".insteadOf git://                                        |
 156 --------------------------------------------------------------------------------------------------------------------------------------------------------
 157
 158 ## SDC Troubleshooting
 159
 160 In order to check the life state of SDC you can run the command `health` from inside the vagrant.
 161 Alternatively you can run the following commands to check the FE and BE status:
 162
 163 FE - `curl http://<ip_address>:8181/sdc1/rest/healthCheck`
 164
 165 BE - `curl http://<ip_address>:8080/sdc2/rest/healthCheck`
 166
 167 Another method to check about problems in SDC is to look at the log files.
 168 The log files of the SDC can be found in the `/data/logs` folder
 169
 170 The docker logs are found under the directory `/docker_logs`.
 171
 172 The jetty(Applicative) are found in the respective folder according to the wanted section
 173 For example, the BE logs will found under the directory `/BE`.
 174
 175 For more information regarding SDC Troubleshooting please refer to the following guide: [SDC Troubleshooting](https://wiki.onap.org/display/DW/SDC+Troubleshooting)
 176
 177 ## Getting Help
 178
 179 #####  [Mailing list](mailto:onap-sdc@lists.onap.org)
 180
 181 ##### [JIRA](http://jira.onap.org)
 182
 183 ##### [WIKI](https://wiki.onap.org/display/DW/Service+Design+and+Creation+%28SDC%29+Portal)