Guidelines to

...

run OFBiz under WASCE 2.0.0.1 or Geronimo 2.1.1

...

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 . You can 't deploy remotely (on a Linux Server from a Windows machine for instance, or whatever actually). I'm working on a solution to be able to deploy remotely...) 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 from this updated OFBiz instance on the server itself.

WASCE 2.0.0.1 is based on Geronimo 2.0.3 which is a snapshot (, previous versions , and so far 2.1, don't work ), I got it there http://people.apache.org/repo/m2-snapshot-repository/org/apache/geronimo/assemblies/geronimo-tomcat6-jee5/2.0.3-SNAPSHOT/geronimo-tomcat6-jee5-2.0.3-20080318.171132-2-bin.zip^{Image Removed}
To know more have a look at https://issues.apache.org/jira/browse/GERONIMO-3947^{Image Removed}nor 2.1, but Geronimo 2.1.1 works (and I suppose above).

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.WASCE WASCE 2.0.0/en/quick-start.html^{Image Removed}.1 or Geronimo 2.0.3 (see link above)1.1
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/^{Image Removed}

• At this stage, don't try to install and use Eclipse plugins. They are the moment I tested, Eclipse plugins where not working. They were 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 (for me for instance, on Windows it was C:\Program Files\IBM\WebSphere\AppServerCommunityEdition).
  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

  Code Block
  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

...

1. 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).

...

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

...

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.Note that system/manager are the defaut login/pwd coming with WASCE (and Geronimo). You may need to change them in appserver.properties. 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.

Beware that this module use the strings "/framework/", "/applications/", "/specialpurpose/" and "/hot-deploy/" to find location of files. So if you have a such string in your OFBiz path you will encouter an issue.
Also if you have developed some new applications you may have to adapt application.xml and geronimo-application.xml to suit your needs.

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

    Code Block
    geronimo run

    with the

    setenv and geronimo

    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

Derby

If you are using the embedded Derby database you should consider this.

• OFBiz creates 2 folders for the Derby Database under the runtime directory: ofbiz and ofbizolap, these contain all the setup data for OFBiz.
• If you run Geronimo, under your Geronimo bin directory you will see the 2 same directories. But those will not contain any data as you are not running OFBiz with the necessary parameters (you are running Geronimo, not OFBiz). Simply replace the 2 directories: ofbiz & ofbizolap in your Geronimo bin directory by the 2 directories from your OFBiz runtime 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.

...

In the simple case we need only one root (ofbiz.home) and only one classpath. 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 application 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 all 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 intance 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. Thanks for any help on the readonly root node issue ... (I'm not an xml specialist, I must confess) 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 exploded inside) more information on Geronimo ML.

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

This solution was developed by Les7arts as a consulting service for Iwoot