Page Comparison

This page documents the steps taken to deploy in Wildfly 910.1.0.2-Final. This is not mostly complete and , so far, bedework is not bedework seems to be running on that platform.

This is a set of notes which should turn into instructions for configuration. This is NOT a set of instructions for someone who wishes to run a wildfly quickstart.

These instructions will provide a reference for upgrading to later versions of wildfly.

Startup

Download and unzip wildfly within the quickstart. Execute startwildfly and then create a user.

...

Startup shell script can set runtime properties to configure the system - as it does with jboss 5.

Datasources

People are currently running bedework on postgresql, mysql, oracle and possibly sqlserver. How do we provide example configurations for these. Provide entire config files or ask them to modify their own?

Using the console seems to be reasonably easy if repetitive. The following datasources are required:

1. java:CardDS - for CardDAV address books (use the hsql service if you don't use them)
2. java:CalendarDS - for the main calendar engine
3. java:EventregDS - for the event registration system
4. java:NotifyDS - for the notification engine
5. java:selfregDS - for the self-registration system
6. java:SynchDS - for the synchronization engine

Add a datasource for selfreg - even if it's not being used. We may need that to handle roles - see below

...

Ajp

Many configurations run with Apache as a front end using ajp to communicate with bedework. Wildfly does not have ajp enabled by default. To do so make the following changes.

Add an ajp listener to the undertow config in standalone.xml

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
    <buffer-cache name="default"/>
    <server name="default-server">
        <ajp-listener name="ajp" socket-binding="ajp" max-post-size="1048576000"/>
        <connection-url>jdbc:h2:tcp://localhost/CalDb</connection-url>
      <driver-class>org.postgresql.Driver</driver-class>
    <driver>h2</driver>
    <security>
 <http-listener name="default" socket-binding="http" redirect-socket="https" ...

Add a socket binding for ajp on port 8009 also in standalone.xml (it may already be present)

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    <user-name>sa</user-name>
      <password>sa</password><socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
    </security>
  </datasource>
<datasource jndi-<socket-binding name="java:/EventregDSmanagement-https" pool-nameinterface="EventregDSmanagement" enabledport="true" use-java-context="true">
  <connection-url>jdbc:h2:tcp://localhost/EventRegDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url>
  <driver>h2</driver>
  <security>
    <user-name>sa</user-name>
    <password>sa</password>
  </security>
</datasource>
<datasource jndi-name="java:/NotifyDS" pool-name="NotifyDS" enabled="true" use-java-context="true">
  <connection-url>jdbc:h2:tcp://localhost/NotifyDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url>
  <driver>h2</driver>
  <security>
    <user-name>sa</user-name>
    <password>sa</password>
  </security>
</datasource>
  <datasource jndi-name="java:/selfregDS" pool-name="selfregDS" enabled="true" use-java-context="true">
    <connection-url>jdbc:h2:tcp://localhost/SelfregDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url>
    <driver>h2</driver>
    <security>
      <user-name>sa</user-name>
      <password>sa</password>
    </security>
  </datasource>
<datasource jndi-name="java:/SynchDS" pool-name="SynchDS" enabled="true" use-java-context="true">
  <connection-url>jdbc:h2:tcp://localhost/SynchDb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url>
  <driver>h2</driver>
  <security>
    <user-name>sa</user-name>
    <password>sa</password>
  </security>
</datasource>

Then build and deploy the selfreg module

./bw -dc bedework/config/wildfly.deploy.properties -wildfly -selfreg

Hawtio

Download and deploy the hawtio war. This provides us with a jmx console. Rename downloaded file as hawtio.zip.

Remove the log4j config:

zip -d hawtio.war WEB-INF/classes/log4j.properties

Add system properties to enable authentication

<extensions>
    ...
</extensions>

<system-properties>
    <property name="hawtio.authenticationEnabled" value="true" />
    <property name="hawtio.realm" value="jboss-web-policy" />
    <property name="hawtio.role" value="admin" />
</system-properties>

Then add an account:

./bin/add-user.sh 

What type of user do you wish to add?
 a) Management User (mgmt-users.properties)
 b) Application User (application-users.properties)
(a): b

Enter the details of the new user to add.
Using realm 'ApplicationRealm' as discovered from the existing property files.
Username : hawtio-admin
Password recommendations are listed below. To modify these restrictions edit the add-user.properties configuration file.
 - The password should not be one of the following restricted values {root, admin, administrator}
 - The password should contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s)
 - The password should be different from the username
Password :
Re-enter Password :
What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[  ]: admin
About to add user 'hawtio-admin' for realm 'ApplicationRealm'
Is this correct yes/no? yes
Added user 'hawtio-admin' to file '/Users/xxx/dev/eap/wildfly-8.1.0.Final/standalone/configuration/application-users.properties'
Added user 'hawtio-admin' to file '/Users/xxx/dev/eap/wildfly-8.1.0.Final/domain/configuration/application-users.properties'
Added user 'hawtio-admin' with groups admin to file '/Users/xxx/dev/eap/wildfly-8.1.0.Final/standalone/configuration/application-roles.properties'
Added user 'hawtio-admin' with groups admin to file '/Users/xxx/dev/eap/wildfly-8.1.0.Final/domain/configuration/application-roles.properties'
Is this new user going to be used for one AS process to connect to another AS process?
e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
yes/no? no

JDBC Drivers.

It's quite possible a site will need to deploy their own to match the version of their database. We can probably add some popular ones to the quickstart but there may be version issues. Current driver jars are probably all compliant - we'll find out I guess.

The documentation DataSource+configuration provides information and links on deploying the drivers and editing the config.

Deploying the driver - an example:

Start wildfly
cd into the bin directory
./jboss-cli.sh 
You are disconnected at the moment. Type 'connect' to connect to the server or 'help' for the list of supported commands.
[disconnected /] connect
[standalone@localhost:9990 /] deploy ~/bedework/files/postgresql-9.4-1204.jdbc42.jar --name=postgresql
[standalone@localhost:9990 /]

When loaded wildfly claims the postgresql-9.3 driver to be non-JDBC-compliant. It does, however, contain the file described in the documentation and it does recognize the driver class.

The jboss documentation has this to say:

Note on MySQL driver and JDBC Type 4 compliance: while the MySQL driver (at least up to 5.1.18) is designed to be a Type 4 driver, its jdbcCompliant() method always return false. The reason is that the driver does not pass SQL 92 full compliance tests, says MySQL. Thus, you will need to install the MySQL JDBC driver as a module (see below).

Presumably the same is true of the postgresql driver.

It appears that if the exampleds is removed from the configuration deployment of the postgresql driver and datasources fails.

(Wildfly 8 note) Also the above method seems unreliable in that intermittently wildfly refuses to start because of a damaged deployment. Other deployment approaches might be more reliable.

Changes to sysevents

...

${jboss.management.https.port:9993}"/>
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
 ...

Hawtio

Download and deploy the hawtio war. This provides us with a jmx console. Rename downloaded file as hawtio.zip.

Remove the log4j config:

zip -d hawtio.war WEB-INF/classes/log4j.properties

Add system properties to enable authentication

<extensions>
    ...
</extensions>

<system-properties>
    <property name="hawtio.authenticationEnabled" value="true" />
    <property name="hawtio.realm" value="jboss-web-policy" />
    <property name="hawtio.role" value="admin" />
</system-properties>

Then add an account:

./bin/add-user.sh 

What type of user do you wish to add?
 a) Management User (mgmt-users.properties)
 b) Application User (application-users.properties)
(a): b

Enter the details of the new user to add.
Using realm 'ApplicationRealm' as discovered from the existing property files.
Username : hawtio-admin
Password recommendations are listed below. To modify these restrictions edit the add-user.properties configuration file.
 - The password should not be one of the following restricted values {root, admin, administrator}
 - The password should contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s)
 - The password should be different from the username
Password :
Re-enter Password :
What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[  ]: admin
About to add user 'hawtio-admin' for realm 'ApplicationRealm'
Is this correct yes/no? yes
Added user 'hawtio-admin' to file '/Users/xxx/dev/eap/wildfly-8.1.0.Final/standalone/configuration/application-users.properties'
Added user 'hawtio-admin' to file '/Users/xxx/dev/eap/wildfly-8.1.0.Final/domain/configuration/application-users.properties'
Added user 'hawtio-admin' with groups admin to file '/Users/xxx/dev/eap/wildfly-8.1.0.Final/standalone/configuration/application-roles.properties'
Added user 'hawtio-admin' with groups admin to file '/Users/xxx/dev/eap/wildfly-8.1.0.Final/domain/configuration/application-roles.properties'
Is this new user going to be used for one AS process to connect to another AS process?
e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
yes/no? no

JDBC Drivers.

It's quite possible a site will need to deploy their own to match the version of their database. We can probably add some popular ones to the quickstart but there may be version issues. Current driver jars are probably all compliant - we'll find out I guess.

The documentation DataSource+configuration provides information and links on deploying the drivers and editing the config.

A script is provided in bedework/config/datasources under each of the database names, for example bedework/config/datasources/postgresql/wildfly-add-driver.txt

Take a copy of this script and run the jboss-cli to deploy your jar. You may need to delete the module if you wish to upgrade.

Deploying the driver - an example:

Start wildfly
cd into the bin directory
./jboss-cli.sh --file=path-to-your-script

When loaded wildfly claims the postgresql-9.3 driver to be non-JDBC-compliant. It does, however, contain the file described in the documentation and it does recognize the driver class.

The jboss documentation has this to say:

Note on MySQL driver and JDBC Type 4 compliance: while the MySQL driver (at least up to 5.1.18) is designed to be a Type 4 driver, its jdbcCompliant() method always return false. The reason is that the driver does not pass SQL 92 full compliance tests, says MySQL. Thus, you will need to install the MySQL JDBC driver as a module (see below).

Presumably the same is true of the postgresql driver.

It appears that if the exampleds is removed from the configuration deployment of the postgresql driver and datasources fails.

(Wildfly 8 note) Also the above method seems unreliable in that intermittently wildfly refuses to start because of a damaged deployment. Other deployment approaches might be more reliable.

Datasources

Bedework is currently being run on postgresql, mysql, oracle and possibly sqlserver.

Using the console seems to be reasonably easy if repetitive. The following datasources are required:

1. java:CardDS - for CardDAV address books (use the hsql service if you don't use them)
2. java:CalendarDS - for the main calendar engine
3. java:EventregDS - for the event registration system
4. java:NotifyDS - for the notification engine
5. java:selfregDS - for the self-registration system
6. java:SynchDS - for the synchronization engine

Add a datasource for selfreg - even if it's not being used. We may need that to handle roles - see below

There is a script and a set of properties - one for each datasource and each database type - in the quickstart config directory. Take a copy of the properties and modify them with the correct url, id and password for your site, Then run the cli as follows

./jboss-cli.sh --file=path-to-your-quickstart/bedework/config/datasources/wildfly-create.txt --properties=your-properties-file

Do this for each datasource you want to deploy.

Note - there appears to be a bug in the cli - it gets a string range error if you try to provide a null password. Give it one and then edit the resulting configuration.

H2 driver

Wildfly comes with a fairly old version of h2. Navigate down to modules/system/layers/base/com/h2database/h2/main and replace the jar and update the module.xml file appropriately.

Hibernate

Wildfly comes with a relatively old versioon of hibernate. Install a later moduel by downloading from http://central.maven.org/maven2/org/hibernate/hibernate-orm-modules/5.2.5.Final/hibernate-orm-modules-5.2.5.Final-wildfly-10-dist.zip

Instructions are at https://docs.jboss.org/hibernate/orm/5.2/topical/html_single/wildfly/Wildfly.html

SSL

Our experience is running wildfly behind a combination of stunnel and haproxy. I believe the configuration is much the same for running behind apache. The key is that haproxy or apache must add X-Forwarded-For headers to each request.

In our setup we have theses requests come in on port 8081.

In haproxy add the line

option forwardfor
to the defaults section.

In the undertow subsystem configuration add the line:

                <http-listener name="stunnel" socket-binding="stunnel" secure="true" redirect-socket="https" proxy-address-forwarding="true" enable-http2="true"/>

and in the socket-binding section add

<socket-binding name="stunnel" port="8081"/>

Selfreg

Then build and deploy the selfreg module

./bw -dc bedework/config/wildfly.deploy.properties -wildfly -selfreg

Changes to sysevents

Because of issues with naming conventions the sysevents module optionally uses jmx to get its configuration. If that fails it falls back on sysevents.properties. That option will be removed from 4.0. It is there to preserve compatability with the jboss5 version.

Change the value of the system property:

For jboss 5
    <syseventsProperty>org.bedework.connection.factory.name=java:jms/BedeworkConnectionFactory</syseventsProperty>
For wildfly
    <syseventsProperty>org.bedework.connection.factory.name=java:/jms/BedeworkConnectionFactory</syseventsProperty>

JMX issues

There is a system property org.bedework.jmx.isJboss5 which is set in the jboss 5 startup and used by the JMX utility classes in the ManagementContext.registerMBean method. It's unclear if this is needed for wildfly or if it was to address a jboss5 specific issue.

Activemq

The eventual aim is to remove the dependency on activemq. While there are no code dependencies the system does use some features of activemq not present in other JMS subsystems.

Following the instructions at https://developer.jboss.org/wiki/HowToUseOutOfProcessActiveMQWithWildFly

Replaced the line:

<subsystem xmlns="urn:jboss:domain:resource-adapters:3.0"/>

with

<subsystem xmlns="urn:jboss:domain:resource-adapters:2.0">
  <resource-adapters>
    <resource-adapter id="activemq-rar.rar">
      <archive>
        activemq-rar-5.12.1.rar
      </archive>
      <transaction-support>XATransaction</transaction-support>
      <config-property name="ServerUrl">failover:(${org.bedework.activemq.uri})?timeout=3000</config-property>
      <connection-definitions>
        <connection-definition class-name="org.apache.activemq.ra.ActiveMQManagedConnectionFactory"
                               jndi-name="java:/jms/BedeworkConnectionFactory"
                               enabled="true" pool-name="ConnectionFactory">
          <xa-pool>
            <min-pool-size>1</min-pool-size>
            <max-pool-size>200</max-pool-size>
            <prefill>false</prefill>
            <is-same-rm-override>false</is-same-rm-override>
          </xa-pool>
          <timeout>
            <blocking-timeout-millis>30000</blocking-timeout-millis>
            <idle-timeout-minutes>3</idle-timeout-minutes>
          </timeout>
        </connection-definition>
      </connection-definitions>
      <admin-objects>
        <admin-object class-name="org.apache.activemq.command.ActiveMQQueue" jndi-name="java:/activemq/queue/sysevents" use-java-context="true" pool-name="syseventsQueue">
          <config-property name="PhysicalName">
            bedework.sysevents
          </config-property>
        </admin-object>
        <admin-object class-name="org.apache.activemq.command.ActiveMQQueue" jndi-name="java:/activemq/queue/syseventslog" use-java-context="true" pool-name="syseventsLoggerQueue">
          <config-property name="PhysicalName">
            bedework.sysevents.logger
          </config-property>
        </admin-object>
        <admin-object class-name="org.apache.activemq.command.ActiveMQQueue"
                      jndi-name="java:/activemq/queue/monitor" use-java-context="true"
                      pool-name="syseventsMonitorQueue">
          <config-property name="PhysicalName">
            bedework.sysevents.monitor
          </config-property>
        </admin-object>
        <admin-object class-name="org.apache.activemq.command.ActiveMQQueue"
                      jndi-name="java:/activemq/queue/crawler" use-java-context="true"
                      pool-name="syseventsCrawlerQueue">
          <config-property name="PhysicalName">
            bedework.sysevents.crawler
          </config-property>
        </admin-object>
        <admin-object class-name="org.apache.activemq.command.ActiveMQQueue"
                      jndi-name="java:/activemq/queue/changes" use-java-context="true"
                      pool-name="syseventsChangesQueue">
          <config-property name="PhysicalName">
            bedework.sysevents.changes
          </config-property>
        </admin-object>
        <admin-object class-name="org.apache.activemq.command.ActiveMQQueue"
                      jndi-name="java:/activemq/queue/schedulerIn" use-java-context="true"
                      pool-name="scheduleInQueue">
          <config-property name="PhysicalName">
            bedework.scheduleIn
          </config-property>
        </admin-object>
        <admin-object class-name="org.apache.activemq.command.ActiveMQQueue"
                      jndi-name="java:/activemq/queue/schedulerOut" use-java-context="true"
                      pool-name="scheduleOutQueue">
          <config-property name="PhysicalName">
            bedework.scheduleOut
          </config-property>
        </admin-object>
      </admin-objects>
    </resource-adapter>
  </resource-adapters>
</subsystem>

No idea what the significance of the trailing number is in the URN.

Downloaded activemq RA 5.12.1 and unzip it into a directory named activemq-rar-5.12.1.rar in standalone/deployments. This approach is based on that at https://wildflyext.gitbooks.io/wildfly-camel/content/components/camel-activemq.html

...

 jboss 5
    <syseventsProperty>org.bedework.connection.factory.name=java:jms/BedeworkConnectionFactory</syseventsProperty>
For wildfly
    <syseventsProperty>org.bedework.connection.factory.name=java:/jms/BedeworkConnectionFactory</syseventsProperty>

JMX issues

There is a system property org.bedework.jmx.isJboss5 which is set in the jboss 5 startup and used by the JMX utility classes in the ManagementContext.registerMBean method. It's unclear if this is needed for wildfly or if it was to address a jboss5 specific issue.

Activemq

The bedenote (to be renamed to bwmsg) module uses camel to provide the activemq features that were used in jboss, mostly virtual destinations. We are now able to use the standard wildfly jms system.

Access logging

Particularly useful for debugging. Go to the cli tool and enter the following:

...

At that point it seems to deploy correctly and we can log in.