docs/tutorials/portal-sdk/setting-up.rst

   1 Setting up
   2 ==========
   3
   4 Dependencies
   5 ------------
   6
   7 In order to build Portal SDK applications on your machine, you'll need to install the following:
   8
   9 1. OpenJDK 8
  10 2. Maven
  11 3. MariaDB (v10.1)
  12 4. Apache Tomcat (v8.5)
  13
  14 Cloning the Portal SDK repository
  15 ---------------------------------
  16
  17 Clone the Portal SDK repository with git:
  18
  19 ::
  20
  21     git clone http://gerrit.onap.org/r/portal/sdk
  22
  23 Building the base
  24 -----------------
  25
  26 Now, we'll build the base with maven:
  27
  28 ::
  29
  30     cd sdk/ecomp-sdk
  31     mvn install
  32
  33 Setting up the MariaDB database
  34 -------------------------------
  35
  36 Adding support for lowercase table names
  37 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  38
  39 To add support for lowercase table names, make sure the following line in your :code:`/etc/mysql/my.cnf` file is present under the :code:`[mysqld]` section:
  40
  41 ::
  42
  43     lower_case_table_names = 1
  44
  45 If you made changes, you'll need to restart your MariaDB instance. Hint:
  46
  47 ::
  48
  49     sudo systemctl restart mariadb.service
  50
  51
  52 Database setup
  53 ^^^^^^^^^^^^^^
  54
  55 Now, we set up the database and user privileges. Log into your MariaDB instance as the 'root' user and do the following:
  56
  57 ::
  58
  59     drop database if exists ecomp_sdk;
  60     drop user if exists 'ecomp_sdk_user'@'localhost';
  61
  62     create database ecomp_sdk;
  63     create user 'ecomp_sdk_user'@'localhost' identified by 'password';
  64     grant all privileges on ecomp_sdk.* to 'ecomp_sdk_user'@'localhost';
  65
  66 Adding tables
  67 ^^^^^^^^^^^^^
  68
  69 Next, we need to run several SQL statements in the repository:
  70
  71 ::
  72
  73     mysql -proot -uroot < sdk/ecomp-sdk/epsdk-app-common/db-scripts/EcompSdkDDLMySql_2_4_Common.sql
  74     mysql -proot -uroot < sdk/ecomp-sdk/epsdk-app-common/db-scripts/EcompSdkDMLMySql_2_4_Common.sql
  75     mysql -proot -uroot < sdk/ecomp-sdk/epsdk-app-os/db-scripts/EcompSdkDDLMySql_2_4_OS.sql
  76     mysql -proot -uroot < sdk/ecomp-sdk/epsdk-app-os/db-scripts/EcompSdkDMLMySql_2_4_OS.sql
  77
  78
  79 Using 'root' for both your MySQL username and password is just about the worst security policy imaginable. For anything other than temporary setups (very temporary), please choose reasonable user names and hard-to-guess passwords.
  80
  81 Your project directory
  82 -------------------------------
  83
  84 Because you'll want your project to use the latest portal SDK code (retrieved via :code:`git pull`), you work directly in :code:`sdk/ecomp_sdk/epsdk-app-os`.
  85
  86 Connecting your app to the backend database
  87 -------------------------------------------
  88
  89 We need to tell our app how to access the database tables we created above. Open :code:`sdk/ecomp-sdk/epsdk-app-os/src/main/webapp/WEB-INF/conf/system.properties` and change the following two lines to reflect the database user you set up above as well as your particular installation of MariaDB:
  90
  91 ::
  92
  93     db.connectionURL = jdbc:mysql://localhost:3306/ecomp_sdk
  94     db.userName = ecomp_sdk_user
  95     db.password = password
  96
  97 Building your app
  98 -----------------
  99
 100 When you want to build your app:
 101
 102 ::
 103
 104     # First cd to the project directory
 105     cd sdk/ecomp_sdk/epsdk-app-os
 106     mvn clean package
 107
 108 .. note:: You don't always have to :code:`clean`. Only use it when you want to clear out intermediate objects and build your entire project from scratch.
 109
 110 .. _installingyourapp:
 111
 112 Installing your app
 113 -------------------
 114
 115 To install your app, run the following commands, or better, create a script:
 116
 117 ::
 118
 119     # Shutdown tomcat
 120     <tomcat install>/bin/shutdown.sh
 121     rm -rf <tomcat install>/webapps/epsdk-app-os*
 122     cp target/epsdk-app-os.war <tomcat install>/webapps/.
 123     # Start tomcat
 124     <tomcat install>/bin/startup.sh
 125
 126 Viewing your app
 127 ----------------
 128
 129 Assuming you have installed Tomcat locally, for example in a vagrant VM with port forwarding, you can `access the app`_ in your normal browser:
 130
 131 ::
 132
 133     http://localhost:8080/epsdk-app-os/login.htm
 134
 135 To log in, use user/password 'demo/demo'.
 136
 137 .. _access the app: http://localhost:8080/epsdk-app-os/login.htm