ui/README.rst

   1
   2 Akraino Blueprint Validation UI
   3 ========
   4
   5 This project contains the source code of the Akraino Blueprint Validation UI.
   6
   7 This UI consists of the front-end and back-end parts.
   8 The front-end part is based on HTML, CSS, and AngularJS technologies.
   9 The back-end part is based on Spring MVC and Apache Tomcat technologies.
  10
  11 Based on these instructions, a user can provide the prerequisites, compile the source code and deploy the UI.
  12
  13 Download the project
  14 --------------------
  15
  16 .. code-block:: console
  17
  18     git clone "https://gerrit.akraino.org/r/validation"
  19
  20 Prerequisites
  21 ---------------
  22
  23 - Database
  24
  25 A PostgreSQL database instance is needed with the appropriate relations in order for the back-end system to store and retrieve data.
  26 Configure the postgreSQL root password in the variable POSTGRES_PASSWORD and execute the following commands in order to build and deploy this database container:
  27
  28 .. code-block:: console
  29
  30     cd validation/docker/postgresql
  31     make build
  32     ./deploy.sh POSTGRES_PASSWORD=password
  33
  34 Below, some data that is initialized in the aforementioned database is illustrated (note that this data is used mainly for testing purposes):
  35
  36 .. code-block:: console
  37
  38     Timeslots:
  39     id:1 , start date and time: now() (i.e. the time of the postgreSQL container deployment), duration: 10 (sec), lab: 0 (i.e. AT&T)
  40     id:2 , start date and time: now() (i.e. the time of the postgreSQL container deployment), duration: 1000 (sec), lab: 0 (i.e. AT&T)
  41
  42     Blueprints:
  43     id: 1 , name : 'dummy'
  44     id: 2 , name : 'Unicycle'
  45
  46     Blueprint Instances:
  47     id: 1, blueprint_id: 1 (i.e. dummy), version: "0.0.2-SNAPSHOT", layer: 0 (i.e. Hardware), layer_description: "Dell Hardware", timeslot id: 1
  48     id: 2, blueprint_id: 2 (i.e. Unicycle), version: "0.0.1-SNAPSHOT", layer: 0 (i.e. Hardware), layer_description: "Dell Hardware", timeslot id: 2
  49
  50 For more information about this data, please refer to the file:
  51
  52     validation/docker/postgresql/akraino-blueprint_validation_db.sql
  53
  54 Based on this data, the UI enables the user to select an appropriate blueprint instance for validation.
  55
  56 Currently, this data cannot be retrieved dynamically by the UI (see limitations subsection).
  57
  58 For this reason, in cases of new blueprint data, a user should define new entries in this database.
  59
  60 For example, if a user wants to define a new timeslot with the following data:
  61
  62     start date and time:now, duration: 123 in secs, lab: Community
  63
  64 the following file should be created:
  65
  66 name: dbscript
  67 content:
  68     insert into akraino.timeslot values(5, now(), 123, 2);
  69
  70 Then, the following command should be executed:
  71
  72 .. code-block:: console
  73
  74     psql -h <IP of the postgreSQL container> -p 6432 -U admin -f ./dbscript
  75
  76 Furthermore, if a user wants to define a new blueprint, namely "newBlueprint" and a new instance of this blueprint with the following data:
  77
  78     version: "0.0.1-SNAPSHOT", layer: 2 (i.e. K8s), layer_description: "K8s with High Availability Ingress controller", timeslot id: 5 (i.e. the new timeslot)
  79
  80 the following file should be created:
  81
  82 name: dbscript
  83 content:
  84     insert into akraino.blueprint (blueprint_id, blueprint_name) values(4, 'newBlueprint');
  85     insert into akraino.blueprint_instance (blueprint_instance_id, blueprint_id, version, layer, layer_description, timeslot_id) values(6, 4, '0.0.1-SNAPSHOT', 2, 'K8s with High Availability Ingress controller', 5);
  86
  87 Then, the following command should be executed:
  88
  89 .. code-block:: console
  90
  91     psql -h <IP of the postgreSQL container> -p 6432 -U admin -f ./dbscript
  92
  93 The UI will automatically retrieve this new data and display it to the user.
  94
  95 - Jenkins Configuration
  96
  97 The Blueprint validation UI will trigger job executions in a Jenkins instance.
  98
  99 This instance must have the following option enabled: "Manage Jenkins -> Configure Global Security -> Prevent Cross Site Request Forgery exploits".
 100
 101 Also, currently corresponding Jenkins job should accept the following as input parameters: "SUBMISSION_ID", "BLUEPRINT", "LAYER" and "UI_IP".
 102 The "SUBMISSION_ID" and "UI_IP" parameters (i.e. IP address of the UI host machine-this is needed by the Jenkins instance in order to send back Job completion notification) are created and provided by the backend part of the UI.
 103 The "BLUEPRINT" and "LAYER" parameters are configured by the UI user.
 104
 105 Moreover, as the Jenkins notification plugin (https://wiki.jenkins.io/display/JENKINS/Notification+Plugin) seems to ignore proxy settings, the corresponding Jenkins job must be configured to execute the following command at the end (Post-build Actions)
 106
 107 .. code-block:: console
 108
 109     curl -v -H "Content-Type: application/json" -X POST --insecure --silent http://$UI_IP:8080/AECBlueprintValidationUI/api/jenkinsJobNotification/ --data '{"submissionId": "'"$SUBMISSION_ID"'" , "name":"'"$JOB_NAME"'", "buildNumber":"'"$BUILD_NUMBER"'"}'
 110
 111 Finally, the Jenkins instance must be accessible from the UI host without using system proxy.
 112
 113 - Nexus server
 114
 115 All the blueprint validation results are stored in Nexus server.
 116
 117 These results must be available in the following url:
 118
 119     https://nexus.akraino.org/content/sites/logs/"lab"-blu-val/job/validation/"Jenkins job number"/results/"name_of_the_test_suite".
 120
 121 where "lab" is the name of the lab (for example 'att'), "Jenkins job number" is the number of the Jenkins job that produced this result, and "name_of_the_test_suite" is the name of the test suite.
 122 If multiple test suites must run, multiple directories should be created.
 123
 124 Moreover, the results should be stored in the 'output.xml' file using the following format:
 125
 126 TBD
 127
 128 Finally, the Nexus server must be accessible from the UI (with or without using system proxy).
 129
 130
 131 Compiling
 132 ---------
 133
 134 .. code-block:: console
 135
 136     cd validation/ui
 137     mvn clean install
 138
 139 Deploying
 140 ---------
 141
 142 In the context of deploying, the following data is needed:
 143
 144 - The postgres root user password
 145 - The Jenkins url
 146 - The Jenkins username and password
 147 - The name of Jenkins Job
 148 - The Url of the Nexus results
 149 - The host system's proxy ip and port
 150
 151 These variables must be configured as content of the deploy script input parameters. Execute the following commands in order to build and deploy the UI container:
 152
 153 .. code-block:: console
 154
 155     cd validation/docker/ui
 156     make build
 157     ./deploy.sh postgres_db_user_pwd=password jenkins_url=http://192.168.2.2:8080 jenkins_user_name=name jenkins_user_pwd=jenkins_pwd jenkins_job_name=job1 nexus_results_url=https://nexus.akraino.org/content/sites/logs proxy_ip=172.28.40.9 proxy_port=3128
 158
 159 If no proxy exists, just do not define proxy ip and port variables.
 160
 161 The UI should be available in the following url:
 162
 163     http://localhost:8080/AECBlueprintValidationUI
 164
 165 Limitations
 166 -----------
 167
 168 - The UI has been tested using Chrome and Firefox browsers.
 169 - The UI is not connected to any LDAP server. Currently, any user can login.
 170 - The UI and postgreSQL containers must be deployed on the same server.
 171 - The back-end part of the UI does not take into account the configured timeslot. It immediately triggers the corresponding Jenkins Job.
 172 - Results data manipulation (filtering, graphical representation, indexing in time order, etc) is not supported.
 173 - Only the following labs are supported: AT&T, Ericsson, Community and Arm.
 174 - Only the following tabs are functional: 'Committed Submissions', 'Blueprint Validation Results -> Get by submission id'.
 175 - The UI configures only the "BLUEPRINT" and "LAYER" input parameters of the Jenkins job.
 176 - The available blueprints and timeslots must be manually configured in the PostgreSQL database.
 177 - The Jenkins instance must be accessible from the UI host without using system proxy.