EUROPEAN COMMISSION
DIRECTORATE GENERAL
for INFORMATICS
IPM Open Source release
Installation guide
© European Community 2006 - Licensed under the EUPL V.1.0
http://ec.europa.eu/idabc/en/document/6523
IPM OSS – Installation Guide
-1-
18/04/2007
Document history
Date
20/05/2005
21/06/2005
17/11/2006
07/02/2006
18/04/2007
Author
Jean-Francois Levert
Frank Sikora
Christophe Volckaert
Jérôme Michel
Guillaume François
Description
Draft
Final
Update v2.1
Java 5 et Tomcat 5
Tomcat 5
Table of content
0. BACKGROUND INFORMATION
3
1. INTRODUCTION
3
2. INSTALLATION OF MYSQL 5
4
2.1
Post-installation procedure:
5
3. INSTALLATION OF J2SDK 1.5.0
8
4. INSTALLATION OF TOMCAT 5.5
8
5. INSTALLATION OF APACHE ANT 1.6.5
10
6. INSTALLATION OF IPM 2.1
10
7. ANNEX - CHARACTER SET ISSUE
13
IPM OSS – Installation Guide
-2-
18/04/2007
0. Background information
Interactive Policy Making (IPM) is a customisable web-based application developed
by the European Commission that aims to improve governance by using the Internet
to collect and analyse reactions of citizens and enterprises across the EU Member
States. Recently, the open source software version of IPM has been developed to
support the public administrations of the EU Member States. The development of
IPM has been done by the Commission’s Directorate General for Informatics under
the IDABC programme.
1. Introduction
The purpose of this document is to describe the steps you will have to perform in
order to install and run the Open Source package of IPM.
Like other web applications, the technical architecture of IPM is based on a database
server and a servlet container. A configuration using the MySQL database and the
application server Tomcat has been validated and fulfil all our requests.
You can access the following web sites for further information about these products:
http://dev.mysql.com/ and http://jakarta.apache.org/tomcat/ .
The IPM setup also needs the J2SDK 1.4.2 and ANT in order to build the war file to
be deployed.
This manual helps you in the installation of these components, assuming you have
some basic knowledge in the Unix/Linux environment and commands.
This procedure is based on the installation of IPM on a Linux plate-form with
the RedHat Enterprise Linux Application Server distribution. Nevertheless, it is not
the recommended configuration and then, if yours is a bit different, please refer to
the “on-line” documentation of each component.
System requirement for IPM installation:
 CPU: at least Pentium
 Minimum memory: 512Mb
 Minimum diskspace: 2Gb to be able to install all the components and
databases.
Here is, for information, the hardware configuration of our “test” machine:
 CPU: Intel(R) Xeon(TM) CPU 2.40GHz stepping 09
 Memory: 510 316 k / 523 712 k available
 Hard disk: SAMSUNG SP0411N, 78242976 sectors (40 060 MB) w/2048KiB
Recommendations:
 In order to perform the following steps, you have to log on the Linux server
with a user which has administrative rights (i.e. the “root” user and if you
are working in a shell, you can use the “su root” command, and then enter
the password).
 Pay attention to have a clean installation to avoid some conflicts with old
installations.
IPM OSS – Installation Guide
-3-
18/04/2007

The 'locale' setting of the Operating System must be set on UTF-8.7. Annex Character Set Issue)
2. Installation of MySQL 5
IPM v2.1 is certified with the most recent release MySQL 5.0.x Community Server
(Further CS).
It is recommended to install both MySQL Database server and client using the
RPM packages. These files are available at the following address:
http://www.mysql.org/downloads/mysql/5.0.html#downloads. Choose the right
packages regarding your plate-form (Linux) and the hardware you use (x86 or AMD
processor) and then, download them from a mirror by clicking “Pick a mirror”. In our
case, we downloaded the following rpm packages:
Afterwards, proceed to the installation of the rpm packages by running the following
command from the directory in which you just downloaded the files:
rpm –ivh MySQL-server-standard <version>.i386.rpm MySQL-client<version>.i386.rpm
<version>
has to be replaced by the current version. In this case, it should be
“5.0.27-0.rhel3”
You will perhaps get the following message:
error: Failed dependencies:
perl(DBI) is needed by MySQL-server-standard-5.0.27-0.rhel3.i386.rpm
Suggested resolutions:
perl-DBI-1.32-5.i386.rpm
In fact, MySQL Server requires Perl DBI. It is recommended to install the following
package: perl-DBI-1.32-5.i386.rpm (http://rpmfind.net/linux/RPM/redhat/9/i386/perl-DBI1.32-5.i386.html) with this command line:
rpm –ivh perl-DBI-1.32-5.i386.rpm
Then, run again the installation command of MySQL server and client.
IPM OSS – Installation Guide
-4-
18/04/2007
2.1
Post-installation procedure:
 Set the “root” password:
During the installation, the RPM server runs the script mysql_install_db, which
sets up the grant tables. This script creates a super-user account root, without
password, which is granted with full privileges. You should assign a password to
this account by running the following “bold” instructions:
[root@localhost bin]# mysqladmin -u root password "newpwd"
where ‘newpwd’ is the password you want to use.
You can test the installation by running the client: /usr/bin/mysql
enter the password you just set. Exit the client with this command:
–p
and then
mysql> exit
In this way, you check you can connect on the server with the client.
 Create the “ipm” user you will use to connect the database with the required
privileges:
First, you have to connect the MySQL client with user “root”:
[root@localhost bin]# mysql -u root -p
Enter password:
Then enter the password you just set up.
The way you are going to define the “ipm” user depends of the host from which
you want to connect to the database. If you plan to install IPM and MySQL on the
same machine, you must run the following command and specify the host like
this:
mysql> GRANT ALL PRIVILEGES ON *.* TO 'ipm'@'localhost.localdomain'
IDENTIFIED BY 'ipm' WITH GRANT OPTION;
But if you need to connect MySQL from another machine, i.e. if the machine on
which you installed MySQL is different from the machine you will install IPM,
run this command:
mysql> GRANT ALL PRIVILEGES ON *.* TO 'ipm'@'%' IDENTIFIED BY 'ipm' WITH
GRANT OPTION;
This will enable you to connect to MySQL server from any host other than
localhost.
IPM OSS – Installation Guide
-5-
18/04/2007
 Create the IPM database:
mysql> CREATE DATABASE ipm;
You can check the database exists:
mysql> use ipm;
You should then receive this message:
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A
Database changed
 Setting up the database:
Some global variables have to be changed on the MySQL server to run correctly
the IPM application. First you have to check the following variables by running
this command:
mysql> SHOW VARIABLES;
This will display the environment variables of MySQL, so check you have the
good value for the following variables:
+---------------------------------+---------------------------+
| Variable_name
| Value
|
+---------------------------------+---------------------------+
| lower_case_table_names
| 1
|
| max_allowed_packet
| 5242880
|
| tx_isolation
| READ-UNCOMMITTED
|
+---------------------------------+---------------------------+
If not, you can modify one of these values with this command:
mysql> SET GLOBAL Variable_name = Value;
If the command SET GLOBAL lower_case_table_names = 1 returns an error message,
you can init this variable in a configuration file:
Quit MySql:
mysql> exit;
Stop the MySql daemon that is in the basedir of your MySQL installation:
[root@localhost bin]# cd /usr/share/mysql/
[root@localhost mysql]# mysql.server stop
Shutting down MySQL.....
[ OK ]
Create the file my.cnf:
[root@localhost bin]# /etc/
[root@localhost etc]# vi my.cnf
IPM OSS – Installation Guide
-6-
18/04/2007
Fill this file with the content:
[mysqld]
set-variable=lower_case_table_names=1
innodb_buffer_pool_size=80M
innodb_log_file_size=5M
innodb_log_buffer_size=8M
innodb_flush_log_at_trx_commit=0
character-set-server=utf8
[mysql]
default-character-set=utf8
Restart the MySql daemon:
[root@localhost etc]# cd /usr/share/mysql/
[root@localhost mysql]# mysql.server start
Starting MySQL
[ OK ]
Reconnect to the MySql server:
[root@localhost mysql]# mysql -u root password "newpwd"
Check if the value has changed:
mysql> show variables like '%lower_case_t%';
+-------------------------------+-------+
| Variable_name
| Value |
+-------------------------------+-------+
| lower_case_table_names | 1
|
+-------------------------------+-------+
1 row in set (0.01 sec)
Concerning the transaction isolation level, the command is a bit different:
mysql> SET GLOBAL TRANSACTION ISOLATION LEVEL READ UNCOMMITTED;
Note that these values will be modified at the next MySQL session. It means
that if you run the “show variables” command, the old values remain. If you want
to affect the current session and only the current session, you have to run the “set
session” command.
Finally, you can exit the client:
mysql> exit;
IPM OSS – Installation Guide
-7-
18/04/2007
3. Installation of J2SDK 1.5.0
 Download the J2SE v5.0 SDK rpm in self-extracting file (of the current
release) corresponding to your plate-form (Linux or other) from the
java.sun.com website to any directory.
 Extract the content of the downloaded file.
From the directory in which you just downloaded the file, set the executable
permission and run the binary to extract the rpm package with the following
commands:
chmod a+x j2sdk-1_5_0_<version>-linux-i586-rpm.bin
./j2sdk-1_5_0_<version>-linux-i586-rpm.bin
<version>
has to be replaced by the current release of JDK. In this case, it should
be “09”
The script displays a license agreement, which you are asked to agree about. Then
the “unpacking” can proceed. The script creates the j2sdk-1_4_2_<version>linux-i586.rpm package in the current directory.
 Finally, run the rpm command and install the package:
rpm -iv j2sdk-1_5_0_<version>-linux-i586.rpm
This will install the JDK in the directory /usr/java/j2sdk1.4.2_<version>.
 Validation of the installation:
/usr/java/j2sdk1.5.0_<version>/bin/java –version
(to validate the installation)
This will return the following lines:
java version "1.5.0_09"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_09-b03)
Java HotSpot(TM) Client VM (build 1.5.0_09-b03, mixed mode, sharing)
4. Installation of TOMCAT 5.5
 Download the corresponding distribution:
The tar.gz binary distribution file is available at the following address:
http://tomcat.apache.org/download-55.cgi
 Run this command to unzip and install Tomcat 5.5:
tar -zxvf apache-tomcat-5.5.<version>.tar.gz –C /usr
<version> has to be replaced by the current version. In this case, it should be “20”
Tomcat will be extracted into the /usr directory.
IPM OSS – Installation Guide
-8-
18/04/2007
 Before starting Tomcat, set the JAVA_HOME variable:
The start-up script startup.sh uses the JAVA_HOME variable which points to the
installation directory of JDK. You can set this variable by editing the
Tomcat_Home/bin/catalina.sh script (where “Tomcat_home” is the “/usr/apachetomcat-5.5.20” directory is you installed Tomcat as expected in the step before)
using the vi editor:
[root@localhost bin]# vi /usr/apache-tomcat-5.5.20/bin/catalina.sh
and adding the following “bold” line:
…
#
#
JAVA_HOME
Must point at your Java Development Kit installation.
JAVA_HOME=/usr/java/j2sdk1.5.0_<version>
#
…
JAVA_OPTS
(Optional) Java runtime options used when the
where <version> corresponds to the current release of the JDK, “09” in our case.
vi is one of three standard editors on the Linux system. It is a screen-oriented
editor designed so that what you see on the screen corresponds exactly and
immediately to the contents of the file you are editing.
Most common vi edit commands you need to add a line in a file:
[i] to insert lines
[esc] to stop editing
[:][w] to save your changes
[:][q] to exit the editor
 Validation of the installation:
You can run tomcat and verify if the installation is ok:
[root@localhost bin]# /usr/apache-tomcat-5.5.20/bin/startup.sh
The following lines must appear:
…
Using
Using
Using
Using
…
CATALINA_BASE:
CATALINA_HOME:
CATALINA_TMPDIR:
JAVA_HOME:
/usr/ apache -tomcat-5.5.20
/usr/ apache -tomcat-5.5.20
/usr/ apache -tomcat-5.5.20/temp
/usr/java/j2sdk1.5.0_09
If you type the following URL in your internet browser, http://localhost:8080
(replace “localhost” with the IP address of your “application” server if you work
on a remote machine), the tomcat welcome page must appear.
To shutdown the server, run the script:
[root@localhost bin]# /usr/jakarta-tomcat-5.5.20/bin/shutdown.sh
At this step, it is better to shutdown the tomcat server because we will need to
restart it in order to fully deploy ipm.
IPM OSS – Installation Guide
-9-
18/04/2007
5. Installation of Apache ANT 1.6.5
ANT is a very useful and powerful tool, maintained by Apache, dedicated to
building source codes of web applications. The release 1.6.5 of ANT is required
to build the IPM “war” file.
Once created, this file will be deployed on the Tomcat application server.
 Download the apache-ant-1.6.5-bin.tar.gz distribution package from the
following location:
http://www.apache.org/dist/ant/binaries/
 “Untar” the package:
Run the following command from the directory in which you downloaded the
package:
tar -zxvf apache-ant-1.6.5-bin.tar.gz -C /usr
(Assuming you are installing “ant” in the /usr directory)
 Set up the environment:
In order to run ANT from any location, you just have to set up the path to the ant
tool in the PATH environment variable as followed:
export ANT_HOME=/usr/apache-ant-1.6.5
export PATH=${PATH}:${ANT_HOME}/bin
6. Installation of IPM 2.1
 STEP 1 – Getting the package ipm-oss-2.1.tar.gz
(to be defined)
 STEP 2 – Unzip the package
Run the following command from the directory in which you downloaded the
package assuming you want to unzip it in /usr/local:
tar –xzvf ipm-oss-2.1.tar.gz –C /usr/local
 STEP 3 – Static directory
Copy the static directory everywhere you want but not in Tomcat directories.
The link with this “structure” of directories will be set in the sitemap.xmap
configuration file (as explained further).
cp -fvr /usr/local/ipm-oss-2.1/static /usr
 STEP 4 – Configuration files
Before building the war file, some configuration files must be updated in order to
take in account the specificities of your installation:
IPM OSS – Installation Guide
-10-
18/04/2007
1. To redirect the Tomcat request to the right Cocoon sitemap (in the static
directory), you must define the following pipelines in the principal sitemap
file ($IPM_HOME/ipm-oss/sitemap.xmap where “IPM_HOME” is the directory
where you unzipped the ipm package) and modify it with the “bold” line as
shown hereafter:
To edit the file, use the “vi” editor as explained beforehand in the tomcat
installation chapter:
<map:pipeline>
<map:match pattern="*">
<map:mount check-reload="yes"
src="file:///usr/static/sitemap.xmap" uri-prefix=""/>
</map:match>
</map:pipeline>
<map:pipeline>
<map:match pattern="**">
<map:mount check-reload="yes"
src="file:///usr/static/sitemap.xmap" uri-prefix=""/>
</map:match>
</map:pipeline>
2. You must also configure the database on which you want to connect by
editing in the same way the cocoon.xconf file that you will find in the
$IPM_HOME/ipm-oss/WEB-INF directory:
<datasources>
…
<jdbc name="prod">
…
<dburl>jdbc:mysql://<IPaddress>/ipm?useUnicode=true&amp;charact
erEncoding=utf-8</dburl>
<user>ipm</user>
<password>ipm</password>
</jdbc>
…
<jdbc name="jobs_prod">
…
<dburl>jdbc:mysql://<IPaddress>/ipm?useUnicode=true&amp;charact
erEncoding=utf-8</dburl>
<user>ipm</user>
<password>ipm</password>
</jdbc>
…
</datasources>
The user and password are the ones you created during the post-procedure of the
installation of MySQL with the SQL statement “GRANT ALL PRIVILEGES ON *.* TO
'ipm'@'%' IDENTIFIED BY 'ipm' WITH GRANT OPTION;”
 STEP 5 – Archive .war file:
Build the war file by using ANT with the build.xml file available in the
distribution package. You must run this command from the ipm “root” directory
/usr/local/ipm-oss-2.1 (but first you must define the JAVA_HOME path used by ant):
[root@localhost ipm-oss-2.1]# export JAVA_HOME=/usr/java/j2sdk1.5.0_09
IPM OSS – Installation Guide
-11-
18/04/2007
[root@localhost ipm-oss-2.1]# ant –lib ./lib
Copy the ipm.war file from the location where you in the $TOMCAT_HOME/webapps
directory. That operation automatically deploy the application when you will start
Tomcat.
cp /usr/local/ipm-oss-2.1/ipm.war /usr/jakarta-tomcat-5.5.20/webapps
 STEP 6 – Launch Tomcat
Run this command to start Tomcat:
$TOMCAT_HOME/bin/startup.sh
(where $TOMCAT_HOME should be /usr/jakarta-tomcat-4.1.31 assuming you
respected the instructions of this manual)
Check if IPM files are available with the following URL:
http://localhost:8080/ipm/testipm.html.
Replace “localhost” by the IP address of your server if you try from a remote
computer
Your environment is now ready to use the IPM application. Log in the
application with the following URL:
http://localhost:8080/ipm/dispatch?access=secure.
The log in screen appears:
IPM OSS – Installation Guide
-12-
18/04/2007
Enter the “pre-defined” user:
User: IPM
Password: IPM
7. Annex - Character Set Issue
Warning: The 'locale' setting of the Operating System must be set on UTF-8. If
not, specific characters chould no be used by the application without issues. This
can be check using the “locale” command:
$ locale
LANG=en_US.UTF-8
LC_CTYPE="en_US.UTF-8"
LC_NUMERIC="en_US.UTF-8"
LC_TIME="en_US.UTF-8"
LC_COLLATE="en_US.UTF-8"
LC_MONETARY="en_US.UTF-8"
LC_MESSAGES="en_US.UTF-8"
LC_PAPER="en_US.UTF-8"
LC_NAME="en_US.UTF-8"
LC_ADDRESS="en_US.UTF-8"
LC_TELEPHONE="en_US.UTF-8"
LC_MEASUREMENT="en_US.UTF-8"
LC_IDENTIFICATION="en_US.UTF-8"
LC_ALL=
If this command exposes something like en_US. ISO-8859-15@euro, the
configuration has to be changed using this command “export” as:
~$export LANG= en_US.UTF-8
Note: Only the ‘UTF-8’ part is important, the ‘en_US’ part can be configured
according to your wishes like “ja_JP.UTF-8” or “de_DE.UTF-8”.
IPM OSS – Installation Guide
-13-
18/04/2007