JBoss Setup

WARNING

The supported app servers are currently WildFly 9.0.x. and EAP 6.4.

JBoss EAP 6.4

You can download JBoss EAP 6.4 to use with Zanata. Extract the archive. This location will be known as JBOSS_HOME for here on. You can start JBoss by typing the following on your command line.

$ cd $JBOSS_HOME
$ ./bin/standalone.sh

For developers on Red Hat Enterprise Linux, you can install JBoss EAP 6.4 by typing the following command on the terminal:

$ yum -y groupinstall "jboss-eap6"
# or:
$ yum -y install jbossas-standalone

This way of installing will place JBoss files under

• /usr/share/jbossas (JBOSS_HOME)
• /etc/jbossas
• /var/lib/jbossas (shortcuts in /usr/share/jbossas)

You can start JBoss EAP by typing the following command on a terminal:

$ service jbossas start

JBoss Configuration

JBoss can be configured manually by editing its standalone.xml configuration file. Additionally, it is possible to run the Zanata installer for the specific target JBoss or Wildfly platform and let it configure JBoss for you. Keep in mind the installer works for released versions of Zanata, so additional configuration may be need to run a development version.

Manual Configuration:

Configure JNDI entries in standalone.xml

Search subsystem xmlns="urn:jboss:domain:naming:1.3" and add bindings as following. Adjust the paths/emails accordingly.

<subsystem xmlns="urn:jboss:domain:naming:1.3">
    <bindings>
        <simple name="java:global/zanata/files/document-storage-directory" value="/example/path"/> #1.
        <simple name="java:global/zanata/security/auth-policy-names/internal" value="zanata.internal"/> #2.
        <simple name="java:global/zanata/security/auth-policy-names/openid" value="zanata.openid"/> #3.
        <simple name="java:global/zanata/security/admin-users" value="admin"/> #4.
        <simple name="java:global/zanata/email/default-from-address" value="[email protected]"/> #5.
    </bindings>
    <remote-naming/>
</subsystem>

1. Replace /example/path with the absolute path to the directory for document storage.
2. Remove this line to disable internal authentication.
3. Remove this line to disable OpenId authentication.
4. Replace admin with the lists of users that will become the admin once they finished registration. Use with care!
5. Replace [email protected] with the email address you want your user to see as "From:".

Optional entries that can be defined in JNDI please refer to source org.zanata.config.JndiBackedConfig.

Install MySQL driver

$ sudo yum install mysql-connector-java
$ cd $JBOSS_HOME
$ ln -s /usr/share/java/mysql-connector-java.jar standalone/deployments/

Create a datasource for Zanata:

Create the file $JBOSS_HOME/standalone/deployments/zanata-ds.xml (modify to suit):

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- http://docs.jboss.org/ironjacamar/schema/datasources_1_0.xsd -->
    <!--
    Using this datasource:
    1. create a jboss module for mysql-connector and activate it using jboss-cli.sh
    2. save this datasource as JBOSS_HOME/standalone/deployments/zanata-ds.xml
    See http://jaitechwriteups.blogspot.com/2012/02/jboss-as-710final-thunder-released-java.html
    -->
    <datasources>
      <datasource jndi-name="java:jboss/datasources/zanataDatasource"
        enabled="true" use-java-context="true" pool-name="zanataDatasource">
        <connection-url>jdbc:mysql://localhost:3306/zanata?characterEncoding=UTF-8</connection-url>
        <driver>mysql-connector-java.jar</driver>
        <security>
           <user-name>root</user-name>
<!--
           <password></password>
-->
        </security>
      </datasource>
    </datasources>

Configure zanata properties in standalone.xml

$ $EDITOR standalone/configuration/standalone.xml

...
            <extensions>
...
            </extensions>
            <system-properties>
	         <property name="javamelody.storage-directory" value="${user.home}/stats"/>
    	         <property name="hibernate.search.default.indexBase" value="${user.home}/indexes"/>
            </system-properties>
...

These properties should be set to the location where Zanata will store system statistics, and search indexes respectively.

Configure security domain zanata in standalone.xml

Insert following under element <security-domains>:

<security-domains>
    ...
    <security-domain name="zanata">
        <authentication>
            <login-module code="org.zanata.security.ZanataCentralLoginModule" flag="required"/>
        </authentication>
    </security-domain>
    <security-domain name="zanata.openid">
        <authentication>
            <login-module code="org.zanata.security.OpenIdLoginModule" flag="required"/>
        </authentication>
    </security-domain>
    <security-domain name="zanata.internal">
        <authentication>
            <login-module code="org.jboss.seam.security.jaas.SeamLoginModule" flag="required"/>
        </authentication>
    </security-domain>
    ...
</security-domains>

If jboss is running, tell it to apply the change with:

$ ./jboss-cli.sh -c :reload

The code snippet above is specific to internal authentication.

Automatic configuration using the Zanata installer

After downloading the Zanata Installer simply extract the file on top of your existing JBoss or Wildfly distribution. Then run the installer script located at $JBOSS_HOME/bin/zanata-installer/install-zanata

Running Integration Tests

To run integration tests (mvn integration-test or mvn verify), a fresh instance of JBoss is required. Modify the arquillian.xml file in zanata-server. The jbossHome property should point to the location of this new JBoss instance. The integration tests will deploy all needed files, start and stop the instance. Alternatively, this property may be removed and the JBOSS_HOME environment variable may be used.

Building and deploying:

$ mvn clean install -DskipTests -DskipArqTests -DskipFuncTests -Dappserver=jbosseap6 -am -pl zanata-war
$ cp zanata-war/target/zanata-<version>-SNAPSHOT.war $JBOSS_HOME/standalone/deployments/zanata.war
- Start JBoss service. http://localhost:8080/zanata

Other things that might help

In bin/standalone.conf:

• To increase memory for classes (and multiple redeployments), change -XX:MaxPermSize=256m to -XX:MaxPermSize=512m

• To enable debugging, uncomment JAVA_OPTS="$JAVA_OPTS -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"

• To fix the JBoss EAP 6 problem where most of the logging is missing, add this line:

  JAVA_OPTS="$JAVA_OPTS -Dorg.jboss.as.logging.per-deployment=false"