NOTE: this is the technical setup guide for OFBiz, for the business oriented one, look here.
Written by: David E. Jones With feedback and contributions from Ruth Hoffman, Andy Zeneski, Si Chen, Chris Chesney, Hans Bakker, and Al Byers
Sponsored by:
Integral Business Solutions (http://www.go-integral.com)
Hotwax Media, Inc (http://www.hotwaxmedia.com)
1. Check/install Java SDK (need 1.4 series full SDK, not just JRE)
2. Check/install SVN client
Expert Recommendation: If you intend to only install a binary release version of OFBiz you will not need the SVN client.
3. Check/install ant (1.6 or later)
1) If you intend to use a development version of OFBiz, follow the instructions on the Source Repository Info page to checkout the latest code or your desired stable branch
2) Build using "ant" in the ofbiz home directory (the directory where you installed OFBiz)
By default OFBiz includes and is configured for an embedded Java database called Derby. This database used to be called Cloudscape but was purchased by IBM, changed to be DB2 specification compliant, and then release as open source. This is a great database for demonstration, testing, development, and even small-scale production environments.
Expert Recommendation: We generally do not recommend the Derby database for production because it is not as easy to administer and optimize and will generally not perform as well as more substantial or native databases as Derby is a lighter weight Java database.
Expert Recommendation: There are many databases that OFBiz can use, both commercial and open source. While there are significant production instances of OFBiz running against Oracle, MS SQLServer, and so on, we generally recommend using an open source database such as Postgres or MySQL. The database to use is an important decision and may affect many things down the road. If you do not have a preferred database to use, we recommend discussing options with an experienced consultant before making a final decision.
In the: ${ofbiz install dir}/framework/entity/config/entityengine.xml file:
Modify an existing datasource (near the bottom of the file) or create a new one by copying one of the sample datasources already there and giving it a new unique name
Expert Recommendation: if you are using an external app server or want to setup more advanced Entity Engine configurations, see the Entity Engine Configuration Guide or other online documentation. The training videos from Undersun Consulting are highly recommend if you get into more advanced usage of OFBiz.
To load the seed data just use the OFBiz install routine through ant or directly with Java and the ofbiz.jar executable JAR file. By default the install routine will load the "seed" and "demo" sets of data files, as defined in the entityengine.xml file and in the ofbiz-component.xml file in each component. Run one of these two options from the command line in the ofbiz home directory to run the default install routine:
"ant run-install" or
"java -jar ofbiz.jar -install"
Note that you can choose to only load the basic "seed" data and not load the "demo" set of data files. To do this run something like:
"java -jar ofbiz.jar -install -readers=seed"
Expert Recommendation: For smaller installations we recommend loading the demo data and modifying it rather than creating all of the data from scratch.
For larger installations we recommend creating seed data files with your own settings, copied from the demo seed data, or simply creating all data from scratch. These can be added to the "ext" set of install data files, which is done by referencing those files in an ofbiz-component.xml file entity-resource tag with the attribute reader-name="ext". To load the "seed" and "ext" groups run something like:
"java -jar ofbiz.jar -install -readers=seed,ext"
The seed data includes a Party with ID "admin" and it has a number of UserLogin accounts associated with it that have varying permissions. Note the following configuration changes:
1. For production systems the passwords on all UserLogin accounts associated with the "admin" party should be changed from their default values.
2. The default password for the "admin" userLoginId is "ofbiz", as it is for the "flexadmin" and "demoadmin" accounts.
The "1" account is meant to be used with the POS system so the new password should include only numbers to make it easier to use with the POS client.
Expert Recommendation:While the "admin" party is the most critical to make sure the passwords are changed for, there are other parties you should check, and change the password for all User Login accounts associated with these parties. This includes "ltdadmin" and "externaluser" and if the demo data is loaded (done by default) then also the users "DemoBuyer", "DemoRepAll", and "DemoRepStore".
${ofbiz insall dir}/base/config/cache.properties
Fresh from SVN, this file is configured to be development friendly to reload resources frequently. For production use the expire times for the caches in the last section of the file should all be commented out by putting a pound sign "#" at the beginning of each line. The properties in question start with "minilang.", "script.", "webapp.", "widget." And "template.".
${ofbiz install dir}/base/config/debug.properties
This file is used to enable/disable different logging levels and used to configure Log4J logging level and output settings. For most production use it can stay as-is. Disabling the "info" and "timing" level properties can save some resources on the server, but we recommend leaving all of the others enabled. To do this just change the values of the "print.info" and "print.timing" properties to anything except "true".
${ofbiz install dir}/framework/security/config/security.properties
There are various settings you might want to configure in this file, but for most production use it can remain unchanged.
The following configuration files contain port configuration that may configured for custom OFBiz installations:
Choose a password to enter later when prompted. This same password will be used for the keystore password and for another question a bit later as the key password for.
1. Run: "keytool -genkey -keyalg RSA -alias ssl -keystore [keystore name]"
Go through and answer the following questions:
Enter keystore password: [password]
What is your first and last name?
[Unknown]: www.mydomain.com (example)
What is the name of your organizational unit?
[Unknown]: Undersun Testing (example)
What is the name of your organization?
[Unknown]: Undersun Testing (example)
What is the name of your City or Locality?
[Unknown]: New York (example)
What is the name of your State or Province?
[Unknown]: New York (example)
What is the two-letter country code for this unit?
[Unknown]: US (example)
Is CN=www.mydomain.com, OU=Undersun Testing, O=Undersun Testing, L=New York, ST=New York, C=US correct?
[no]: yes
Enter key password for
(RETURN if same as keystore password): [password]
2. Run: "keytool -certreq -alias ssl -keyalg RSA -file certreq.csr -keystore [keystore name]"
The following will be prompted/shown:
Enter keystore password: [password]
The CSR will be saved in the current directory: ----BEGIN NEW CERTIFICATE REQUEST--- and -----END NEW CERTIFICATE REQUEST----
3. Submit the CSR to a signing authority (Thawte, Verisign, etc)
4. Download your certificate from the signing authority. Please remember to download the Certificate in PKCS#7 format
5. Import the Certificate into the keystore by running:
"keytool -import -alias ssl -trustcacerts -file mysignedcert.cer -keystore [keystore name]"
6. Configure the ofbiz-containers.xml file to point to your new keystore and password:
Currency settings may be configured in the following configuration file:
${ofbiz install dir}/framework/common/config/general.properties
ß Default Currency Code (must exist in Uom table, three letter code, see seed data in the CurrencyData.xml file): currency.uom.id.default=USD
ß Default Country Code (must exist in Geo table, is three letter ISO country code, see seed data in the GeoData.xml file): country.geo.id.default=USA
ß Note that these settings can be overridden for a Store in the Edit Product Store page.
e-mail settings may be configured in the following, OFBiz file:
${ofbiz install dir}/framework/common/config/general.properties
ß SMTP Server (relay host): mail.smtp.relay.host
ß SMTP Username (if needed): mail.smtp.auth.user
ß SMTP Password (if needed): mail.smtp.auth.password
ß Turn on email notifications by setting the mail.notifications.enabled property to "Y".
It is often desirable to have one of the webapps mounted on the root. This is often either the ecommerce webapp or your own web site, which is created as a webapp in an OFBiz component would be setup the same way.
ß To set the mount point to root (or "/") for a webapp, find the corresponding "webapp" tag in the appropriate ofbiz-component.xml file and change the "mount-point" attribute on that tag to equal "/".
ß For the default OFBiz ecommerce webapp, this is found in the file:
${ofbiz install dir}/applications/ecommerce/ofbiz-component.xml
There are various ways to run OFBiz, and they all come down to some variation of the executing the "ofbiz.jar" executable JAR file. On the command line this can be as simple as:
"java -jar ofbiz.jar".
For production use you will want to setup a start script that contains special settings for things like memory heap size, and so on. There are example start and stop scripts in the root ofbiz directory in the startofbiz.sh and stopofbiz.sh files.
Expert Recommendation: Instead of running the startup and shutdown scripts manually it might be a good idea to set them up as services on the system, or use something like daemontools to make sure the process is restarted automatically if it goes down for some reason.
Expert Recommendation: While some steps can be taken at this point in the configuration process, the real performance testing and tuning should be done after you have setup your catalog, categories and products, and after you have customized any templates you plan to.
As mentioned above a critical part of performance tuning is turning off the expire times in the cache.properties by commenting out the lines near the bottom of that file that set those values.
General Cache Information
ß You can get a lot of good information on database and configuration file (XML, properties, etc) performance by looking at the statistics in the cache management page in Web Tools. They are all listed there with statistics about hits and misses, and about why cache misses happened.
ß There are three causes for cache misses:
1. Not Found
2. Soft Reference clearing (is done during garbage collection)
3. Expire Time reached for an entry in the cache
ß Memory Settings
If you are running into problems with Soft References (as seen on the cache management page in WebTools), the case is generally that your heap memory settings are less than ideal. Every time Java does a memory allocation and finds it needs to grow the heap size it first does a garbage collection and clears out soft references. The Entity Engine caches all use Soft References to avoid overrunning memory with cached database data.
In other words, you may have 2Gb of memory on the box, but you are probably only starting with 64Mb (or even less) and have a max heap of 128Mb. These are done with the following java command line arguments: -Xms64M for the low size, and -Xmx128M for the max size. We usually recommend a max heap size of around 75% of the memory on the box, but that depends on the operating system of course... The small size should be pretty high, perhaps even as high as the max, to avoid the caches being cannibalized during allocations and garbage collections as described above.
ß Database Intensive Operations
The comments above on memory settings, caches, etc. are for category browsing pages and such where just about everything should be cached. For db intensive operations, like the product searching, it's much better to focus on how the db is doing with the queries.
The Point-Of-Sale (POS) component in OFBiz is still maturing, but is a very flexible and capable enterprise class POS solution that features:
The POS system is designed to run with its own database in a totally stand-alone mode. This was done so that even if the machine is totally cutoff from the network it can still operate.
To run OFBiz in the POS "mode" just run: "java -jar ofbiz.jar -pos".
Note that this uses the pos-containers.xml file instead of the ofbiz-containers.xml file and by default it doesn't load a web container (ie Tomcat or Jetty), but that can certainly be added by changing that file.
The Store for the POS needs slightly different settings than for a web store.
There is an example POS Store in the demo data.
One of the differences to note is that the POS Store should always have the Is Immediately Fulfilled field set to Y, whereas for an online store or other mail or phone or store it should be set to N.
The POS Store should also have Manual Auth Is Capture set to Y, and typically Check Inventory and Require Inventory should be set to N.
There are many files under the ofbiz/applications/pos directory that you may want to customize as you set it up.
The receipt templates are .txt files in the config directory there.
The screens are configured through XUI in various files under the screens/default directory.
Button events are configured in the config/buttonevents.xml file.
There are example synchronization settings in the data/PosSyncSettings.xml file, which is just an Entity Engine seed data file that gets loaded into the database.
This example is for 3 tiers: a Main Central Server (MCS), a Per-Store Server (PSS) and the Point-Of-Sale client (POS). There are example sync settings to do 4 data moves including MCS -> PSS, PSS -> POS, POS -> PSS, and PSS -> MCS.
This uses the Entity Synchronization service in the Entity Engine and the XML import file for this has pretty good comments about what does what.
Note that the services shown in the example are configured to use the location "entity-sync-rmi" which is a pre-defined location specified in the serviceengine.xml file.
Note that to help avoid duplication of sequenced IDs in the data that is synchronized up the chain from the POS terminals a unique prefix should be setup for the Entity Engine using the sequenced-id-prefix attribute of the delegator element in the entityengine.xml file.