Difference between revisions of "Installation Guide for ADempiere on IBM i"

Revision as of 21:38, 30 July 2008

Overview

This installation guide should be used for installing ADempiere on IBM I or i5/OS, the native operating systems of IBM Power Systems and System i. Either JBoss or WebSphere can be used as the application server, though performance testing has shown that WebSphere is faster and more reliable on installations that may require 50 or more concurrent users.

Limitations

• Posterita not supported
• WebStore not supported

Tested ADempiere versions

• 3.4.0

Prerequisites

• IBM Power System, System i or iSeries
• IBM i or i5/OS
• WebSphere Application Server 6.1.0.17 (on native partition)
• Two partitions setup – IBM i for Application Server and Linux for Database (SLES 10.1 recommended)
• Eclipse IDE for Java EE Developers (installed on Linux partition or separate machine with Linux or Windows)
• You must be able to log in as the administrator in both partitions (root in Linux, qsecofr in IBM i)

Linux Partition Setup

IBM Java installation

Sun does not support Power5 and Power6 processors, IBM Java is required instead. IBM-JAVA2-PPC64-SDK-5.0 can be downloaded from here. You will need to register with IBM if you have not already, which entitles you to free access to other software, white papers and red books.

Once you have downloaded the file you will need to install it with the following command:

 rpm –Uvh ibm-java2-ppc64-sdk-5.0-5.1.ppc64.rpm

Java should be be installed in a directory similar to /opt/ibm/java2-ppc64-50. This can be checked with the following command:

 /opt/ibm/java2-ppc64-50/bin/java -version

PostgreSQL

Ensure that your setup has the following packages installed as they are required for compiling PL/Java. If you are using SLES 10 this can be done though Software Management in Yast 2 (Control Center -> Software -> Software Management):

• GCC-JAVA - gcc-java 4.1.0-28.4 (Must install)
• C compiler run time library - libgcc
• 64bit C compiler runtime library - libgcc-64bit
• Java Runtime Library for GCJ - libgcj
• 64bit Java Runtime Library for GCJ - libgcj-64bit
• GCC Preprocessor - cpp

In Software Management, verify that the following packages are installed for the PostgreSQL DBMS:

• Postgresql-server
• Postgresql-dlevel
• Postgreslibs-64bit
• Postgresqllibs
• Postgresql-jdbc

If you are using a Linux distribution other than SLES 10, you may need to download and install PostgreSQL manually. If you are using SLES 10.1 but cannot find the required packages, you will need to add the following repositories to Yast 2:

 http://download.opensuse.org/distribution/SL-10.1/inst-source/
 http://download.opensuse.org/distribution/SL-10.1/non-oss-inst-source/

Once the files have been installed, start the PostgreSQL server with the following command:

 /etc/init.d/postgresql start

If it does not already exist, create a new user called postgres:

 createuser – P postgres

Change the password of postgres and switch to that user:

 passwd postgres
 su – postgres

Create a database user called adempiere in PostgreSQL and create the adempiere database by entering the following on the command line:

 psql
 CREATE USER adempiere WITH PASSWORD 'adempiere';
 ALTER USER adempiere WITH SUPERUSER;
 ALTER USER adempiere WITH LOGIN;
 CREATE DATABASE adempiere WITH OWNER adempiere ENCODING 'UTF8';
 \q

You will now need to compile and install PL/Java.

PL/Java

Make sure you are logged in as root and set the JAVA_HOME environment variable to the directory where java was installed, for example:

 export JAVA_HOME=/opt/ibm/java2-ppc64-50

Download the PL/Java source code, which is available from here

Save the archive to the /opt directory and then extract it:

 cd /opt
 tar zxfv pljava-1.3.0.tar.gz
 cd pljava-1.3.0

The following steps will compile pljava and build the required object files and jar files:

 make USE_GCJ=1
 mkdir -p /usr/share/pljava  
 install -m 644 build/pljava.jar /usr/share/pljava 
 install -m 644 build/deploy.jar /usr/share/pljava  
 install -m 755 build/objs/pljava.so /usr/share/pljava  
 cat > /etc/ld.so.conf.d/postgresql.conf <<EOF 
 $JAVA_HOME/jre/lib/ppc64
 $JAVA_HOME/jre/bin/classic
 $JAVA_HOME/jre/lib 
 $JAVA_HOME/jre/bin
 EOF  

If you prefer you can do this step manually by creating the /usr/share/pljava directory and manually copying over 'pljava.jar deploy.jar and pljava.so' and setting the required permissions with chmod. You will then need to create a postgres.conf file in /etc/ld.so.conf.d/postgresql.conf and add required java directories as listed above.

Rebuild the library list with:

 ldconfig

Ensure your 'libjvm.so' has been set with the following:

 ldconfig -p |grep libjvm.so

You should get something like: libjvm.so (libc6,64bit) => /opt/ibm/java2-ppc64-50/jre/bin/classic/libjvm.so. If the command returns nothing check the /etc/ld.so.conf.d/postgresql.conf file and verify that the directories are correct.

Modify postgresql.conf in /var/lib/pgsql/data (remember to uncomment #the lines): add these lines:

 custom_variable_classes = 'pljava' 
 pljava.classpath = '/usr/share/pljava/pljava.jar' 

Modify the following: listen_addresses = '*' # if you want to log in from the internet port = 5432

dynamic_library_path = '$libdir' to dynamic_library_path = '$libdir:/usr/share/pljava'

then modify pg_hba.conf in /var/lib/pgsql/data. The result will look something like this:

 # TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD #
 #local is for Unix domain socket connections only
 local   all         all                               trust 
 # IPv4 local connections:
 host    all         all         127.0.0.1/32          trust
 host    all         all         127.0.0.2/32          trust
 host    all         all         appserver/32          trust
 # IPv6 local connections:
 host    all         all         ::1/128               trust
 host    adempiere   adempiere   0.0.0.0/0             trust

Restart the postgreSQL server by running the following command:

 /etc/init.d/postgresql restart

(NOTE: You will need to restart the postgresql server every time you update the ph_hba.conf file for the changes to take effect)

Then install pljava into Database by running:

 java -cp /usr/share/pljava/deploy.jar:/usr/share/pgsql/postgresql-8.1-404.jdbc3.jar \
 org.postgresql.pljava.deploy.Deployer -install -user adempiere -database adempiere \
 -password adempiere

Database Table Setup

Download ADempiere and extract it to a temporary directory. Change to this directory and run the script:

 ./utils/RUN_ImportAdempiere.sh

All of the tables required for ADempiere will be generated via this script, which may take several minutes to complete.

The database should now be ready to communicate with the Application Server.

IBM i partition setup

Download ADempiere onto the Linux partition and decompress it using:

 gunzip Adempiere_340s.tar.gz

Transfer the archive to the native partition using ftp using binary mode:

 ftp <servername>
 cd /
 bin
 put Adempiere_340s.tar
 bye

Extract the archive using pax. Do NOT use tar as IBM I uses a different character set and the binary files will be corrupted:

 pax –r –C 819 –f Adempiere.tar

Export the JAVA_HOME and ADEMPIERE_HOME environment variables, make sure that JAVA_HOME points to version 1.5 of java:

 export ADEMPIERE_HOME=/Adempiere
 export JAVA_HOME=/QOpenSys/QIBM/ProdData/JavaVM/jdk50/32bit
 java –version

(NOTE: It is strongly recommended that you use use /Adempiere as your adempiere installation directory. Using other directories may result in problems that are difficult to fix otherwise.)

Copy the adempiere environment properties template into the adempiere environment properties file with the following command:

 cp AdempiereEnvTemplate.properties AdempiereEnv.properties

Edit the AdempiereEnv.properties file and make the following changes. You may need to ftp the file to the Linux partition and back in order to edit it:

 ADEMPIERE_HOME=/Adempiere
 JAVA_HOME=/ QOpenSys/QIBM/ProdData/JavaVM/jdk50/32bit
 ADEMPIERE_DB_SYS=adempiere
 ADEMPIERE_KEYSTORE=/Adempiere/keystore/myKeystore
 ADEMPIERE_KEYSTOREPASS=adempiere

Make a directory for the key store and generate a key for ADempiere using the IBM Java keytool, as follows:

 Mkdir keystore
 $JAVA_HOME/bin/keytool –genkey –keyalg rsa –alias adempiere –dname “CN=localhost, 
 OU=ADempiere Bazaar, O=AdempiereUser, L=Sydney, S=NSW, C=AU” –keypass adempiere 
 –validity 999 –keystore /Adempiere/keystore/myKeystore –storepass adempiere

Run the ADempiere setup with the following command:

 Chmod 744 RUN_silentsetup.sh
 RUN_silentsetup.sh

Once the installation has completed successfully you have the option of fixing JBoss or migrating to WebSphere Application Server.

Running JBoss

In order to run JBoss in IBM I a few configuration changes are necessary.

Edit the file (either natively or by transferring to another partition server with ftp) ADEMPIERE_HOME/jboss/server/adempiere/deploy/jbossweb-tomcat55.sar/server.xml. You will need to add the following argument to the tag below the comment :

 algorithm = IbmX509

Edit ADEMPIERE_HOME/utils/RUN_Server2.sh and remove the ‘-server’ options from JAVA_OPTS.

Migrating to WebSphere

Change the working directory to: ADEMPIERE_HOME\jboss\server\adempiere\deploy\adempiere.ear

Package the exploded ear into a compressed file using:

 jar cvfM adempiere.ear *

Use ftp to transfer the packaged ear file to the machine where you have Eclipse installed. Open eclipse and go to file -> import. Select J2EE -> ear file. Locate the compressed ear file and use all of the default settings. Do NOT select a target runtime. Click Finish.

Open up the application deployment descriptor (adempiere -> earContent -> META-INF -> application.xml) and make the following modifications:

• Add in a document type descriptor tag directly before the application tag:

 <!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN"
 "http://java.sun.com/j2ee/dtds/application_1_2.dtd">

• Remove all of the parameters from the application tag.
• Add the next two lines directly beneath the application tag if they are not already present

 <display-name>ADempiere</display-name>
 <description>ADempiere Applications</description>

• Remove the following lines completely from the file:

 <module>
   <java>AdempiereSLib.jar</java>
 </module>
 <module>
    <java>Adempiere.jar</java>
 </module>
 <module>
   <java>adempiereApps.jar</java>
 </module>

Find the module for adempiereWebCM.war and change the context root to home, as shown below:

 <module>
   <web>
     <web-uri>adempiereWebCM.war</web-uri>
     <context-root>/home</context-root>
   </web>
 </module>

• Remove the following completely from the file:

 <module>
   <web>
     <web-uri>posterita.war</web-uri>
     <context-root>/posterita</context-root>
   </web>
 </module>

Open up the deployment descriptor for adempiereApps.war (adempiereApps ->WebContent -> WEB-INF -> web.xml) and make the following modifications:

• Add in a document type definition tag directly before the web-app tag:

 <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">

• Remove all of the parameters from the web-app tag

Open up the manifest file for adempiereRoot.jar (adempierRoot_EJB -> ejbModule -> META-INF -> MANIFEST>MF and make the following modifications:

• Delete the following section:

 Name: META-INF/jaws.xml
 SHA1-Digest: vb2Dx67PF/Qhr9XGrx03Of8tjdw=

• Delete the following section:

 Name: META-INF/jboss.xml
 SHA1-Digest: FF5ayoXZ7BfYVDld/IMvvHqpvEg=

Delete the following files from the adempiereRoot_EJB -> ejbModule -> META-INF folder:

• jaws.xml
• jboss.xml

Open up the deployment descriptor for adempiereRoot.war (adempiereRoot_WEB ->WebContent -> WEB-INF -> web.xml) and make the following modifications:

• Add in a document type definition tag directly before the web-app tag:

 <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">

• Remove all of the parameters from the web-app tag

Open up the deployment descriptor for adempiereWebCM.war (adempiereWebCM ->WebContent -> WEB-INF -> web.xml) and make the following modifications:

• Add in a document type definition tag directly before the web-app tag:

 <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">

• Remove all of the parameters from the web-app tag
• Swap the order of the <mime-mapping> and the <welcome-file-list> tags

Open up the deployment descriptor for adempiereWebStore (adempiereWebStore ->WebContent -> WEB-INF -> web.xml) and make the following modifications:

• Add in a document type definition tag directly before the web-app tag:

 <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">

• Remove all of the parameters from the web-app tag
• Move the mime-mapping tag to above the welcome-file-list tag
• Delete the Posterita project, including its contents, from the solution.
• Right Click on the Adempiere Project and select Export -> Ear File. Choose a directory and click finish.

Open up your web browser from the machine with new ear. Go to the WebSphere Administration Console and follow these steps to install the ear into the application server:

• Go to Enterprise Applications -> Install New Application
• Browse for the ear file that was exported from Eclipse and click next
• Accept the installation options and click Next
• Select all of the modules to be mapped to the server by ticking all of the boxes and click next.
• Provide the JNDI names as adempiere/Status and adempiere/Server respectively and click next.
• Specify the target resource JNDIs as adempiere/Status, adempiere/StatusLocal, adempiere/Status and adempiere/ServerLocal and click next.
• Accept the default configuration for Map virtual hosts for Web modules by clicking next.
• A summary will be displayed, click finish.