README.md

   1 # ONAP SDC
   2
   3 [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=bugs)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
   4 [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
   5 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=coverage)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
   6 [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
   7 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
   8 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
   9 [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
  10 [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
  11 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
  12 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
  13 [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=onap_sdc&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=onap_sdc)
  14
  15 ## Introduction
  16
  17 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.
  18
  19 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.
  20 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.
  21
  22 SDC manages four levels of assets:
  23
  24 * Resource - A fundamental capability, implemented either entirely in software, or as software that interacts with a hardware device.
  25 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.
  26 * 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.
  27
  28 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.
  29
  30 There are four major components of SDC:
  31
  32 * Catalog - The repository for assets at the Resource, Service and Product levels. Assets are added to the Catalog using the Design Studio.
  33 * Design Studio - Used to create, modify and add Resource, Service and Product definitions in the Catalog.
  34 * 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.
  35 * 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.
  36
  37 ## Git Configuration
  38
  39 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.
  40
  41 In order to do so just add this section to your global git.config file under the `[core]` key:
  42
  43     longpaths = true
  44
  45 ## Compiling the Project
  46
  47 SDC is built from several projects while the parent "sdc" contains the main pom.xml for all of them:
  48 - asdctool              - set of utilities used for scheme creation and data migration in SDC
  49 - catalog-be            - backend code
  50 - catalog-fe            - frontend java code (servlet, proxy)
  51 - catalog-dao           - database layer
  52 - catalog-model         - data model of the application
  53 - catalog-ui            - front end code (javascript, html, css)
  54 - common                    - set of utilities used by the onboarding project
  55 - common-app-api        - common code for frontend and backend
  56 - common-be                 - utilities, datatypes and enums
  57 - security-utils        - handle encryption/decryption of passwords
  58 - onboarding-be         - onboarding backend code
  59 - onboarding-ui         - onboarding frontend code
  60 - integration-tests - The integration tests using the docker images to validate Backend API calls and FE with Selenium
  61 - sdc-os-chef           - chefs scripts used for docker creation and startup
  62 - utils                     - set of dev utils used for working with the project locally
  63
  64
  65 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.
  66 Once maven is set up properly, go to sdc project and run the command: `mvn clean install`
  67
  68 By default, the "all" maven profile will be executed but others exist:
  69 * fast-build - A fast build skipping all tests and useless maven plugins (only builds the jars)
  70 * start-sdc - Once docker containers have been build, triggering this profile starts SDC CS, BE, FE, simulator
  71 * stop-sdc - Stop all SDC containers started by using the profile "start-sdc"
  72 * run-integration-tests - This runs only the integration tests against a running SDC started by using "start-sdc" profile.
  73 * docker - This enables the docker images build for each SDC module
  74     **Note: 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.**
  75
  76 More flags to use in the build process are:
  77 * -DskipITs - Skips integration tests only
  78 * -DskipTests - Skips unit tests execution and integration tests
  79 * -DskipUICleanup=true - Skips deleting the UI folders
  80 * -Djacoco.skip=true - Skips running jacoco tests
  81 * -DskipPMD - Skips creating a PMD report
  82
  83 ## Accessing SDC
  84
  85 After having started SDC with the command `mvn clean install -P start-sdc`, you can access it by accessing this URL: `http://<ip_address>:8285/login`
  86
  87 [Swagger UI](http://localhost:8080/swagger-ui/index.html) lists some endpoints available from catalog-BE. `http://<IP_ADDRESS>:8080/swagger-ui/index.html`
  88
  89 As ONAP AAF is not present, the url provided uses the 8285 simulator ports, just click on the user you want to use for accessing SDC (i.e. Carlos Santana)
  90
  91 For more information regarding using the webseal_simulator please refer to the following guide: [SDC Simulator](https://wiki.onap.org/display/DW/SDC+Simulator)
  92
  93 ### SDC Containers
  94
  95 The following table shows the SDC containers found after a maven "start-sdc":
  96
  97     CONTAINER ID        IMAGE                                    COMMAND                  CREATED             STATUS                      PORTS                                                                              NAMES
  98     968a8168e412        onap/sdc-backend-init:latest             "/bin/sh -c /home/${…"   9 minutes ago       Exited (0) 54 seconds ago                                                                                      sdc-backend-init-1
  99     621c0fda1b0f        onap/sdc-backend-all-plugins:latest      "sh -c ${JETTY_BASE}…"   9 minutes ago       Up 9 minutes                0.0.0.0:4000->4000/tcp, 0.0.0.0:8080->8080/tcp, 0.0.0.0:8443->8443/tcp             sdc-backend-all-plugins-1
 100     d823078776d8        onap/sdc-onboard-backend:latest          "sh -c ${JETTY_BASE}…"   9 minutes ago       Up 9 minutes                0.0.0.0:4001->4001/tcp, 0.0.0.0:8081->8081/tcp, 0.0.0.0:8445->8445/tcp, 8080/tcp   sdc-onboard-backend-1
 101     4729b0b7f0fe        onap/sdc-simulator:latest                "sh -c ${JETTY_BASE}…"   9 minutes ago       Up 9 minutes                0.0.0.0:8285->8080/tcp, 0.0.0.0:8286->8443/tcp                                     sdc-simulator-1
 102     583e0d7fa300        onap/sdc-onboard-cassandra-init:latest   "/home/sdc/startup.sh"   9 minutes ago       Exited (0) 9 minutes ago                                                                                       sdc-onboard-cassandra-init-1
 103     92085524f19f        onap/sdc-cassandra-init:latest           "/home/sdc/startup.sh"   10 minutes ago      Exited (0) 9 minutes ago                                                                                       sdc-cassandra-init-1
 104     c6e90dd7ddaf        selenium/standalone-firefox:2.53.1       "/opt/bin/entry_poin…"   10 minutes ago      Up 10 minutes               0.0.0.0:4444->4444/tcp                                                             standalone-firefox-1
 105     e02139c0379b        onap/sdc-frontend:latest                 "sh -c ${JETTY_BASE}…"   10 minutes ago      Up 10 minutes               0.0.0.0:6000->6000/tcp, 0.0.0.0:8181->8181/tcp, 0.0.0.0:9443->9443/tcp, 8080/tcp   sdc-frontend-1
 106     96843fae9e4c        onap/sdc-cassandra:latest                "/root/startup.sh"       10 minutes ago      Up 10 minutes               7000-7001/tcp, 7199/tcp, 9160/tcp, 0.0.0.0:9042->9042/tcp                          sdc-cassandra-1
 107
 108 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)
 109
 110
 111 ### Accessing the logs
 112
 113 To access the logs, there are different options:
 114 * Connect to the docker container you want to inspect by doing `docker exec -it -u root sdc-XXXXXXXX-1 sh`
 115     * Then look at the logs generally in /var/lib/jetty/logs or /var/log/onap (that may differ !)
 116 * A volume is shared between the BE, onboard-BE and FE containers, this volume is mapped to `/tmp/sdc-integration-tests`,
 117     * In that folder you can obtain the logs of the different containers
 118
 119 ### Debugging SDC
 120
 121 After having started SDC with the command `mvn clean install -P start-sdc`, different java remote debug ports are opened by default:
 122 * Onboard Backend - 4001 (jetty)
 123 * Backend - 4000 (jetty)
 124 * Frontend - 6000 (jetty)
 125 It's therefore possible to connect your IDE to those debug ports remotely to walk through the code and add some breakpoints.
 126
 127 **Look at the pom.xml of the integration-tests module to have a better understanding of all the docker settings provided to start SDC.**
 128
 129 ### Integration tests
 130 The integration are composed of 2 parts, one to test the BE Apis and another one to test the FE with selenium.
 131
 132 The selenium tests make use of the selenium/standalone-firefox:2.53.1 container.
 133
 134 About BE APIs tests, onboarding E2E flow :
 135 Onboarding E2E flow cover following SDC functionality:
 136
 137     Onboard of VNF
 138     Create VF from VSP
 139     Certify VF
 140     Create Service
 141     Add VF to service
 142
 143     Certify Service
 144     Export TOSCA and validate it structure using external TOSCA parser
 145
 146 **as part of execution we open a connection to Titan and perform resources clean up both before and after tests execution (only resource with “ci” prefix will be deleted from the catalog)
 147 List of VNFs/PNFs that proceed by onboarding flow, located in `integration-tests/src/test/resources/Files/`)
 148
 149     sample-signed-pnf-cms-includes-cert-1.0.1-SNAPSHOT.zip
 150     sample-signed-pnf-1.0.1-SNAPSHOT.zip
 151     sample-pnf-1.0.1-SNAPSHOT.csar
 152     sample-pnf-custom-type.csar
 153     base_vfw.zi
 154     base_vvg.zip
 155     database-substitution-mappings.csar
 156     helm.zip
 157     Huawei_vHSS.csar
 158     Huawei_vMME.csar
 159     infra.zip
 160     resource-ZteEpcMmeVf-csar_fix.csar
 161     vbng.zip
 162     vbrgemu.zip
 163     vfw.zip
 164     vgmux.zip
 165     vgw.zip
 166     vLB.zip
 167     vLBMS.zip
 168     vSBC_update_v03.csar
 169     vsp-vgw.csar
 170     vvg.zip
 171     ZteEpcMmeVf.csar
 172
 173 #### Start the integration tests manually
 174
 175 Those tests execute the following
 176 There are 2 options to start them:
 177 * After having started SDC with the command `mvn clean install -P start-sdc`, run the command `mvn clean install -P run-integration-tests`
 178 * If you want to debug them and run them from your IDE, you must start them from the testNG Suites files, otherwise this won't work.
 179   The test suites are located here:
 180   * BE: `integration-tests/src/test/resources/ci/testSuites/backend`
 181   * FE: `integration-tests/src/test/resources/ci/testSuites/frontend`
 182
 183 #### Integration tests with Helm Validator
 184
 185 Those tests use container built externally in other ONAP repository: [sdc/sdc-helm-validator](https://gerrit.onap.org/r/admin/repos/sdc/sdc-helm-validator)
 186
 187 You can run those tests same as default integration tests by adding additional profile to maven commands:
 188 `integration-tests-with-helm-validator`
 189 * To start SDC with Helm Validator run: `mvn clean install -P start-sdc,integration-tests-with-helm-validator`
 190 * To execute tests that use Helm Validator use: `mvn clean install -P run-integration-tests,integration-tests-with-helm-validator`
 191 ## Accessing SDC UI in Dev Mode (Legacy way)
 192
 193 In order to access the SDC UI from your dev environment you need to do the following:
 194
 195 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.
 196 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.
 197
 198 ## SDC on OOM
 199
 200 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)
 201
 202 ## Frontend Local Env - onboarding
 203
 204 ### Steps:
 205
 206 Install nodejs & gulp
 207 1. download nodejs from here: https://nodejs.org/en/ (take the "current" version with latest features) & install it.
 208 2. install gulp by running the following command: npm install --global gulp-cli
 209
 210 ### Install DOX-UI a:
 211
 212 1. pull for latest changes
 213 2. go to folder dox-sequence-diagram-ui
 214 3. run npm install
 215 4. wait for it...
 216 5. go to folder dox-ui
 217 6. run npm install
 218 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)
 219 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>
 220 9. after everything is successful, run gulp
 221 10. after server is up, your favorite UI will wait for you at: http://localhost:9000/sdc1/proxy-designer1#/onboardVendor
 222
 223 ### Troubleshooting:
 224
 225 | Problem                       |   Why is this happening | Solution                                                                                   |
 226 |-------------------------------|-------------------------|--------------------------------------------------------------------------------------------|
 227 | npm cannot reach destination  | onboarding proxy        | When within onboarding network, you should set onboarding proxy to NPM as the following:   |
 228 |                               |                         | npm config set proxy http://genproxy:8080                                                  |
 229 |                               |                         | npm config set https-proxy http://genproxy:8080                                            |
 230 |                               |                         |                                                                                            |
 231 | git protocol is blocked       | onboarding network      | When within onboarding network, you should set globally that when git                      |
 232 | and cannot connect            | rules for protocols     | protocol is used, it will be replaced with "https"                                         |
 233 |                               |                         | git config --global url."https://".insteadOf git://                                        |
 234 --------------------------------------------------------------------------------------------------------------------------------------------------------
 235
 236 ## SDC Troubleshooting
 237
 238 In order to check the life state of SDC you can run the command `health` from inside the vagrant.
 239 Alternatively you can run the following commands to check the FE and BE status:
 240
 241 FE - `curl http://<ip_address>:8181/sdc1/rest/healthCheck`
 242
 243 BE - `curl http://<ip_address>:8080/sdc2/rest/healthCheck`
 244
 245 Another method to check about problems in SDC is to look at the log files.
 246
 247 The jetty(Applicative) are found in the respective folder according to the wanted section
 248 For example, the BE logs will found under the directory `/BE`.
 249
 250 For more information regarding SDC Troubleshooting please refer to the following guide: [SDC Troubleshooting](https://wiki.onap.org/display/DW/SDC+Troubleshooting)
 251
 252 ## Getting Help
 253
 254 #####  [Mailing list](mailto:onap-sdc@lists.onap.org)
 255
 256 ##### [JIRA](http://jira.onap.org)
 257
 258 ##### [WIKI](https://wiki.onap.org/display/DW/Service+Design+and+Creation+%28SDC%29+Portal)