[docker] Add sonobuoy multiarch image build
[validation.git] / 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.