Guidelines to run OFBiz under WASCE 2.0.0.1 or Geronimo 2.0.3

Goal

This is intended to be used at production stage. The idea is to develop as normal under OFBiz, and then, when at production stage, to deploy on a WASCE/Geronimo server. You can then update anew when needed from developement machine(s).

How it works

This uses a totally exploded EAR architecture (with exploded WARs as well). The deployment tool is for the moment intended to be use on a sole machine. You can deploy remotely (on a Linux Server from a Windows machine for instance, or whatever actually) but there are some drawbacks due to Geronimo itself. See comments at end of this page. So the idea is to have an OFBiz instance on the server you want to deploy and to update it from your development machine(s) (using Subversion for instance). Then to deploy locally from this updated OFBiz instance on the server.

WASCE 2.0.0.1 is based on Geronimo 2.0.3 which is a snapshot, previous versions don't work nor 2.1, but Geronimo 2.1.1 works.

The code and templates are in framework/appserver/wasce2. Of course, this works under Linux and Windows as well.

Install

http://publib.boulder.ibm.com/wasce/V2.0.0/en/quick-start.html or Geronimo 2.0.3 (see link above)
If needed refer to documentation using bread crumbs links in the web page above (WASCE 2.0 Documentation > Index > Content > Setup > Choosing an installation bundle) or/and use Geronimo documentation : http://cwiki.apache.org/GMOxDOC20/

• At this stage, don't try to install and use Eclipse plugins. They are not up to date yet, and will not be of a great help in our case anyway (I tried them, and lost some time around this)

• After installation, you may set your GERONIMO_HOME env var. But you might prefer to set it in the appserver.properties file. In the same time check the content of this file and adapt it suiting your needs. If present GERONIMO_HOME env var is not overloaded by geronimoHome appserver.properties value.

Setup and deploy (or redeploy)

• First check and adapt the content of the appserver.properties file
  • For instance system/manager are the defaut login/pwd coming with WASCE (and Geronimo). You may need to change them, but there are more important informations, please check
• From a clean OFBiz installation which runs well on the same machine than where WASCE is installed, at OFBiz root (or Eclipse, or what else) run

  java -jar ofbiz.jar -setup wasce2

  You may do it offline or inline depending of appserver.properties file setting for offline parameter. Of course if you use offline=false the application server should run before. This should deploy OFBiz under your application server and generate 4 kinds of files.

1. OFBiz jar files in the Geronimo repository
2. Deployment plans (application.xml and geronimo-application.xml) in a generated META-INF directory (in OFBiz root directory). Though the term "deployment plans" is normally used only for Geronimo specific "J2EE deployment descriptors" (application.xml for instance is a standard "J2EE deployment descriptors")
3. Deployment plans (geronimo-web.xml) in each applications WEB-INF directories
4. There is one more README file generated in OFBiz META-INF directory. Open it and follow its intructions before running your application server (so the 1st time you need to deploy offline). Don't forget to have a look in this file, there are important informations generated there

Something like "Illegal character in path" in the log means that you must remove the corresponding file, these errors are often related to .xls of .pdf files (or what else) found in the OFBiz directories structure (these kinds of files don't exist in OFBiz OOTB). If it's not related directly to OFBiz remove it.

You might see an error message like

Error: ofbiz does not appear to be a the name of a module available
on the selected server. Perhaps it has already been stopped or
undeployed? If you're trying to specify a TargetModuleID, use the
syntax TargetName|ModuleName instead. If you're not sure what's
running, try the list-modules command.

Don't worry, this is because the deployment tool try before to undeploy (not in redeploy mode, note that redeploy implies an application server running). And if you see this message it's only because this module is not deployed on the server. Of course if this error appears during the deployment phase and not the undeployment one, there is a problem in your parameters.

In case of any other problems try to look 1st at http://publib.boulder.ibm.com/wasce/V2.0.0/en/troubleshooting.html

I should mention that it seems to me that deploying with a server already running (offline=false in appserver.properties) is faster but I did not measure exactly yet. Anyway, you need to deploy offline the 1st time you deploy since you need to put in the geronimo script (.bat or .sh) the generated and mandatory informations found in META-INF/README before running the server. Else OFBiz modules will not load and the server will hang.

Run

• Then if you launch the WASCE server using regular command (or running "Geronimo run" from GERONIMO_HOME\bin) it should start with OFBiz modules loaded. For obvious port conflicts reason, don't run standard OFBiz at the same time.
  • If you run the Geronimo script from GERONIMO_HOME\bin

    geronimo run 

    with the geronimo (and possibly setenv) script modified following instructions in the README file you will see what happens. This is why I think it's a preferable way of launching the server.

• You will find OFBiz specific logs in geronimo_home\bin\framework\logs directory

RMI

If you need to use RMI follow directions at end of the framework\appserver\templates\wasce2\README file. Note that I only tried without SSL using this tip

Multi-instances

The appserver "-setup" deployment option is able to deploy OFBiz multi-instances in Geronimo. Actually there are, at least, 2 cases for multi-instances.

1. Instances are all the same (simple case)
2. Instances are differents or mixed (some instances may be the same)

In the simple case we need only one root (ofbiz.home) and one classpath. Instances are numbered, except the "default one". This allows to keep OFBiz current code : all links from a numbered instances going out of the current application to another application will go to the corresponding called application in the default non numbered instance. This is more a hack but it works. It's interesting when you have a lot of people working in a sole application as it's the case when you have a group of people working to seel goods by phone or other channels (customer support) and for the eCommerce aplication as well.

In the second case there are as many as roots and classpathes couples as there are different instances. I have already in code what is needed to deal with both cases, but I got an issue when writing to modules web.xml (the xml root node is readonly and I don't understand why). In the simple case it's not a problem as we need only to write in the 1st web.xml file (in webtools's) and we can do it by hand (we don't need to dynamically put an instance number in it). Anyway there is much more than this since OFBiz is not build to run multi-instances. In the 1st case it's less a problem as all instances refer to the default corresponding application but to work properly in the general case it would need to introduce an instance number parameter in links. Waiting for such a solution I can see two ways :

• Introduce an instance number in the web.xml file of the 1st web app loaded (OOTB it's webtools). Then use 2 instances for each instance one numbered and the other not. This is of course very clumsy
• I also got a glimpse of another possibility during my reading of Geronimo or? WASCE documentation but I forgot where. I'm pretty sure it's the right solution, but I would have to search anew... It's a bit like Ludovic Maître's suggestion in one of his emails in user ML (he wrote about Tomcat namespaces but it was not clear to me about what exactly he was speaking).

Miscellaneous experiences

Redeployment

You can't redeploy OFBiz modules (web apps actually) independently. You have to redeploy the whole ear. This is because we use a totally exploded EAR (with WARs exploed inside) more information on Geronimo forum.

Remote deployment (not recommended)

Remote deployment using the --inPlace option (for a totally exploded EAR with exploded and only exploded WARs inside as OFBiz is deployed above) is only possible if you exactly replicate the deployed directory structure on both the client and the server machine. If you are on Windows you must even replicate the drive more information on Geronimo forum. I have open a Jira issue for this https://issues.apache.org/jira/browse/GERONIMO-3963. Also beware of heterogeous environments (Windows to Linux for instance) as I did any such tests.