ADempiere Dedicated Server
At first it should be pointed out that this tutorial highly resembles the one from Posterita. The system profile (OS and packages) is much alike. The difference is that here there are none graphical tools like pgAdmin III, so this tutorial mostly observes the differences. There are few but important tricky parts. They all follow.
If this tutorial appears old for you, check the Versions notes below.
Installing the server edition of Ubuntu 7.10
The Ubuntu servers which inherit Debian's stability and robustness are excellent environment for hosting enterprise class application systems. Except that a Ubuntu server is pretty easy and straightforward to install, having the appropriate CD.
See Install_on_Ubuntu_8.04 for the newest Ubuntu release.
The present version of Ubuntu Server is 7.10 (Gutsy Gibbon) which coincides with ADempiere 3.2.0 (May Day), Java 2 SDK 1.5.0 (for preference) and PostgreSQL 8.2 with pljava 1.3.0. Note that you may consider waiting till April, 2008. Then Ubuntu 8.04 (Hardy Heron) is planned to be released. This one will be LTS (Long Time Support) edition, which means whole 5 years of support for the server!
The good thing about this variant of the distro is the possibility of batch installation of a whole bunch of additional servers, including (wow, how convenient!) the PostgreSQL database server (version 8.2.5 - the one that's still pretty comfortable with the pljava). The set of additional servers is:
* DNS server - lets you provide and use the DNS (Domain Name System) service. * LAMP server - tool-chain for web developers, including Apache Web server, MySQL database server and PHP/Perl/Python programming languages. * Mail Server - managing electronic mail is always useful. * OpenSSH server - the free distribution of the server, which manages secure shell connections. * PostgreSQL Server - powerful and robust object-relational database server. * Print Server - manages the printers attached and the jobs assigned to them. * Samba file server - this one lets you have a seamless local network and file-sharing system along with Windows machines.
CAUTION! A very good suggestion is to miss out this Ubuntu version's Mail server (just skip it) or you might cause yourself the trouble of reinstalling it all again. For a mysterious reason (explained somewhere in the debris of the Ubuntu forums) installing this one leaves you sudo-less.
So already aboard Ubuntu server, few things have left to be set up.
First you have to take control over the database. Issue the commands:
/home/user$ sudo su /root$ passwd postgres
Now since you own the database's root user, the connection profile and other configurations must be done. Type at the prompt:
/root$ vim /etc/postgresql/8.2/main/pg_hba.conf
The lines where authentication method should be changed to trust are at the bottom of the file. Very good example is presented here.
Installing the pljava
There are generally two different ways of downloading pljava on the server machine:
1. Directly from terminal using the wget command:
/home/user$ sudo su /root$ cd /opt /opt$ wget http://www.posterita.org/share/pljava.zip /opt$ unzip pljava.zip -d /opt/
By default Ubuntu server comes without the zip and unzip tools, so you might have to get them first from the repository:
/home/user$ sudo apt-get install unzip
2. You may have a desktop machine around and download the pljava.zip archive from the Posterita site. The question now is how to put it on the server. There is a very useful command for secure copying files over a network - scp. Just open a terminal on the desktop machine and type (it is assumed you are in the directory where the archive file is downloaded):
user@desktop-machine$ scp pljava.zip server-user@server-machine:/home/user
You will be asked for the remote machine user's password. The server-user, server-machine should be replaced with the appropriate values. server-machine might be an ip address or a hostname depending on how you set up your network. Once copied, you may go back to the server machine and unzip the archive to the /opt/ folder.
After database is imported and loaded with pljava you may run the script which builds your application server. Of course you can't use RUN_setup.sh from the command line. If you want to use this one you should install X-Server and appropriate Window Manager, which step is not in the scope of this tutorial. In this case RUN_silentsetup.sh should be used, but not immediately. As a first step you should do:
$ cd $ADEMPIERE_HOME ADEMPIERE_HOME$ vim AdempiereEnvTemplate.properties
Here are the raw contents of this file:
#AdempiereEnv.properties Template #Adempiere home ADEMPIERE_HOME=/home/user/Adempiere #Java home JAVA_HOME=/usr/lib/jvm/jdk1.5.0_09 #Type of jvm, sun|mac|<ibm> ADEMPIERE_JAVA_TYPE=sun #Java runtime options ADEMPIERE_JAVA_OPTIONS=-Xms64M -Xmx512M #Type of database, postgresql|oracle|oracleXE|fyracle ADEMPIERE_DB_TYPE=postgresql #Database server host name ADEMPIERE_DB_SERVER=localhost #Database port, oracle, postgresql, fyracle ADEMPIERE_DB_PORT=5432 #Database name ADEMPIERE_DB_NAME=adempiere #Database system user password ADEMPIERE_DB_SYSTEM=postgres #Database user name ADEMPIERE_DB_USER=adempiere #Database user password ADEMPIERE_DB_PASSWORD=adempiere #Type of application server ADEMPIERE_APPS_TYPE=jboss #Application server host name ADEMPIERE_APPS_SERVER=localhost #Application server port ADEMPIERE_JNP_PORT=1099 ADEMPIERE_WEB_PORT=80 ADEMPIERE_SSL_PORT=443 #Keystore setting ADEMPIERE_KEYSTORE=/home/user/Adempiere/keystore/myKeystore ADEMPIERE_KEYSTOREWEBALIAS=adempiere ADEMPIERE_KEYSTORECODEALIAS=adempiere ADEMPIERE_KEYSTOREPASS=myPassword #Certificate details #Common name, default to host name ADEMPIERE_CERT_CN= #Organization, default to the user name ADEMPIERE_CERT_ORG=ADempiere Bazaar #Organization Unit, default to 'AdempiereUser' ADEMPIERE_CERT_ORG_UNIT=AdempiereUser #town ADEMPIERE_CERT_LOCATION=myTown #state ADEMPIERE_CERT_STATE= #2 character country code ADEMPIERE_CERT_COUNTRY= #Mail server setting ADEMPIERE_MAIL_SERVER=localhost ADEMPIERE_ADMIN_EMAILemail@example.com ADEMPIERE_MAIL_USER= ADEMPIERE_MAIL_PASSWORD= #ftp server setting ADEMPIERE_FTP_SERVER=localhost ADEMPIERE_FTP_PREFIX=my ADEMPIERE_FTP_USER=anonymous ADEMPIERE_FTP_PASSWORDfirstname.lastname@example.org
Here only the paths are changed from the original to Linux-like ones and some of the specially important variables are bolded. The word is about the Certificate details section. It is better to set any values to those variables, otherwise the build might complain and stop.
During every build/rebuild of ADempiere its binaries are unpacked and repacked again (to the according JARs, WARs, EARs). The process involves certifying the new packages. The certificate is kept into the directory identified with the ADEMPIERE_KEYSTORE variable and is being created during the initial install. This creation is done by the JDK's native keytool.exe which is being called automatically within the installation process. So you're obligated to do nothing more than to fill all the provided variables form the Keystore setting and Certificate details sections of the AdempiereEnv.properties file. If you're curious, further knowledge can be obtained through the keytool's page or take a look at this nice and exhaustive guide.
Don't forget the port variables either. Values like ADEMPIERE_WEB_PORT=8080 and ADEMPIERE_SSL_PORT=8443 are definitely safer. After editing it with the vim program you should save the file with the name AdempiereEnv.properties.
Now you may run the silent setup script and after successful build the server can be started:
ADEMPIERE_HOME$ sudo ./utils/RUN_Server2.sh
After the server is started, on any desktop machine on the same network open a browser and type in the address bar:
where server_address is the ip address or the hostname of the server machine and port is the port you defined by the ADEMPIERE_WEB_PORT variable in the AdempiereEnv.properties file. Your installation's ADempiere Home Page should be displayed. Here you have variety of choices to run the client application. One convenient way is to Web-Start ADempiere (through JNLP shortcut). It is not the fastest in the beginning but through it you're always up to date with the changes made on the server (if such a policy is chosen and applied) and you won't have to reinstall the client application every time a change is introduced.
Automate the administration
Very important matter in administrating servers is the ability to control them remotely and sometimes to make them independent of such conrol. The everyday tasks of backing up the database and not so frequent tasks as starting the application server at the machine's boot (especially when the administrator is not around) can make an essential difference.
JBoss startup through daemon at boot
At the $ADEMPIERE_HOME/utils/unix/ location in your installation you'll find several interesting scripts concerning the topic. serverStart.sh is the most important one. It is consistent with RedHat/Fedora like distributions which means that to work on Debianish distro like Ubuntu it have to be edited a little. Here are some necessary steps:
1. In Ubuntu the bash console's configuration file is called .bashrc instead of .bash_profile (line 21 - the ENVFILE variable).
2. Nevertheless Ubuntu's policy for using the root account will be an obstacle for the ENVFILE variable at a latter point, that's why I explicitly declare and initialize the ADEMPIERE_HOME variable for this script on the next line of the file.
3. The next thing in the script (line 23) is the introduction of the system functions needed. In Ubuntu they are elsewhere, so make the following change:
. /etc/init.d becomes . /lib/lsb/init-functions
4. On line 44 (when invoking the user responsible for starting the server as superuser) you must specify the correct user if you use a different one.
5. The upper change have to be made also on line 84, but there another thing have to be changed (the -S switch):
su adempiere -c "cd $EXECDIR/utils;$EXECDIR/utils/RUN_Server2Stop.sh &> /dev/null &" becomes su your_user -c "cd $EXECDIR/utils;$EXECDIR/utils/RUN_Server2Stop.sh -S &> /dev/null &"
so with this addition the script won't complain.
Now as the script is ready you may introduce it to the operating system. A few more steps are needed:
1. Copying the file into /etc/init.d generally makes it a daemon. Despite that this is not enough if you want it to start at boot time.
2. Shortcuts to this script into all directories representing the system's run-levels have to be put. This usually is made by a single command issued at the prompt as a super user:
$ update-rc.d /etc/init.d/serverStart.sh defaults
Of course you may have saved the file with a different name, which have to be put in the given command.
3. Another source of obstacles for the fluent startup is the ownership of the AppServer's logfile. Most often the owner is the root user and have to be changed to your user and its group:
ADEMPIERE_HOME$ cd jboss/server ADEMPIERE_HOME/jboss/server$ chown -R your_user adempiere ADEMPIERE_HOME/jboss/server$ chgrp -R your_user's_group adempiere
This should suffice and generally after rebooting the OS until you log on the application server should be already running. That might be checked with the client application, but the quicker way is with some commands on the console:
This command shows the system's process assigned to the JBoss server: $ ps aux | grep jboss This command queries the daemon itself on the server's status: $sudo /etc/init.d/serverStart.sh status
Let Ubuntu backup the database
Another script have to be written for that purpose. It is much smaller and should look like this:
#!/bin/sh # cd /home/adempiere/Adempiere/utils . ./RUN_DBExport.sh
Here you'll cd into where you installed ADempiere. Consequently you might extend the script with commands that copy the backup .jar file to a remote storage or in any fashion you feel comfortable with. The resulting script have to be copied exactly into the /usr/bin directory.
Now a cron job have to be scheduled - a system process that is executed at a predefined time pattern. At the console issue the command:
$ crontab -e
which lets you define the following line:
00 18 * * * /usr/bin/DBExport_script.sh
This definition tells the cron daemon to backup your database every day at 18:00. The first line of the file is self explanatory and there are many tutorials for the cron's time patterns, so anything can be done.
- OS/DB related: As of the end of April 2008, Ubuntu 8.04 has been released (the upper download link already points to the new version's medias). There are no differences in the installation of the Server OS. The new thing is the version of the PostgreSQL Database Server coming with the distribution - 8.3.1. At the time the version 1.4.0 of the pljava is present, which has been released for this higher version of the database server. They both work well together. At the same time the 3.4 version of ADempiere has already generated feedback for over a month.
- Application (JBoss) related: As of the 3.4.0 - Emily version the contents of the $ADEMPIERE_HOME/utils/unix/ directory are changed to be consistent not only with RedHat-like distributions but also with Debian-like ones. Here the script adempiere_Debian.sh is the important one. Most of the needed configurations are taken into account in it, but still on Ubuntu I need to edit it before deploying it:
- The ADEMPIERE_HOME variable needs to be initialized explicitly at the beginning.
- The '-S' switch needs to be provided to the RUN_Server2Stop.sh command in the stop() definition.
The rest of the deployment is as explained above.