Developing Portal SDK based UI App and the initial setup

ALERT: Updated info will be maintained on this topic at https://docs.onap.org/en/elalto/submodules/portal.git/docs/tutorials/index.html

The ONAP Portal SDK provides a sample web app to build and deploy to a Tomcat instance. The SDK App can be used standalone (i.e., command line) or within the Eclipse IDE. This page offers a quick-start guide for this webapp development.

Browsing the SDK

Release trees are archived in this Git release repository and available for browsing:

https://gerrit.onap.org/r/#/admin/projects/portal/sdk

Downloading the SDK

Below is the link to SDK Sample App in gerrit repo. You can download the below sample app to bring up a simple demo webapp that brings many out of box features to integrate with ONAP Portal.

SDK Sample App

Prerequisites

• Java version 1.8
• Maven version 3.
  • These instructions do not require any entries in a local Maven configuration file, which is stored below your home directory in file .m2/settings.xml. However, some people have reported problems caused by entries in their configuration files.
• Tomcat version 8
• MariaDB Server version 10.1.11-MariaDB, which includes Galera cluster support.
• Maven will automatically download required jar and pom files from the ONAP nexus repositories.
  
  

Basic Project setup - New install of ONAP SDK using Maven

1. Create a new directory and download the ONAP SDK Sample App project within that new location; e.g C:\dev\ONAP_SDK
2. In the newly created directory, first run maven on the "clean" goal (mvn clean). You should see no warnings, and eventually a build success message. This validates that you have maven working.
3. Build the deployable WAR file using the "package" goal (mvn package). You will see some warnings about missing pom files, which can be ignored.

Eclipse Project setup

This section offers instructions for a clean/new install of the ONAP SDK in the Eclipse development environment.

Additional prerequisites:

• Eclipse for JEE Developers, version Mars. This distribution includes include the Web Tools Platform (WTP) plugins that recognize JSP files, and should also have the Maven (m2e) plugin installed by default. (Avoid using Eclipse for Java Developers.)
• At least 2 GB memory limit in Eclipse to allow the project validation to run to completion. To change the upper memory limit that Eclipse can use, edit the file eclipse.ini and under the -vmargs line look for an entry with -Xmx; the following entry allows 2GB: -Xmx2048m

Steps:

1. Create a new directory and download the ONAP SDK Sample App project within that new location; e.g C:\dev\ONAP_SDK
2. Import the project into your eclipse workspace: File → Import → Existing Maven project, browse to the newly created directory and click OK, it will show the pom.xml file, then click Finish.
3. The first import and build will take some time while the Maven plugin downloads required dependencies and validates the project contents. If Eclipse runs out of memory, see above note in "additional prerequisites".
4. Check the sanity of the project's Eclipse source classpath; deployment assembly folders are all properly set. The project classpath must reflect the Maven dependencies; depending on your location setup, your classpath may also include Server Runtime libraries (Tomcat for example).
5. Run maven on the "clean" and then the "install" targets: First, right click on the project, pick Run As, pick Maven Clean. Second, again right click on the project, pick Run As, pick Maven Build..., enter "install" in the Goals field, then click the Run button.

Note 1: If Maven dependencies are not appearing in the classpath/libraries, there could be a need to update the maven project (Right click on the project → Maven Update)

Database setup

The application requires MariaDB (MySQL-compatible) database with a predefined set of tables; see the Prerequisites section above for the software versions needed. Note that many ONAP Portal SDK team members reuse existing databases for development and test, but this option is not available to developers outside the ONAP Portal team.

1. Configure the server to ignore case on table names by setting the MySQL/MariaDB system variable called lower_case_table_names to value 1. Example line in the MySQL configuration file my.cnf within the [mysqld] section:

   lower_case_table_names = 1

2. Create a database user, for example 'ecomp_sdk_user':

   1. mysql> create user 'ecomp_sdk_user'@'localhost' identified by 'ecomp_sdk_pass';
3. Create a database, for example 'ecomp_sdk':
   1. mysql> create database 'ecomp_sdk';

4. Grant access to the newly created database.  For example, if the database is created with the name of ‘ecomp_sdk’, login as root to your MySQL instance and grant full privileges on the database you created.  Depending on your distribution, the command will look something like this:

   1. mysql> grant all on ecomp_sdk.* to ‘ecomp_sdk_user’@'localhost';

5. Populate the database by first running the DDL and then DML scripts provided in folder db-scripts. There are 6 scripts included that can be used for SDK; only one DDL and one DML file is necessary at one time. Please see the table below to see which scripts your instance needs.  You will need to revise the scripts to use the database name you chose above; all scripts use the database name "ecomp_sdk".  For example:

   1. mysql> source EcompSdkDDLMySql.sql;
   2. mysql> source EcompSdkDMLMySql.sql

EcompSdkDDLMySql.sql

EcompSdkDDL_(verNNNN)_Add.sql

EcompSdkDMLMySql.sql

EcompSdkDML_(verNNNN)_Add.sql

EcompSdkTestDML.sql

cleanup_EcompSdk.sql

Eclipse Project/Tomcat configuration/startup

1. Edit the WEB-INF/conf/system.properties file with the database information. Make sure all the entries point to your local environment and a working accessible database.
   

   db.connectionURL = jdbc:mysql://<mysql-host>:<port>/<db-name>

   db.userName = mysql-user

   db.password = password

2. Edit the the log4j.properties file (WEB-INF/conf/log4j.properties file) and update the property "log4j.appender.logfile.File" to reflect the local environment; 
3. Add a Tomcat Server instance
4. Click on Add / Remove on Tomcat instance you have added and add the project to it.
5. Right click on the tomcat and start.
6. As with most Eclipse based web applications, it is always a good idea to clean your project from all places. ( Project  →  Clean, Tomcat  →  Clean, Clean Tomcat working directory etc.)
7. Once your application is up and running, if you have made suitable entries in the FN_USER table as discussed above in "Database Setup", you can open a browser with the URL: http://<host>:<port>/<context>/login_external.htm url and use the credentials stored in that table to login. This is helpful for development, but must NEVER be used in production.

Project Customization

The SDK-App distribution should be customized with the appropriate application name in these locations:

1. File pom.xml: groupId, artifactId
2. File src/main/resources/logback.xml: componentName
3. File src/main/webapp/WEB-INF/web.xml: display-name
4. File src/main/webapp/WEB-INF/conf/system.properties: app_display_name

OnBoarding SDK App to Portal

Follow below steps:

1. Pre-Onboarding - provide required fields as shown in the below screen on Portal Onboarding UI. 
   
2. Post-Onboarding - Edit the portal.properties based on your deployed environment.
   1. ecomp_redirect_url
   2. ecomp_rest_url
   3. UEB values