LSPS documentation logo
LSPS Documentation
Deploy LSPS Application on a Local Server

In this tutorial, you set up a MySQL database with LSPS tables, set up the WildFly server, deploy the LSPS Application to the WildFly server, and connect to the server from PDS. We assume you are on Linux.

Important: This environment is not intended for production. For simplicity, resources are set up in the home directory and no security aspects are taken into consideration. More detailed deploy instructions are available in the Deployment Guide.

You will need the following:

  • MySQL (version 5.7.23)
  • JDBC driver for MySQL
  • WildFly (WildFly 11)
  • lsps-runtime (requires licensed)

Setting up Local MySQL Database

  1. Install MySQL: make sure to perform this as the administrator on Windows.
  2. Log in as root user:
    mysql -u root -p
  3. Create LSPS database and user:
    CREATE USER 'lsps'@localhost;
    CREATE DATABASE lsps DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
    GRANT ALL PRIVILEGES ON lsps.* TO lsps@'' IDENTIFIED BY 'lsps';
    FLUSH PRIVILEGES;
  4. In the [mysqld] section of the mysqld.conf file, add max_allowed_packet=512M. On Windows, define this in your C:\ProgramData\MySQL\MySQL Server 5.7\my.ini in the mysql installation directory.
    $ grep max_allowed /etc/mysql/mysql.conf.d/mysqld.cnf
    max_allowed_packet = 512M
  5. Initialize the database with the migrate.sh script from lsps-runtime/db-migration.
    ./migrate.sh databaseUrl:jdbc:mysql://localhost/lsps user:lsps password:lsps
    Initialized Database
    mysql> USE lsps;
    Database changed
    mysql> SHOW TABLES;
    +--------------------------------+
    | Tables_in_lsps                 |
    +--------------------------------+
    | LSPS_ACTIVE_USERS_TRACK        |
    | LSPS_BINARY_DATA               |
    | LSPS_BINARY_DATA_METADATAS     |
    | LSPS_DASHBOARD_TABS            |
    ...
    

Setting up Local WildFly

  1. Download WildFly and extract to your home.
    ~$ unzip Downloads/wildfly-11.0.0.Final.zip
    ~$ mv wildfly-11.0.0.Final/ wildfly
    
  2. Set up JAVA_HOME and add JAVA_HOME/bin to PATH.
    export JAVA_HOME=/usr/lib/jvm/java-8-oracle
    export PATH=$JAVA_HOME/bin:$PATH
    
  3. Set up data source for the MySQL database:
    1. Add JDBC driver:
      ~$ cd Downloads
      ~/Downloads/$ unzip mysql-connector-java-5.1.46.zip
      ~$ cd ..; mkdir -p wildfly/modules/com/mysql/main
      ~$ cp Downloads/mysql-connector-java-5.1.46/mysql-connector-java-5.1.46-bin.jar wildfly/modules/com/mysql/main/mysql-connector-java.jar
      
    2. Configure the driver in wildfly/modules/com/mysql/main/module.xml.
      ~$ cat wildfly/modules/com/mysql/main/module.xml
      <module xmlns="urn:jboss:module:1.0" name="com.mysql">
        <resources>
           <resource-root path="mysql-connector-java.jar"/>
        </resources>
        <dependencies>
          <module name="javax.api"/>
          <module name="javax.transaction.api"/>
        </dependencies>
      </module>
      
    3. Add the authentication jar:
      ~$ mkdir -p wildfly/modules/com/whitestein/lsps/security/main
      ~$ cp ~/Downloads/lsps-runtime/lsps-security-jboss-3.2.jar wildfly/modules/com/whitestein/lsps/security/main/lsps-security-jboss.jar
      
    4. Configure the authentication module:
      cat wildfly/modules/com/whitestein/lsps/security/main/module.xml
      <module xmlns="urn:jboss:module:1.0" name="com.whitestein.lsps.security">
        <resources>
          <resource-root path="lsps-security-jboss.jar"/>
        </resources>
        <dependencies>
          <module name="javax.api"/>
          <module name="javax.transaction.api"/>
          <module name="org.picketbox" />
        </dependencies>
      </module>
      
  4. Create the admin user for WildFly:
    ~$ ./wildfly/bin/add-user.sh -u admin -p admin
    
  5. Set up profile configuration in wildfly/standalone/configuration/standalone-full.xml:
    • Add LSPS_DS transaction datasource that connects to your lsps database:
      <datasources>
      <!-- ADDED: -->
      <xa-datasource jndi-name="java:/jdbc/LSPS_DS" pool-name="LSPS_DS" enabled="true" use-java-context="false">
          <xa-datasource-property name="URL">
            jdbc:mysql://localhost:3306/lsps
          </xa-datasource-property>
          <driver>mysqlxa</driver>
          <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
          <xa-pool>
              <min-pool-size>10</min-pool-size>
              <max-pool-size>20</max-pool-size>
              <prefill>true</prefill>
          </xa-pool>
          <security>
              <user-name>lsps</user-name>
              <password>lsps</password>
          </security>
      </xa-datasource>
      
    • Add driver connection:
      <drivers>
        <driver name="h2" module="com.h2database.h2">
            <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
        </driver>
        <!-- ADDED: --_>
        <driver name="mysqlxa" module="com.mysql">
           <xa-datasource-class>com.mysql.cj.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
        </driver>
      
    • Add the security realm to the security subsystem:
      <subsystem xmlns="urn:jboss:domain:security:2.0">
          <security-domains>
              <security-domain name="lspsRealm" cache-type="default">
                   <authentication>
                       <login-module code="com.whitestein.lsps.security.jboss.LSPSRealm" flag="required" module="com.whitestein.lsps.security">
                           <module-option name="dsJndiName" value="/jdbc/LSPS_DS"/>
                       </login-module>
                   </authentication>
               </security-domain>
      
    • Prolong the locking isolation on the web cache container:
      <cache-container name="web" default-cache="passivation" module="org.wildfly.clustering.web.infinispan">
             <local-cache name="passivation">
             <locking isolation="REPEATABLE_READ" acquire-timeout="600000"/>
      
    • Add mail session LSPS_MAIL:
      <mail-session name="lspsmail" jndi-name="java:jboss/mail/LSPS_MAIL">
              <smtp-server outbound-socket-binding-ref="mail-smtp"/>
          </mail-session>
      
    • Configure JMS:
      • Enable persistence on jms <subsystem xmlns="urn:jboss:domain:messaging-activemq:2.0">:
        <server name="default" persistence-enabled="true">
        
      • Add queue and topic:
        <jms-queue name="LSPS_QUEUE" entries="java:jboss/jms/LSPS_QUEUE"/>
            <jms-topic name="LSPS_TOPIC" entries="java:jboss/jms/LSPS_TOPIC"/>
        
  6. Adjust JAVA_OPTS:
    • On Linux, in wildfly/bin/standalone.conf:
      ~$ cat wildfly/bin/standalone.conf
      if [ "x$JBOSS_MODULES_SYSTEM_PKGS" = "x" ]; then
         JBOSS_MODULES_SYSTEM_PKGS="org.jboss.byteman"
      fi
      if [ "x$JAVA_OPTS" = "x" ]; then   
          JAVA_OPTS="-Xms64m -Xmx800M -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m -Djava.net.preferIPv4Stack=true"
          JAVA_OPTS="$JAVA_OPTS -Djboss.server.default.config=standalone-full.xml"
          JAVA_OPTS="$JAVA_OPTS -Dorg.eclipse.emf.ecore.EPackage.Registry.INSTANCE=org.eclipse.emf.ecore.impl.EPackageRegistryImpl"
          JAVA_OPTS="$JAVA_OPTS -Dorg.apache.el.parser.COERCE_TO_ZERO=false"
          JAVA_OPTS="$JAVA_OPTS -Dcom.whitestein.lsps.vaadin.ui.debug=true"
      else
         echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"
      fi
      
    • On Windows, add at the end of wildfly/bin/standalone.conf.bat:
      set "JAVA_OPTS=-Xms64m -Xmx800M -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m -Djava.net.preferIPv4Stack=true"
      rem # ADD THE FOLLOWING:
      set "JAVA_OPTS=%JAVA_OPTS% -Djboss.server.default.config=standalone-full.xml"
      set "JAVA_OPTS=%JAVA_OPTS% -Dorg.eclipse.emf.ecore.EPackage.Registry.INSTANCE=org.eclipse.emf.ecore.impl.EPackageRegistryImpl"
      set "JAVA_OPTS=%JAVA_OPTS% -Dorg.apache.el.parser.COERCE_TO_ZERO=false"
      
  7. Deploy the ear with LSPS Application: here we deploy the default ear from lsps-runtime.
    cp ~/Downloads/lsps-runtime/lsps-application-3.2.ear ~/wildfly/standalone/deployments/
    
  8. Start the server:
    ~/wildfly/bin$ ./standalone.sh
    

Connecting to Local WildFly from PDS

To connect your PDS to the server, do the following:

  1. In the Modeling perspective of PDS, go to Server Connection > Server Connection Settings
  2. In the dialog, click Add.
  3. Enter the connection properties and test the connection.
    localsetup_server_connection.png
  4. Make sure the connection is selected in the Server Connections.
  5. In the status bar, check that the connection is active.
    localsetup_server_connected.png
    Now you can use the management perspective to "communicate" with the LSPS Application on your server.