Installing Orbeon Presentation Server

1. Downloading

Presentation Server can be downloaded from http://www.orbeon.com/community/downloads.

2. System Requirements

To install Presentation Server you need an application server that runs on Java version 1.4.1 (or later) and implements the Servlet API 2.3 (or later). Presentation Server is supported on the following application servers:

  • Apache Tomcat 4.1.31 with JDK 1.4.2
  • Apache Tomcat 5.0.28 with JDK 1.4.2
  • Apache Tomcat 5.5.4 with JDK 1.5.0
  • BEA WebLogic Server 7 and 8.1
  • IBM WebSphere 6
  • JBoss 3.2.6 and 4.0.0

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

3. Installing Presentation Server 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. 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 Presentation Server.

  4. 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), or perform one of the optional installation steps below.

  5. 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 this by with:

        <tomcat-users>
        <role rolename="administrator"/>
        <user username="admin" password="password" roles="administrator"/>
        </tomcat-users>

4. Installing Presentation Server on BEA WebLogic 7 and 8.1

  1. Assume that DOMAIN represents your WebLogic domain directory (typically c:\bea\user_projects). Create a new directory: DOMAIN\applications\orbeon.
  2. Unzip orbeon.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 Presentation Server examples 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 Presentation Server 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 Presentation Server is properly installed, you can start WebLogic as usual with the startWeblogic.cmd script (in DOMAIN).

5. Installing Presentation Server on IBM WebSphere 6

  1. Launch WebSphere server.

    • On Windows go to Control Panel, Administrative Tools, Services.
    • On Linux/UNIX, assuming that WSAS_HOME represents the location of your WebSphere installation, run WSAS_HOME/profiles/default/bin/startServer.sh server1.

  2. Log in to the administrative console.

    • Got to http://localhost:9060/ibm/console/.
    • The default administrator login is admin.

  3. Install and deploy Presentation Server (orbeon.war).

    • Click on Applications / Install New Application.
    • Upload orbeon.war and follow the wizard. We will assume that you chose /ops as context root.
    • Save the configuration.
    • Click on Applications / Enterprise Applications.
    • Select orbeon_war and click on the "start" button.

  4. Run and modify the examples.

    • Go to http://localhost:9080/ops/.
    • You can view the log from PresentationServer in WSAS_HOME/profiles/default/logs/server1/SystemOut.log.
    • You can modify the examples 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 examples/tutorial/hello1/view.xhtml: replace "Hello World!" by your own message, and reload the page in the browser to see the result.

6. Installing Presentation Server on JBoss 3.2.6 and 4.0.0

  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 orbeon.war in the orbeon.war directory you just created.
  3. Edit JBOSS_HOME/bin/run.bat (or run.sh on UNIX). Look for the line that starts with set JAVA_OPTS. Add at the end of this line the following option: -Dorg.jboss.logging.Log4jService.catchSystemOut=false
  4. If you are using JBoss 4.0.0, edit JBOSS_HOME/server/default/deploy/jbossweb-tomcat50.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. 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">orbeon-demo-users.properties</module-option>
        <module-option name="rolesProperties">orbeon-demo-roles.properties</module-option>
        </login-module>
        </authentication>
        </application-policy>

7. Running the BizDoc Tutorial Application

To install the standalone BizDoc application described in the Presentation Server Tutorial, simply deploy the orbeon-bizdoc.war file in your application server. To do so, follow the installation instructions above depending on your application server, but deploy orbeon-bizdoc.war instead of orbeon.war. You do not have to include the optional steps.

Access the application using the /orbeon-bizdoc/ path from web browser. For example, if you application server is running on your local host on port 8080, enter http://localhost:8080/orbeon-bizdoc/ in the URL bar of your web browser.

8. Security

For security reasons, you might want to run Presentation Server 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 Presentation Server exploded WAR file
    • oxf.resources: Location of Presentation Server 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"