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
1. Downloading
Orbeon Forms can be downloaded from http://www.orbeon.com/forms/download.
2. System Requirements
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.x and 5.x
- GlassFish
Please contact us if you have questions about support for other application servers or versions.
3. Installing Orbeon Forms on Apache Tomcat
-
Assuming that
TOMCAT_HOME
represents the location of your Tomcat installation: create a newTOMCAT_HOME/webapps/orbeon
directory. -
Unzip
orbeon.war
in theorbeon
directory you just created. -
With Tomcat 5, move
xercesImpl.jar
andxmlParserAPIs.jar
fromcommon/endorsed
toserver/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. -
You can now start Tomcat, and access
http://localhost:8080/orbeon/
to test your installation (replacinglocalhost
and8080
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. -
Optionally, to run the authentication example:
-
Open
TOMCAT_HOME/webapps/orbeon/WEB-INF/web.xml
and uncomment thesecurity-constraint
,login-config
andsecurity-role
declarations at the end of the file. -
Open
TOMCAT_HOME/conf/server.xml
and uncomment the following declaration:<Realm className="org.apache.catalina.realm.MemoryRealm" />
-
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>
-
Open
4. Installing Orbeon Forms on BEA WebLogic 9.1
-
Select a directory where you want to store your web application. Let's assume the path you chose is
C:/WebApps/orbeon
. -
Unzip
orbeon.war
intoC:/WebApps/orbeon
. There should now be a directory calledWEB-INF
underC:/WebApps/orbeon
. -
Start WebLogic's adminstration console.
-
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 asorbeon
. Complete the installation and start the web application. -
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/
.
5. Installing Orbeon Forms on BEA WebLogic 7.0 and 8.1
Orbeon Forms 3.0 hasn't been tested with these versions of WebLogic, but you may want to try the following instructions for Orbeon Forms 2.8.
-
Assume that
DOMAIN
represents your WebLogic domain directory (typicallyc:\bea\user_projects
). Create a new directory:DOMAIN\applications\orbeon
. -
Unzip
orbeon.war
in theorbeon
directory you just created. -
Edit the
startWeblogic.cmd
(inDOMAIN
) and changeset STARTMODE=true
toset STARTMODE=false
. This starts WebLogic in development mode. In development mode, WebLogic automatically loads and deploys the content of theapplication
directory. If you don't want to start the server in development mode, you have to explicitly declare a Web application in theconfig.xml
. -
To improve performance on WebLogic (highly recommended!):
-
Start WebLogic (e.g. with
startWebLogic.cmd
) -
Make sure you can access the Orbeon Forms example applications with your browser (by going
to
http://localhost:7001/orbeon/
) - Stop WebLogic
-
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.
-
Start WebLogic (e.g. with
-
Optionally, to run the authentication example:
-
Open
DOMAIN/applications/orbeon/WEB-INF/web.xml
and uncomment thesecurity-constraint
,login-config
andsecurity-role
declarations at the end of the file. - Go to the WebLogic Console with a browser.
-
Create a new user named
admin
with a password of your choice.
-
Open
-
Once Orbeon Forms is properly installed, you can start WebLogic as usual with the
startWeblogic.cmd
script (inDOMAIN
).
6. Installing Orbeon Forms on IBM WebSphere 5 and 6
-
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.
-
From the command line, execute
-
On Linux/UNIX, assuming that
WSAS_HOME
represents the location of your WebSphere installation, runWSAS_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.
-
On Windows, running WebSphere:
-
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
.
- On WebSphere 5: got to
-
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 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/orbeon_war.ear/orbeon.war
on WebSphere 5, where NODE_NAME if usualy your machine name.
-
One important log file (if something goes wrong when the applicaiton starts)
is:
-
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 modifyapps/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.
- Go to
7. Installing Orbeon Forms on JBoss
-
Assuming that
JBOSS_HOME
represents the location of your JBoss installation: create a newJBOSS_HOME/server/default/deploy/orbeon.war
directory. -
Unzip
orbeon.war
in theorbeon.war
directory you just created. -
If you are using JBoss 4.2 or 5.0, you can skip this. Otherwise:
-
With JBoss 4.0:
-
Set the following parameter in
web.xml
:<context-param><param-name>oxf.initialize-logging</param-name><param-value>false</param-value></context-param> -
Rename the default Orbeon Forms log4j JAR file under WEB-INF/lib from
log4j-*.jar
tolog4j-*.jar.bak
. Additionally, you can remove this JAR file altogether. -
Create a file
jboss-web.xml
inJBOSS_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:
-
In
JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/META-INF/jboss-service.xml
and change the value in<attribute name="UseJBossWebLoader">
fromfalse
totrue
.
-
-
-
Start JBoss by running
JBOSS_HOME/bin/run.bat
(orrun.sh
on UNIX). -
Run and modify the example applications.
- Go to
http://localhost:8080/orbeon/
-
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
.
- Go to
-
Optionally, to run the authentication sample:
-
Open
JBOSS_HOME/server/default/deploy/orbeon.war/WEB-INF/web.xml
and uncomment thesecurity-constraint
,login-config
andsecurity-role
declarations at the end of the file. -
Open
JBOSS_HOME/server/default/deploy/orbeon.war/WEB-INF/jboss-web.xml
and uncomment thesecurity-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>
-
Open
-
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>
.-
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 toJBOSS_HOME/server/default/deploy
. -
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 ofmy-database
you might want to use a name which is descriptive of your database). -
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 withjdbc/
:<res-ref-name>jdbc/my-datasource</res-ref-name>
. -
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 theweb.xml
) and<jndi-name>java:/my-database</jndi-name>
(the same name you declared in the...-ds.xml
file). -
Copy the JAR files with the JDBC driver for your database in
JBOSS_HOME/server/default/lib
.
-
Look at the files
8. Security
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:
- Download the policy file.
-
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 -
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
-
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"