Info | ||
---|---|---|
| ||
This page documents the usage with Gradle, the pre-Gradle documentation is here: Apache OFBiz Technical Production Setup Guide This page documents the trunk version, the documentation for the R16.11 version is here: Apache OFBiz Technical Production Setup Guide |
NOTE: this is the technical setup guide for OFBiz, for the business oriented one, look here.
...
1) If you intend to use a development version of OFBiz, please follow the instructions on the Source Repository page to checkout the latest code or the stable branch that you require.
2) Build using "[./]ant gradlew" (add "./" on *nix systems, to use the embedded ant which is in sync with your OFBiz versionGradle which comes with its wrapper, hence gradlew and not gradle in the command). Do this from the ofbiz home directory (i.e. the directory where you installed OFBiz)
Database Setup
. Note: you can get more information about Gradle task using "gradlew tasks".
Database Setup
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. This is mainly because Derby is a lightweight 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 using Oracle, MS SQLServer, and so on, we generally recommend using an open source database such as Postgres or MySQL. Which database to use is an important decision and may have a future impacts on your implementation. If you do not have a preferred database choice then we strongly recommend discussing options with an experienced consultant before making a final decision.
- If you decide not to use the embedded Derby database, check/install your database of choice. See below for some information that may help with using or installing OFBiz with alternative databases
Changing from Derby to MySQL Database
OFBiz and Oracle
Connecting OFBiz to PostGIS spatially enabled database
Switching from a Derby database to another - If necessary, put the correct JDBC driver in the following directory:
- ${ofbiz install dir}/framework/entity/lib/jdbc (NOTE: You can use "ant download-PG-JDBC" to download the last postgres jdbc driver or " ant download-mySQL-JDBC" to download the last mySQL jdbc driver)
- Replace the old or incorrect version of the driver (i.e. copy in with same name to avoid problems with update restoring the old driver later)
- To setup the Entity Engine to use a different database from the default Derby database.
In the: ${ofbiz install dir}/framework/entity/config/entityengine.xml file:
- Modify the "localpostgres" (or "localmysql", etc.) datasources elements to connect to your database.
- Modify the "default" delegator element:
Change
<group-map group-name="org.apache.ofbiz" datasource-name="localpostgreslocalderby"/>
to
<group-map group-name="org.apache.ofbiz" datasource-name="localpostgreslocalpostgres"/> The OLAP and Tenant data sources will still use Derby. If you want to change those to use PostgreSQL also, then:
Modify the "localpostgresolap" datasource element to connect to your OLAP database.
Modify the "localpostgrestenant" datasource element to connect to your Tenant database.
Modify the "default" delegator element:
Change
<group-map group-name="org.apache.ofbiz.olap" datasource-name="localderbyolap"/>
to
<group-map group-name="org.apache.ofbiz.olap" datasource-name="localpostgresolap"/>
Change
<group-map group-name="org.apache.ofbiz.tenant" datasource-name="localderbytenant"/>
to
<group-map group-name="org.apache.ofbiz.tenant" datasource-name="localpostgrestenant"/>- 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
- If using the default OFBiz transaction manager and connection pool then update the data URI, username and password in the inline-jdbc tag
- If you want your OFBiz tables in a special schema you will first need to create that schema in your database and then set the schema-name attribute on the datasource tag
- Find the "default" delegator near the top of the file and change the datasource-name attribute value in the group-map tag under it to the name of the data source you modified or created.
Expert Recommendation: if you are using an external application 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.
Initial Data Loading
To load the initial data just use the OFBiz install routine through ant gradlew or directly with Java and the build/libs/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 the following two options from the command line in the ofbiz home directory to run the default install routine:
Code Block |
---|
[./]ant load-demo (ant run-install in no longer used in supported releases) gradlew loadAll (add "./" on *nix systems, to use the embedded antGradle which is incomes sync with yourits OFBiz version) Note: you can get more information about Ant targets using ant -p |
or
Code Block |
---|
java -jar ofbizwrapper, hence gradlew and not gradle in the command). Do this from the ofbiz home directory (i.e. the directory where you installed OFBiz). Note: you can get more information about Gradle task using "gradlew tasks". or java -jar build/libs/ofbiz.jar --load-data |
Help can be obtained by by the following command:
Code Block |
---|
gradlew "ofbiz -help" or java -jar build/libs/ofbiz.jar ? |
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:
Code Block |
---|
gradlew "ofbiz --load-data readers=seed,seed-initial" or java -jar build/libs/ofbiz.jar --load-data readers=seed,seed-initial |
Definition: Seed Data is data that an application requires in order to run. It is created and maintained along with the code and should be loaded into the database when the code is updated. It should not be changed or removed in the application database without first having done so in the Seed Data XML files. In OFBiz these are the source of the Seed Data and they are maintained in the code repository along with the code. Add in components should do the same for this sort of data.
Definition: Seed Initial Data is data that is only required the first time the system is loaded like the password of the admin user. Later if you want to update the seed data, you would normally not want the password of admin to be set back to 'ofbiz'.
Expert Recommendation: For smaller installations we recommend loading the demo data and modifying it through the OFBiz applications rather than creating all of the data from scratch.
...
To load the "seed" and "ext" groups run something like:
Code Block |
---|
javagradlew -jar "ofbiz.jar --load-data readers=seed,ext" |
or the special ant target:
Code Block |
---|
[./]ant load-extseed (ant run-install-extseed in no longer supported releases) (add "./" on *nix systems, to use the embedded ant which is in sync with your OFBiz version) or java -jar build/libs/ofbiz.jar --load-data readers=seed,ext |
The OFBiz demo data includes a Party with ID "admin" and it has a number of UserLogin accounts associated with it that have varying permissions.
...
- For production systems the passwords on all UserLogin accounts associated with the "admin" party should be changed from their default values.
- The default password for the "admin" userLoginId is "ofbiz" which is also the same 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.
...
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 hashtag sign "#" at the beginning of each line. The properties in question start with "minilang.", "script.", "webapp.", "widget." And "template.".
...
Info |
---|
Log4J is the engine used by OFBiz to manage its log output. The releases 13.07.*, 12.04.*, 11.04.*, 10.04.* use Log4J 1 (the configuration file is named log4j.xml) while newer releases are bundled with Log4j2 (the configuration file is named log4j2.xml). For information about advanced configuration of Log4j refer to: |
Security Settings
${ofbiz install dir}/framework/security/config/security.properties
...
If you want the entire authentication process to fail if LDAP authentication fails, then set the security.ldap.fail.login property in ${ofbiz install dir}/framework/security/config/security.properties to true. Only users who are in the LDAP directory will be able to use OFBiz. This would be appropriate for installations that use only the back office (manager) applications.
Info | ||
---|---|---|
| ||
Be sure to always check the Keeping OFBiz secure page for possible vulnerabilites |
URL and Port Settings
The following configuration files contain port configuration configurations that may configured for custom OFBiz installations:.
You may also use the global portoffset Java properties. Use "gradlew "ofbiz ?" or "java -jar build/libs/ofbiz.jar -h" to know more about this option.
- $${ofbiz install dir}/framework/base/config/ofbiz-containers.xml (The Containers Configuration File)
- ${ofbiz install dir}/framework/webapp/config/url.properties (The URL Properties File)
- Deprecated in recent versions:
Sometimes other container configuration files are used, but are generally in that same directory and will be specified in the start properties file used (see start.properties, pos.properties, install.properties, etc) - The commented out BSH client (the last container in the file) should generally be disabled or at least protected by a firewall for production deployments. Otherwise this is a significant security risk.
- These properties are used to configure the settings to send to the client browser. The port and host settings may be different than the port and host settings of the local machine if it is running through Apache through AJP, through any proxy, or through a load balancer of any sort. The settings in this file should be set to what the client browser will see when communicating with your system.
- Note that the settings in this file can be overridden on the WebSite record with the ID specified by the webSiteId field in the web.xml file in each webapp, if applicable. These can be viewed and modified in the WebSites tab of the Content Manager applicationNote that if an external application server is used instead of the embedded Tomcat or Jetty servers then many things normally configured here will be configured in the setup files for the external application server.
- Deprecated in recent versions:
- ${ofbiz install dir}/framework/webappbase/config/urljndiservers.properties (The URL Properties xml (JNDI Servers XML File)
- These properties are used to configure the settings to send to the client browser. The port and host settings may be different than the port and host settings of the local machine if it is running through Apache through AJP, through any proxy, or through a load balancer of any sort. The settings in this file should be set to what the client browser will see when communicating with your system.
- Note that the settings in this file can be overridden on the WebSite record with the ID specified by the webSiteId field in the web.xml file in each webapp, if applicable. These can be viewed and modified in the WebSites tab of the Content Manager application.
- ${ofbiz install dir}/framework/base/config/jndiservers.xml (JNDI Servers XML File)
- Generally only the "default" server is used which has automatic configuration through the Java standard JNDI facility, so no changes are needed for most production deployments in this file.
- Generally only the "default" server is used which has automatic configuration through the Java standard JNDI facility, so no changes are needed for most production deployments in this file.
- ${ofbiz install dir}/framework/base/config/jndi.properties (JNDI Properties file)
- This is a standard Java JNDI configuration
- This is a standard Java JNDI configuration properties file and is used to configure the local JNDI server to be used. Note that this is how the "default" JNDI server in the JNDI Servers XML File is configured. If this file is not present the Java standard JNDI classes will use various defaults instead.
...
- To ease development (Out Of The Box, OFBiz is configured in development mode) the compressHTML properties in general.properties if OFF. If you prefer to strip unnecessary whitespace from HTML output you can set it on ON (uncomment the line "#compress.HTML=true"). Note that non html output screens like for example tab delimited exports can be then messed up. Note also that , it is NOT the same thing as gzipped HTTP 1.1 compression.
- For the same reason (development mode) the line "widget.verbose=true" is uncommented. If you do not want to see any informations about widget boundaries in the generated HTLM code, you should comment this line.
Ports, Default Values
- HTTP Admin Port - 808010523
- Configured in: ofbiz-containers XML start.properties File
- Referenced in: Config.java File
- HTTP - 8080
- Configured in: ofbiz-containers XML File
- Referenced in: Service Service Engine XML File, Client Browser (if running direct), URL Properties File
- HTTPS - 8443
- Configured in: ofbiz-containers XML File
- Referenced in: Client Browser (if running direct)
- AJP13 - 8009
- Configured in: ofbiz-containers XML File
- Referenced in: Apache mod_jk plugin configuration
- JRMP (JNDI, RMI, etc) - 1099
- Configured in: Carol Properties (carol.jrmp.url)
- Referenced in: Containers XML File, JNDI Properties File, Service Engine XML File
- BSH Client - 9989, 9990 (this should generally be disabled or at least protected by a firewall)
- Configured in: ofbiz-containers XML File
- Multicast ports - 45564, etc. (Tomcat clustering)
- Configured in: ofbiz-containers XML File
...
"keytool -import -alias ssl -trustcacerts -file mysignedcert.cer -keystore [keystore name]"
6. Configure the the framework\catalina\ofbiz-containerscomponent.xml file to point to your new keystore and password:
...
If you are having trouble getting OFBiz to connect to your mail server, try disabling your anti-virus software (temporarily) as it may block attempts to send emails from unknown applications because it thinks they are being sent by a virus.
Another possible issue is the presence in database of SystemProperty data that could overload general.properties configuration. Be sure to check the absence of mail property in SystemProperty table.
Mounting a Root WebApp
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.
...
There are various ways to run OFBiz, and they all come down to some variation of the executing the "build/libs/ofbiz.jar" executable JAR file.
On the command line this can be as simple as (but beware you might need to pass specific JVM arguments, like "-server" if you develop on Windows, see
Jira | ||||||
---|---|---|---|---|---|---|
|
Code Block |
---|
gradlew ofbiz or java -jar build/libs/ofbiz.jar |
or through ant:
Code Block |
---|
[./]ant start
(add "./" on *nix systems, to use the embedded ant which is in sync with your OFBiz version) |
To access the To access the application from your browser follow advice given in the Demo and Test Setup Guide
...
To run all automated tests use the following command:
Code Block |
---|
gradlew testIntegration or java -jar build/libs/ofbiz.jar --testt |
To run just the tests for one component run something like (for the entity component):
Code Block |
---|
javagradlew "ofbiz -jar -test component=entity" or java -jar build/libs/ofbiz.jar --test component=entity |
Performance Monitoring and Tuning
...
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. Last recent versions (say since R10.04) require more permanent generation space (also know as perm gen space). For instance in the trunk demo server we currently (16 May 2010) use 512 MB of perm gen space. And our memory parameters are -Xms128M -Xmx1024M -XX:MaxPermSize=512m.
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 database intensive operations, like the product searching, it's much better to focus on how the database is managing with the queries.
POS Setup Process
Info | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
With The last released version with the POS available was R12.04.06. It's though still available in the R14.12 and 15.12 non released branches. It'll not be availble with the R16 release. All the documentation below is reliable and usable before revision 1754402 |
The Point-Of-Sale (POS) component in OFBiz was maturing, it was already a very flexible and capable enterprise class POS solution that features:
- templated receipts
- XML file configurable screens
- jPOS hardware support
- multi-tiered synchronization of product, price, promotion, party, order, and other data related to POS deployment and operation
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. It can also be used with a shared database, for instance if you want to run a webstore simultaneously using the same stock. You could even use the same machine to run both (ERP&eCommerce + POS) using the -both parameter (see below.)
To run OFBiz in the POS "mode" just run:
Code Block |
---|
java -jar ofbiz.jar --pos
|
or currently on Windows use startofbizPos.
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 (Tomcat by default), but you may also run the command below which uses the both-containers.xml allowing to run the POS concurrently with Web eCommerce and Back Office.
Code Block |
---|
java -jar ofbiz.jar --both
|
or currently on Windows use startofbizBoth.
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 store types (e.g. mail, phone etc) 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 specialpurpose/pos directory that you may want to customize as you set it up.
- The receipt templates stored as .txt files in the config directory there.
- The screens are configured through XUI in various files under the screens/default directory. There is a default set for 1024x768 screen (in default directory), and a 800x600 preset. (NOTE: To use 800x600, you must modify 3 properties in xpos.properties : StartClass, ClientWidth and ClientHeight, but don't touch the other parameters...)
- Button events are configured in the config/buttonevents.xml file.
- The POS is translatable, see the config directory and for more the OFBiz-POS page
You may want to change some default options following your needs.
- In the parameters.properties file
- By default the POS uses a virtual alphanum keyboard and a virtual numeric pad. If you prefer to use a real keyboard, change the ShowKeyboardInSaveSale parameter. (Note: You may even swap dynamically back and forth from the Admin Panel using "Virtual" button. But then the parameter will not persist.)
- There is a related special parameter SwipWithCard which is, for now, used only to swipe card numbers using an MSR in the Client Profile dialog box (Promo Panel, Client Profile button). There are also sentinel parameters for setting MSR types.
- If you use an external system for credit card payments then you may find it convenient to use the PosRefNum parameter which allows you makes entering payments references optional (i.e. so you dont have to enter them)
- In pos-containers.xml and both-containers.xml (depending if you use one or the other)
- xui-session-id : the POS terminal identifier (used during synchronisation for instance)
- facility-id : related to the name you set for your facility on the ERP side
- look-and-feel : see http://www.jgoodies.com/
- In xui.properties (in framework/guiapp/config)
- # isSameLogin : if equals "true" (false by default), a logged off user (blocked, time out, ...) can only log in with the same login/pwd.
- There are also some technicals barcode scanning related parameters in jpos.properties
The localisation is done dynamically using the platform default. But it needs a 1st launch to be set (it dynamically changes the XUI's xpos.properties file). So in order to switch from a language to an other you have to load the POS twice It also takes care of possible font issues. But for now only for Chinese (it uses posstyles_zh.xml).
You may override this behavior (for instance to test) using
- The languageSuffix parameter in the xui.properties file. This has an influence on the labels from XuiLabels.properties files.
- Forcing the JVM language using "-Duser.language=zh -Duser.country=CN" from the command line. This has an influence on the labels from PosUiLabels.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.
Note that OOTB the login/pwd are 1/1 (or 2/2 for a non manager person) and you must open the register before being able to play with the POS.
To open the register
- Click on the MGR button on the top and near the right
- and then on the "Open" button on the right side of the screen near the top.
If you need to do some JavaPOS settings you may find this page interesting
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. Last recent versions (say since R10.04) require more permanent generation space (also know as perm gen space). For instance in the trunk demo server we currently (16 May 2010) use 512 MB of perm gen space. And our memory parameters are -Xms128M -Xmx1024M -XX:MaxPermSize=512m.
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 database intensive operations, like the product searching, it's much better to focus on how the database is managing with the queries.If you need more informations see the OFBiz-POS page