LSPS documentation logo
LSPS Documentation
LSPS Application on a Local Server and Database

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 Designer. 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 8.0
  • JDBC driver for MySQL
  • WildFly 16
  • lsps-tools (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' IDENTIFIED BY 'lsps';
    CREATE DATABASE lsps DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_unicode_ci;
    ALTER USER 'lsps'@'localhost' IDENTIFIED BY 'lsps'
    GRANT XA_RECOVER_ADMIN ON *.* TO 'lsps'@'%';
    SET GLOBAL log_bin_trust_function_creators = 1;
    quit
  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 8.0\my.ini in the mysql installation directory.
    $ cat /etc/mysql/mysql.conf.d/mysqld.cnf |grep -E "(max_allowed|default_time_zone)"
    max_allowed_packet= 512M
    default_time_zone=+01:00
  5. Initialize the database with the lsps-db-migration-lsps tool from lsps-tools/cli-tools.
    java -jar lsps-db-migration-lsps-<VERSION>-full.jar --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. 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
  2. Download WildFly and extract it.
    ~$ #we use home directory; on linux consider /opt
    ~$ unzip Downloads/wildfly-16.0.0.Final.zip
    ~$ mv wildfly-16.0.0.Final/ wildfly
  3. Set up data source for the MySQL database:
    1. Download and add the MySQL JDBC driver:
      ~$ mkdir -p wildfly/modules/com/mysql/main
      ~$ cp Downloads/mysql-connector-java-<VERSION>.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-tools/lsps-security-jboss-<VERSION>.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 (The file configured as instructed below is available here:
    • Add LSPS_DS transaction datasource that connects to your lsps database with the driver:
      <datasources>
      <!-- ADDED: -->
      <xa-datasource jndi-name="java:/jdbc/LSPS_DS" pool-name="LSPS_DS" enabled="true" use-java-context="false">
           <driver>mysqlxa</driver>
           <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/lsps?useUnicode=true&characterEncoding=utf-8</xa-datasource-property>
           <security>
              <user-name>lsps</user-name>
              <password>lsps</password>
           </security>
           <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>
            </xa-datasource>
            <drivers>
               <driver name="mysqlxa" module="com.mysql">
               <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class>
            </driver>
          </drivers>
      </xa-datasource>
      
    • Set the datasource of the default bindings of urn:jboss:domain:ee:4.0 to LSPS_DS
      <default-bindings context-service="java:jboss/ee/concurrency/context/default" datasource="java:/jdbc/LSPS_DS" ...
    • Set up the security lspsRealm.
      <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:6.0">:
        <subsystem xmlns="urn:jboss:domain:messaging-activemq:6.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=512m -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=512m -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-tools.
    cp ~/Downloads/lsps-tools/lsps-application-3.2.ear ~/wildfly/standalone/deployments/
  8. Start the server:
    ~/wildfly/bin$ ./standalone.sh

Connecting to Local WildFly from Designer

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

  1. In the Modeling perspective of Designer, 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.