Debian and PostgreSQL Install
Installing Adempiere from scratch can be tricky, and sometimes consume a lot of effort and time. This article is intended as a step-by-step guide for people not used to ERP concepts and terminology of how to get Adempiere up and running. It is based in my experience Adempiere version 3.2.0 (MayDay) in a Debian Etch GNU/Linux using PostgreSQL 8.1.8, the JVM from Sun Microsystems version 1.5.0 and pljava version 1.3.0.
The scope of this article is to explain and sequence, step by step, the phases and actions needed to get the software installed and running, until the first basic steps of Initial Client Setup, Business Partners and Products. Operating system concepts will not be explained and only the specifics of database administration that are needed for Adempiere are in scope. The OS chosen for this article is Linux (Debian Etch), and the Database, PostgreSQL, but most of the concepts will be generic enough to be applied to other configurations.
The expected audience is people with little or no ERP knowledge, but with knowledge of computer administration and some database administration, that need to perform the basic steps of software setup and configuration.
Please feel free to edit or add information to any part of this document. :)
In Debian, packages are always kept in the same version as they were when the distribution was released (speaking about Etch, in April 8th, 2007), so it tends to "age" with time. That is while closer to the last release date you tend to have all the versions needed for software that isn't kept in their package system, the older the release gets, the more you will need to get backports and other tricks to keep it up-to-date.
As Etch is just out of the oven, all the software need have compatible versions, so the only trick as of today is a little bug in PLjava that I will talk about in a moment.
First thing you have to be sure to include the non-free packages in your /etc/apt/sources.list, as there is where we will find the Sun Java VM.
Make sure you have the following line in your /etc/apt/sources.list:
deb http://http.us.debian.org/debian/ etch main contrib non-free
You can, and are encouraged to, substitute the http.us.debian.org with your preferred mirror.
Now make sure you have aptitude installed, as it has become the preferred package management tool in Etch:
apt-get install aptitude
Next step, install the Sun Java VM version 1.5.0:
aptitude install sun-java5-jdk
Read the disclaimer, the license and get to the next step, installing Postgresql-8.1
aptitude install postgresql-8.1
When aptitude finishes, you should have a functional postgresql database installed and running. Debian places the database in /var/lib/postgresql/8.1 the default database is named main and is located in /var/lib/postgresql/8.1/main. We assume in this guide that Adempiere's database will be created in the default cluster.
Next we need to install and run PLjava, the java backend for PostgreSQL. There is a bug (http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=390661) in the package shipping with Etch at this time (postgresql-8.1-pljava-gcj version 1.3.0-1+b1) that prevents the package from working at all. It is a simple dynamic library missing thing but yet will make the installation process fail. The work around is to get the source package Debian-way, make the changes and compile them yourself.
To get the source file you will need to add the following line to your /etc/apt/source.list:
deb-src http://http.us.debian.org/debian/ etch main contrib non-free
or use your preferred mirror.
Then I suggest changing directories to download the source. I particularly like having all my own compiled packages in /usr/local/src, so if you don't have that directory:
mkdir -p /usr/local/src cd /usr/local/src apt-get source postgresql-8.1-pljava-gcj
The next step is to change the Makefile to include the libjvm.so library. so:
cd postgresql-pljava-1.3.0/src/C/pljava vi Makefile
Now add the option -ljvm at the end of the 4 lines that begin with a SHLIB_LINK. And link libjvm to /usr/lib:
ln -s /usr/lib/jvm/java-1.5.0-sun/jre/lib/i386/server/libjvm.so /usr/lib/libjvm.so
Now you need to install the PostgreSQL development libraries:
aptitude install postgresql-server-dev-8.1
And export the JAVA_HOME environment variable:
And we are ready to compile and install pljava:
cd ../../.. make all make install
Once the procedure ends with no error, we should have a working PLjava, but we still need to configure PostgreSQL to use it. First we have to edit the postgresql.conf file to make it understand pljava commands, so edit /etc/postgresql/8.1/main/postgresql.conf and add the following lines to the end of the file:
custom_variable_classes = 'pljava' pljava.classpath='/usr/lib/postgresql/8.1/lib/pljava.jar' pljava.statement_cache_size = 10 pljava.release_lingering_savepoints = true pljava.vmoptions = ' ' pljava.debug = false
Now we must add the JAVA_HOME variable to the /etc/postgresql/8.1/main/environment so postgresql can find the java virtual machine:
JAVA_HOME = '/usr/lib/jvm/java-1.5.0-sun'
Next step will configure the whole "main" cluster to use pljava, installing it in the template1 database all the databases created subsenquentially will be pljava enabled.
We must now restart the postgresql server to active the changes in the configuration files:
Now we install pljava support in the main cluster with the following:
su postgres -c "export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun; \ /usr/lib/postgresql/8.1/bin/psql -d template1 \ -f /usr/local/src/postgresql-pljava-1.3.0/src/sql/install.sql"
With the previous line, every database created in this PostgreSQL server from that point on will be configured to use pljava in the backend.
--- BEGIN --- Added April 26, 2008 ---
The above step may give you errors that will repeat several times:
psql:/usr/local/src/postgresql-pljava-1.3.0/src/sql/install.sql:6: ERROR: could not load library "/usr/lib/postgresql/8.1/lib/pljava.so": /usr/lib/postgresql/8.1/lib/pljava.so: undefined symbol: SetUserId
psql:/usr/local/src/postgresql-pljava-1.3.0/src/sql/install.sql:55: ERROR: language "java" does not exist
If that's the case for you too, the following fixed for me:
1- Download pljava-src-1.4.0.tar.gz to /usr/local/src from http://pgfoundry.org/frs/?group_id=1000038&release_id=1024
2- Extract the files to /usr/local/src/pljava-1.4.0 (Trying to follow the steps/paths from the original author) by typing:
cd /usr/local/src tar zxvf pljava-src-1.4.0.tar.gz
3- Add -jvm to each line that start with SHLIB_LINK. (This may be unnecessary for this version, but I modified it before trying)
cd pljava-1.4.0/src/C/pljava vi Makefile
4- Type the following commands (some of them may be unnecessary):
cd /usr/local/src/pljava-1.4.0 make all make install /etc/init.d/postgresql-8.1 restart su postgres -c "export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun; \ /usr/lib/postgresql/8.1/bin/psql -d template1 \ -f /usr/local/src/pljava-1.4.0/src/sql/install.sql"
5- That should be it! You will get some "already exists" errors, but that will be OK because the first try worked partially.
--- END --- Added April 26, 2008 ---
Now we need to create a new user for Adempiere to run from I suggest creating the adempiere account:
You have to remember the password you used to create this user, you will need it later on.
Now we must enable this user we just created to access the database as the postgres user, which is the system user of the database and will be used by the RUN_ImportAdempiere.sh script to import the database data.
Add the following line to /etc/postgresql/8.1/main/pg_hba.conf:
host all postgres 127.0.0.1/32 md5 host all adempiere 127.0.0.1/32 md5
this lines will allow the RUN_ImportAdempiere.sh script to connect to the database as the postgres user IF the database is in the localhost, and subsenquentially allow the adempiere user (non system) to access from this same address.
Note: Running the database configured in localhost isn't probably what you want, as all the clients will need access to this database and the address you tell the script the database runs from will be remembered in the future (but it can be altered). So you should probably put you server external IP address (the address of the eth0 interface i.e.) instead of the 127.0.0.1 address of the previous line.
Now we need to change the password of the postgres user in the database, so the script can use it to import its data:
su postgres -c "psql --command \"ALTER USER postgres PASSWORD '<system_password>'\""
You should type in a strong password in <system_password>. This password will be used by the script only and you won't have to remember it after the configuration process is over.
At this point we have a running postgresql cluster in which all the newly created databases will support pljava as the backend.
From this point on all procedures should be executed as the "adempiere" user we created earlier, so:
su adempiere cd ~
So now it is time to download, de-tar and configure the client itself. Download the Adempiere_320.tar.gz file from the Download repository at http://sourceforge.net/project/showfiles.php?group_id=176962 and untar it:
tar zxvf Adempiere_320.tar.gz
That will create a directory called "Adempiere" in the home directory (by default /home/adempiere/Adempiere).
With the tarball open, it is time to setup the server. The setup script is graphical and uses X it might be better to login as the adempiere user itself in a X console. If you prefer to use your current user, you may try to issue the following command in a terminal to allow the script run as the adempiere user to connect to your X session:
Note: Please check the man page for the xhost command, as it can be a security problem if used incorrectly.
Using ssh to forward X session If you do not or can not use the xhost program, you can use ssh (provided that ssh server has been installed) to forward the X session request:
ssh -X -l adempiere localhost
In the "adempiere" account, we need to get the two environment variables Adempiere needs to run. Add the following line to /home/adempiere/.bashrc :
export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun export ADEMPIERE_HOME=/home/adempiere/Adempiere
Also run that two lines in the command prompt so you don't need to restart the shell.
export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun export ADEMPIERE_HOME=/home/adempiere/Adempiere
Then it is time to run the setup command: