Installing Orbeon Forms on Apache Tomcat

1. Assuming that TOMCAT_HOME represents the location of your Tomcat installation: create a new TOMCAT_HOME/webapps/orbeon directory.
2. Unzip orbeon.war in the orbeon directory you just created.
3. You can now start Tomcat, and access http://localhost:8080/orbeon/ to test your installation (replacing localhost and 8080 with the host name and port number of your Tomcat installation if different from the default).
4. Optionally, to run the authentication example:
   
   
1. Open TOMCAT_HOME/webapps/orbeon/WEB-INF/web.xml and uncomment the security-constraint, login-config and security-role declarations at the end of the file.
2. Open TOMCAT_HOME/conf/server.xml and uncomment the following declaration: <Realm className="org.apache.catalina.realm.MemoryRealm" />
3. Edit TOMCAT_HOME/conf/tomcat-users.xml and replace the content of the file with:
   
   
   <tomcat-users>
    <role rolename="orbeon-user"/>
    <role rolename="orbeon-admin"/>
    <user username="orbeonadmin" password="xforms" roles="orbeon-user,orbeon-admin"/>
</tomcat-users>
   
   

On Unix systems, we recommend you don't use GIJ / GCG, as there are reports as of June 2008 of issues with that runtime environment and Orbeon Forms. Instead, we recommend you use the Sun runtime environment.

Installing Orbeon Forms on Oracle WebLogic 10/11g

A version of the ANTLR library that ships with WebLogic 10/11g conflicts with the version required by Orbeon Forms. To run Orbeon Forms on WebLogic 10/11g, you need to instruct WebLogic to let Orbeon Forms use the version of ANTLR that ships with Orbeon Forms. You can do this in the WebLogic EAR descriptor, which means you need to encapsulate Orbeon Forms in an EAR before you deploy it:

1. Create the following directory structure in a temporary directory:
   
   
   orbeon-ear
    META-INF
        application.xml
        weblogic-application.xml
    orbeon
   
   Populate application.xml with:
   
   
   <?xml version="1.0"?>
<j2ee:application xmlns:j2ee="http://java.sun.com/xml/ns/j2ee">
    <j2ee:display-name>Orbeon Forms</j2ee:display-name>
    <j2ee:module>
        <j2ee:web>
            <j2ee:web-uri>orbeon</j2ee:web-uri>
            <j2ee:context-root>/orbeon</j2ee:context-root>
        </j2ee:web>
    </j2ee:module>
</j2ee:application>
   
   Populate weblogic-application.xml with:
   
   
   <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE weblogic-application PUBLIC
    "-//BEA Systems, Inc.//DTD WebLogic Application 8.1.0//EN"
    "http://www.bea.com/servers/wls810/dtd/weblogic-application_2_0.dtd">
<weblogic-application>
    <prefer-application-packages>
        <package-name>antlr.*</package-name>
    </prefer-application-packages>
</weblogic-application>
   
   
2. Uncompress the orbeon.war into the orbeon-ear/orbeon directory you created in step 1. After this, you should have a directory orbeon-ear/orbeon/WEB-INF.
3. Deploy the orbeon-ear directory. If you are running WebLogic in development mode, you can move it to user_projects/domains/base_domain/autodeploy.
   
4. Optionally, you might want to change where the orbeon.log is stored. You define the location of the file in WEB-INF/resources/config/log4j.xml, in the SingleFileAppender. By default the location of the file is defined as ../logs/orbeon.log. If you start WebLogic with user_projects/domains/base_domain/startWebLogic.sh, the log will be located in user_projects/domains/logs/orbeon.log.
   

Installing Orbeon Forms on BEA WebLogic 9.1

1. Select a directory where you want to store your web application. Let's assume the path you chose is C:/WebApps/orbeon.
2. Unzip orbeon.war into C:/WebApps/orbeon. There should now be a directory called WEB-INF under C:/WebApps/orbeon.
3. Start WebLogic's administration console.
4. Use the console to install a new Web application. When prompted to select a WAR file, point to the directory C:/WebApps/orbeon. When prompted for a context path, choose a value such as orbeon. Complete the installation and start the web application.
5. You should now be able to access the Orbeon Forms example applications by pointing your browser to the address of your WebLogic server followed by the context path you chose, for example: http://localhost:7001/orbeon/.

Installing Orbeon Forms on IBM WebSphere 5 and 6

1. Launch WebSphere server.
   
   
• Let's assume WSAS_HOME represents the location of your WebSphere installation.
• On Windows:
• To run WebSphere from the command line, execute WSAS_HOME/bin/startServer server1 (on WebSphere 5).
• To run WebSphere as a service: go to Control Panel, Administrative Tools, Services, Look for IBM WebSphere Application Server and make sure it is started.
• On Linux/UNIX:
• Run WSAS_HOME/profiles/default/bin/startServer.sh server1.
• Note:
• The default heap size is likely to be too low. You can increase the heap size from the WebSphere Administrative Console, by going to Server / Application Servers / server1 / Process Definition / Java Virtual Machine. There we recommend you set the Initial Heap Size and Maximum Heap Size to the same value.
  
  
2. Log in to the administrative console.
   
   
1. On WebSphere 5: got to http://localhost:9090/admin/.
2. On WebSphere 6: got to http://localhost:9060/ibm/console/.
3. The default administrator login is admin.
   
   
3. Install and deploy Orbeon Forms (orbeon.war).
   
   
• Click on Applications / Install New Application.
• Select the orbeon.war to upload, choose a context path like /orbeon (from now on we will assume this was your choice).
• Hit "next" until you get to the end of the wizard, then hit "finish". You can leave the defaults everywhere while going through the wizard.
• Save the configuration.
• Click on Applications / Enterprise Applications.
• Select orbeon_war and click on the "start" button.
• Note:
• One important log file (if something goes wrong when the application starts) is: WSAS_HOME/logs/server1/SystemOut.log on WebSphere 5.
• The WAR file is uncompressed by WebSphere in WSAS_HOME/installedApps/NODE_NAME/orbeon_war.ear/orbeon.war on WebSphere 5, where NODE_NAME if usualy your machine name.
  
  
4. Run and modify the example applications.
   
   
• Go to http://localhost:9080/orbeon/.
• You can view the log from Orbeon Forms in WSAS_HOME/profiles/default/logs/server1/SystemOut.log.
• You can modify the example applications resources as the application sever is running and see the results of your modifications on the fly. The resources are stored under WSAS_HOME/profiles/default/installedApps/yourmachineNode01Cell/orbeon_war.ear/orbeon.war/WEB-INF/resources. For instance, try to modify apps/xforms-hello/view.xhtml: replace "Please enter your first name:" by your own message, and reload the page in the browser to see the result.
  

Installing Orbeon Forms on JBoss

1. Assuming that JBOSS_HOME represents the location of your JBoss installation: create a new JBOSS_HOME/server/default/deploy/orbeon.war directory.
   
2. Unzip the orbeon.war file in the orbeon.war directory you just created.
   
3. If you are using JBoss 5.0, you can skip this. Otherwise:
   
   
• With JBoss 4.0 / JBoss 4.2:
  
  
1. Set the following parameter in web.xml:
   
   <context-param>
    <param-name>oxf.initialize-logging</param-name>
    <param-value>false</param-value>
</context-param>
2. Rename the default Orbeon Forms log4j JAR file under WEB-INF/lib from log4j-*.jar to log4j-*.jar.bak. Additionally, you can remove this JAR file altogether.

• With JBoss 4.0:

1. Create a file jboss-web.xml in JBOSS_HOME/server/default/deploy/orbeon.war/WEB-INF with the following content:
   
   <jboss-web>
    <class-loading java2ClassLoadingCompliance="false">
        <loader-repository>
            orbeon.war:loader=orbeon.war
            <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
        </loader-repository>
    </class-loading>
</jboss-web>
   
   
• With JBoss 3.2:
  
  
1. In JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/META-INF/jboss-service.xml and change the value in <attribute name="UseJBossWebLoader"> from false to true.
   
   
1. Start JBoss by running JBOSS_HOME/bin/run.bat (or run.sh on UNIX).
   
2. Run and modify the example applications.
   
   
1. Go to http://localhost:8080/orbeon/
2. You can modify the example applications resources as the application sever is running and see the results of your modifications on the fly. The resources are stored under JBOSS_HOME/server/default/deploy/orbeon.war/WEB-INF/resources.
   
   
3. Optionally, to run the authentication sample:
   
   
1. Open JBOSS_HOME/server/default/deploy/orbeon.war/WEB-INF/web.xml and uncomment the security-constraint, login-config and security-role declarations at the end of the file.
2. Open JBOSS_HOME/server/default/deploy/orbeon.war/WEB-INF/jboss-web.xml and uncomment the security-domain element near the end of bottom of the file.
3. Open JBOSS_HOME/server/default/conf/login-config.xml and add the following aplication policy to the list of policies:
   
   <application-policy name="orbeon-demo">
    <authentication>
        <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
            <module-option name="usersProperties">jboss-orbeon-example-users.properties</module-option>
            <module-option name="rolesProperties">jboss-orbeon-example-roles.properties</module-option>
        </login-module>
    </authentication>
</application-policy>
   
   
4. Optionally, you might want to setup a JDBC data source if your application is using the SQL Processor. What follows assumes you are configuring the SQL Processor with <sql:datasource>my-datasource</sql:datasource>.
   
   
1. Look at the files JBOSS_HOME/docs/examples/jca/*-ds.xml. You should find one that correspond to the database you are using. Copy it to JBOSS_HOME/server/default/deploy.
2. Edit the file you copied and change the parameters to match your database configuration. Also assign a JNDI name to this data source with: <jndi-name>my-database</jndi-name> (instead of my-database you might want to use a name which is descriptive of your database).
3. Edit WEB-INF/web.xml and uncomment the <resource-ref>. Also change there the content of <res-ref-name> to match the name you are using in the SQL Processor prefixed with jdbc/: <res-ref-name>jdbc/my-datasource</res-ref-name>.
4. Edit WEB-INF/jboss-web.xml. In that file you should have <res-ref-name>jdbc/my-datasource</res-ref-name> (the same name you use to configure the SQL Processor and that you have in the web.xml) and <jndi-name>java:/my-database</jndi-name> (the same name you declared in the ...-ds.xml file).
5. Copy the JAR files with the JDBC driver for your database in JBOSS_HOME/server/default/lib.

Installing Orbeon Forms on Oracle Application Server and OC4J

To run Orbeon Forms on Oracle Application Server or OC4J, edit $ORACLE_HOME/j2ee/home/application-deployments/orbeon/orbeon/orion-web.xml and uncomment the following line: