Orbeon Forms can be downloaded from http://www.orbeon.com/forms/download.

To install Orbeon Forms you need an application server that runs on Java version 1.4.2 (or later) and implements the Servlet API 2.3 (or later). Orbeon Forms has been used by various organizations on the following application servers:

• Apache Tomcat 5.5.20 (JDK 1.5.0 and 1.6)
• BEA WebLogic Server 9.1 (JRockit)
• IBM WebSphere 6
• JOnAS 4.6.6 (Tomcat 5.5.12, JDK 1.5.0)
• JBoss 4.0.4
• GlassFish

Please contact us if you have questions about support for other application servers or versions.

1. Assuming that TOMCAT_HOME represents the location of your Tomcat installation: create a new TOMCAT_HOME/webapps/ops directory.

2. Unzip ops.war in the ops directory you just created.

3. With Tomcat 5, move xercesImpl.jar and xmlParserAPIs.jar from common/endorsed to server/lib. This way Xerces will be available to Tomcat, but it won't override the version of Xerces and standard XML APIs that comes with Orbeon Forms.

4. You can now start Tomcat, and access http://localhost:8080/ops/ to test your installation (replacing localhost and 8080 with the host name and port number of your Tomcat installation if different from the default), or perform one of the optional installation steps below.

5. Optionally, to run the authentication example:

   1. Open TOMCAT_HOME/webapps/ops/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 this by with:
      <tomcat-users><role rolename="orbeon-user"/><role rolename="orbeon-admin"/><user username="orbeonadmin" password="xforms" roles="orbeon-user,orbeon-admin"/></tomcat-users>

1. Select a directory where you want to store your web application. Let's assume the path you chose is C:/WebApps/ops.

2. Unzip ops.war into C:/WebApps/ops. There should now be a directory called WEB-INF under C:/WebApps/ops.

3. Start WebLogic's adminstration console.

4. Use the console to install a new Web application. When prompted to select a WAR file, point to the directory C:/WebApps/ops. When prompted for a context path, choose a value such as ops. 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/ops/.

1. Assume that DOMAIN represents your WebLogic domain directory (typically c:\bea\user_projects). Create a new directory: DOMAIN\applications\orbeon.

2. Unzip ops.war in the orbeon directory you just created.

3. Edit the startWeblogic.cmd (in DOMAIN) and change set STARTMODE=true to set STARTMODE=false. This starts WebLogic in development mode. In development mode, WebLogic automatically loads and deploys the content of the application directory. If you don't want to start the server in development mode, you have to explicitly declare a Web application in the config.xml.

4. To improve performance on WebLogic (highly recommended!):

   1. Start WebLogic (e.g. with startWebLogic.cmd)
   2. Make sure you can access the Orbeon Forms example applications with your browser (by going to http://localhost:7001/orbeon/)
   3. Stop WebLogic
   4. Open the config.xml file in an editor. Look for the <WebAppComponent Name="orbeon"> element and add the attribute: ServletReloadCheckSecs="-1". This will prevent WebLogic from checking if a servlet has changed in the application and will make Orbeon Forms much faster.

5. Optionally, to run the authentication example:

   1. Open DOMAIN/applications/orbeon/WEB-INF/web.xml and uncomment the security-constraint, login-config and security-role declarations at the end of the file.
   2. Go to the WebLogic Console with a browser.
   3. Create a new user named admin with a password of your choice.

6. Once Orbeon Forms is properly installed, you can start WebLogic as usual with the startWeblogic.cmd script (in DOMAIN).

1. Launch WebSphere server.

   • On Windows, running WebSphere:
     • From the command line, execute WSAS_HOME/bin/startServer server1 (on WebSphere 5).
     • 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, assuming that WSAS_HOME represents the location of your WebSphere installation, 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.

   • On WebSphere 5: got to http://localhost:9090/admin/.
   • On WebSphere 6: got to http://localhost:9060/ibm/console/.
   • The default administrator login is admin.

3. Install and deploy Orbeon Forms (ops.war).

   • Click on Applications / Install New Application.
   • Select the ops.war to upload, choose a context path like /ops (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 ops_war and click on the "start" button.

   • Note:

     • One important log file (if something goes wrong when the applicaiton starts) is: WSAS_HOME/logs/server1/SystemOut.log on WebSphere 5.
     • The WAR file is uncompressed by WebSphere in WSAS_HOME/installedApps/NODE_NAME/ops_war.ear/ops.war on WebSphere 5, where NODE_NAME if usualy your machine name.

4. Run and modify the example applications.

   • Go to http://localhost:9080/ops/.
   • 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/ops.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.

1. Assuming that JBOSS_HOME represents the location of your JBoss installation: create a new JBOSS_HOME/server/default/deploy/ops.war directory.

2. Unzip ops.war in the ops.war directory you just created.

3. Set the following parameter in web.xml:

   <context-param><param-name>oxf.initialize-logging</param-name><param-value>false</param-value></context-param>

4. 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.

Note

NOTE: With certain versions of JBoss, in particular prior to 4.0.4, omitting the two steps above (setting the parameter and renaming the log4j JAR) but doing the following instead, may work:

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.

5. Start JBoss by running JBOSS_HOME/bin/run.bat (or run.sh on UNIX).

6. Run and modify the example applications.

   • Go to http://localhost:8080/ops/
   • 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/ops.war/WEB-INF/resources.

7. Optionally, to run the authentication sample:

   • Open JBOSS_HOME/server/default/deploy/ops.war/WEB-INF/web.xml and uncomment the security-constraint, login-config and security-role declarations at the end of the file.
   • Open JBOSS_HOME/server/default/deploy/ops.war/WEB-INF/jboss-web.xml and uncomment the security-domain element near the end of bottom of the file.
   • 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>

For security reasons, you might want to run Orbeon Forms under a Security Manager. Java's Security Manager allows you to control the Java sandbox and which resources the application can access. When installed correctly, the Security Manager can prevent unauthorized code to execute malicious actions, such as deleting files on the server or initializing network connections. For more information, please read the Security in Java 2 SDK 1.2 tutorial and the Security Manager API.

Follow the steps below to install the Security Manager:

1. Download the policy file.
2. Append the permissions to the application server policy file. The table lists the policy file for the supported servers.

   Apache Tomcat	catalina.policy
   BEA Weblogic	weblogic.policy
   IBM WebSphere	was.policy
   Sun ONE	server.policy

3. Add the following system properties to the server startup script.
   • oxf.home: Location of the Orbeon Forms exploded WAR file
   • oxf.resources: Location of Orbeon Forms resources directory
4. Modify the startup script to enable the security manager. Add the following system properties:
   • -Djava.security.manager
   • -Djava.security.policy=="path to the policy file"