EUROPEAN COMMISSION

DIRECTORATE GENERAL
for INFORMATICS

CIRCABC Open Source release

Installation guide

© European Community 2008 - Licensed under the EUPL V.2.0

http://ec.europa.eu/idabc/eupl

CIRCABC OSS – Installation Guide -1- 24/10/2008

Document history
Date Author Description
04/03/07 Yanick Pignot Draft
24/10/08 Pascal Monfils Draft

Table of contents

1 BACKGROUND INFORMATION...................................................................3

2 INTRODUCTION............................................................................................4

3 INSTALLATION OF MYSQL 5......................................................................6

3.1 Post-installation procedure:.....................................................................................................6

4 INSTALLATION OF J2SDK 1.5.....................................................................9

5 INSTALLATION OF TOMCAT 5.5...............................................................10

6 PREPARE THE FILE SYSTEM...................................................................12

7 INSTALLATION OF CIRCABC 3.2.1...........................................................14

7.1 Get the required files...............................................................................................................14

7.2 Install CIRCABC....................................................................................................................15

7.3 Configure CIRCABC to be running in your environment..................................................16

7.4 Install the new configuration..................................................................................................22

7.5 Run CIRCABC........................................................................................................................22

8 Annex - Character Set Issue....................................................................27

CIRCABC OSS – Installation Guide -2- 24/10/2008

Background information

CIRCABC (Communication and Information Resource Centre for Administrations,

Businesses and Citizens) project is the continuation of CIRCA project.

CIRCA system has been in service throughout IDA & IDA II (horizontal measure)
and is in production since 1997. It provides Interest Groups with a private web
workspace to collaborate on common objectives and tasks. The current application is
available for Member States administrations and the service has been continually
improved.

The legal reference of CIRCABC project is IDABC (Interoperable Delivery of

European eGovernment Services to public Administrations, Businesses and Citizens)
programme Decision 2004/387/EC, Article 5, paragraph 2 and Annex II, section B,
point (p).

CIRCABC OSS – Installation Guide -3- 24/10/2008

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 CIRCABC. This package
contains two archives:
1. circabc2.0-oss-src.tar.gz: which contains all the sources code to develop new
enhancement of CIRCABC.
2. circabc2.0-oss-bin.tar.gz: which contains all you need to install CIRCABC on
you own server. Only this archive is covered in this document.
Like other web applications, the technical architecture of CIRCABC 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 simplified (from CIRCABC binaries distribution) CIRCABC setup also needs
Alfresco© and the J2SDK 1.5 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 CIRCABC on a Linux platform

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.

Since CIRCABC is an application developed on top of Alfresco open source

platform, if you need help on specific environment or specific configuration, you
can visit theses links:
- http://wiki.alfresco.com/wiki/Category:Installation.
- http://wiki.alfresco.com/wiki/Server_Configuration

System requirement for CIRCABC installation (indicative recommendations):

 For 50 concurrent or up to 500 casual users:

1GB JVM RAM
2x server CPU (or 1xDual-core)
 For 100 concurrent users or up to 1000 casual users:
1GB JVM RAM
4x server CPU (or 2xDual-core)
 For 200 concurrent users or up to 2000 casual users:
2GB JVM RAM

CIRCABC OSS – Installation Guide -4- 24/10/2008

 8x server CPU (or 4xDual-core)

And at least 8 Gb of free space on the hard drive. But It depends on the number of
documents CIRCABC should deal with.

Here is, for information, the hardware configuration of our “test” machine:
 CPU: Intel® Xeon™ CPU 2.40GHz stepping 09
 Memory: 3990 Mo / 8086 Mo with swap
 Free Hard disk: 9 Gb

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 conflicts with old
installations.
 The 'locale' setting of the Operating System must be set on UTF-8 at the end
of the installation procedure (see point 8 Annex - Character Set Issue)

CIRCABC OSS – Installation Guide -5- 24/10/2008

Installation of MySQL 5

The reference manual of MySQL 5 is available at:

http://dev.mysql.com/doc/refman/5.1/en/

It is recommended to install both MySQL Database server and client using the
RPM packages. These files are available at the following address:
http://dev.mysql.com/downloads/mysql/5.1.html. Choose the right packages regarding
your plat-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.1.20-0.rhel3”

Perhaps you will get the following message:

error: Failed dependencies:
perl(DBI) is needed by MySQL-server-standard-5.1.20-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-DBI-
1.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.

3.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

CIRCABC OSS – Installation Guide -6- 24/10/2008

 password, which is granted with full privileges. You should assign a password to
this account by running the following “bold” instructions:
[root@localhost]# 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 –p and then
enter the password you just set. Exit the client with this command:
mysql> exit
In this way, you check you can connect on the server with the client.

 Connect to mysql as root user:

First, you have to connect the MySQL client with user “root”:
[root@localhost]# mysql -u root -p
Enter password:

Then enter the password you just set up.

 Create the “circabc” database you will use:

Now, you have to create the database that the application will use. In our example
the created database is named 'circabc'. Further we will indicate how to use
another database name.
mysql> create database circabc;

You can check whether the database exists:

mysql> use circabc;

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

Configuration tips:
As seen later, the database name can be different and must be configured in the
"circa-repository.properties" using the "db.name" key

 Create the “circabc” user you will use to connect the database with the
required privileges:

The way you are going to define the “circabc” user depends on the host from
which you want to connect to the database. If you plan to install CIRCABC and
MySQL on the same machine, you must run the following command and specify
the host like this:
mysql> grant all on circabc.* to 'circabc'@'localhost' identified by '
circabc' with grant option;

CIRCABC OSS – Installation Guide -7- 24/10/2008

 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
CIRCABC on, run this command:
mysql> GRANT ALL PRIVILEGES ON *.* TO 'circabc'@'%' IDENTIFIED BY
'circabc' WITH GRANT OPTION;

This will enable you to connect to MySQL server from any host other than
localhost. You can restrict the access to only one server by replacing '%' by the
address of the server on which CIRCABC is running.

Configuration tips:
As seen later, the database username and password can be different and must
be configured in the "circa-repository.properties" respectively using the
"db.username" and "db.password" keys

Finally, you can exit the client:

mysql> exit;

CIRCABC OSS – Installation Guide -8- 24/10/2008

Installation of J2SDK 1.5

1. Download the J2SE v5.0  SDK rpm in the self-extracting file (of the current
release) corresponding to your platform (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 (2008-
03-04), it should be “13”

The script displays a licence agreement, which you are asked to agree about. Then
the “unpacking” can proceed. The script creates the j2sdk-1_5_0_<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.5.0_<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_13"

Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_13-bxx)
Java HotSpot(TM) Client VM (build 1.5.0_13-bxx, mixed mode, sharing)

CIRCABC OSS – Installation Guide -9- 24/10/2008

Installation of TOMCAT 6

 Download the corresponding distribution:

The tar.gz binary distribution file is available at the following address:

 http://apache.mogo.be/tomcat/tomcat-6/v6.0.33/bin/apache-tomcat-
6.0.33.tar.gz

 Run this command to unzip and install Tomcat 6:

tar -zxvf apache-tomcat-6.0.<version>.tar.gz –C /usr

<version> has to be replaced by the current version.

Tomcat will be extracted into the /usr directory.

 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/apache-
tomcat-5.5.26” directory where Tomcat is installed as expected in the step before).

Furthermore, it is important to configure some parameters (ie. the memory to use)

that must be sent to the JVM whenever Tomcat starts up via the JAVA_OPTS
variable. Otherwise, the application will not be running correctly.

We edit the file through the vi editor:

[root@localhost]# vi /usr/apache-tomcat-6.0.<version>/bin/catalina.sh

and add 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
JAVA_OPTS="-server -Xms1024m -Xmx1024m -XX:MaxPermSize=128m -XX:
+DisableExplicitGC -Djava.io.tmpdir=/usr/env/circabc/temp"

where <version> corresponds to the current release of the JDK, “13” in our case.
and where /usr/env/circabc/temp can point to a different directory if
configured differently (see next section).

The JVM options can vary with your device's performance. These values,
however, match a wide range of configurations.

vi is one of three standard editors on the Linux system. It is a screen-oriented

editor designed so that the content of the file you are editing is displayed, exactly
and immediately.

CIRCABC OSS – Installation Guide -10- 24/10/2008

 Most common vi edit commands required for adding 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:

Now you run tomcat and verify whether the installation is ok:
[root@localhost]# /usr/apache-tomcat-5.5.<version>/bin/startup.sh

The following lines must appear:

…
Using CATALINA_BASE: /usr/ apache -tomcat-6.0.33
Using CATALINA_HOME: /usr/ apache -tomcat-6.0.33
Using CATALINA_TMPDIR: /usr/ apache -tomcat-6.0.33/temp
Using JAVA_HOME: /usr/java/j2sdk1.5.0_13
…

The tomcat welcome page must appear once you have keyed the URL
http://localhost:8080 in your internet browser, (replace “localhost” with the
IP address of your “application” server if you work on a remote machine).

To shutdown the server, run the script below:

[root@localhost]# /usr/jakarta-tomcat-6.0.33/bin/shutdown.sh

At this step, it is better to shut down the tomcat server because we will have to
restart it in order to fully deploy CIRCABC.

CIRCABC OSS – Installation Guide -11- 24/10/2008

Prepare the file system

 Create ALF_DATA:

The documents and indexes will be stored on the server file system, not in the
database.. The directory, in which CIRACBC will work, is usually named
"ALF_DATA" The user who launches, if other than root, must have all rights on it.

To create this directory, run this command:

[root@localhost]# mkdir –p /usr/env/circabc/alf_data

Configuration tips:
As seen later, the ALF_DATA directory path can be different and must be
configured in the "circa-repository.properties" file using the "dir.root" key.

 Create TEMP_DIR:

By default, CIRCABC uses the system temporary directory, but it is not a good idea
to keep this behaviour. If several instances of CIRCABC run on the same server, with
different users, the access to this folder will be troubled. It is due to each instance to
create its own sub directory (with the same name):
 The first stated instance is the owner.
 The second instance, which views that the sub directory is already
created, uses it but has not enough right to write in it.

[root@localhost]# mkdir /usr/env/circabc/temp

Configuration tips:
As seen in a previous section, the temporary directory path can be different and
must be configured in the "catalina.sh" file using the "Djava.io.tmpdir" key.

 Create log directories:

The CIRCABC log files will be written under this specified directory.
[root@localhost]# mkdir /usr/env/circabc/logs/

Configuration tips:
As seen later, the created log files directory path can be different and must be
configured in the "log4j.properties" file using the "log4j.appender.File.File" key.

Since the Tomcat logging is uneasy to change, you can create a symbolic link to see it
in the same directory:
[root@localhost]# ln -s /usr/apache-tomcat-6.0.33/logs /usr/env/circabc/logs/tomcat

<version> has to be replaced by the current version. In this case (2008-03-04), it

should be “26”
 Specify user rights if needed:

CIRCABC OSS – Installation Guide -12- 24/10/2008

If the user who starts Tomcat is not root or is not the owner of theses three directories,
you must allow him full right on it. You must launch:

[root@localhost]# chown -R <user>:<group> /usr/env/circabc

<user> has to be replaced by the user name in charge to launch tomcat

<group> the group in which the user is granted.

CIRCABC OSS – Installation Guide -13- 24/10/2008

Installation of CIRCABC 3.4

CIRCABC binaries distribution is provided as a set of AMP files (or Alfresco Module
Package).

An AMP file (or Alfresco Module Package) is a collection of code, XML,

images, CSS, etc. that collectively extend the functionality or data provided by the
standard Alfresco repository. An AMP file has a standard format.

In the CIRCABC binaries distribution you can see two of amp package:
1. "circabc.amp": All the CIRCABC specific features and default configuration.
The installation doesn't require modifying this file.
2. "config.amp": It is the only one package you should modify to set up
CIRCABC to run on your specific environment. This AMP cannot be installed
if circabc.amp has not been previously installed too.

The installation is done via the Alfresco Module Management Tool. It consists of a
simple mapping between the Alfresco war archive and an AMP. If the AMP file
structure is respected, the MMT will add the new specific files by overriding existing
ones if required.

For more information about AMP please visit:

 http://wiki.alfresco.com/wiki/AMP_Files
 http://wiki.alfresco.com/wiki/Module_Management_Tool

7.1 Get the required files

Now, you will preferably work in your home directory:

[root@localhost]# cd ~

 STEP 1 – Getting the package circabc3.4-oss-bin.tar.gz

To download this file, go to the "Files" section of the OSOR page of CIRCABC:
http://forge.osor.eu/projects/circabc/

 STEP 2 – Unzip the package

[root@localhost]# tar -zxvf circabc3.4-oss-bin.tar.gz

You should see the list of extracted files:

endorsed/
EUPL 1.0 LICENSE DE.pdf
EUPL 1.0 LICENSE EN.pdf
EUPL 1.0 LICENSE FR.pdf
circabc.amp
config.amp
endorsed/cmu_time_awb.jar
...

CIRCABC OSS – Installation Guide -14- 24/10/2008

  STEP 3 – Getting alfresco application

You must download the open source release of Alfresco from the download page
of the sourceforge
To provide the stable functionality of Alfresco, CIRCABC 2.0 OSS is running on
the Alfresco Labs 3Stable release of Alfresco community edition. At this address
you should be able to find the files named:
 alfresco-labs-war-3Stable.tar.gz:
http://sourceforge.net/projects/alfresco/files/Alfresco/Alfresco
%20Labs%203%20Final/alfresco-labs-war-3Stable.tar.gz/download
 alfresco-mmt-
3Stable.jar:http://sourceforge.net/projects/alfresco/files/Alfresco/Alfres
co%20Labs%203%20Final/alfresco-mmt-3Stable.jar/download

For your information:

In the download pages, you can find alfresco extension distributed under AMP
files. The installation of these files is similar to the installation of the CIRCABC
AMP, but we have not tested it.

For your information:

Another interesting file provided is the Alfresco SDK. It provides the sources and a
development environment to contribute to the Alfresco development. This file is not
required to install CIRCABC.

 STEP 4 – Extract the alfresco.war

In the archive alfresco-labs-war-3Stable.tar.gz, we only need one file, the

alfresco.war web archive that contains the application. To extract it, type the
command:

[root@localhost]# tar -zxvf alfresco-labs-war-3Stable.tar.gz alfresco.war

You should only see this extracted file:

alfresco.war

7.2 Install CIRCABC

 STEP 5 – Apply the CIRCABC AMP

Previously, we downloaded the file alfresco-mmt-3Stable.jar that is the

application provided by Alfresco to install an AMP inside the alfresco.war. To
do that, you simply run the command:
[root@localhost]# /usr/java/jdk1.5.0_<version>/bin/java -jar alfresco-mmt-3Stable.jar install
circabc.amp alfresco.war -nobackup -force -verbose

<version> has to be replaced by the current release of JDK. In this case (2008-
03-04), it should be “13”

CIRCABC OSS – Installation Guide -15- 24/10/2008

 Due to the optional verbose parameter, you should see a long list of added files:
...
- Directory '/jsp/extension' added to war
- File '/css/extension/help.css' added to war from amp
- File '/css/extension/d-commission.css' added to war from amp
- File '/css/extension/circabc.css' added to war from amp
- File '/css/extension/circabc-counter-ipm.css' added to war from amp
...

The package must be adapted to your specific environment yet, but at this time,
we consider that CIRCABC is installed. You can now rename the application:

[root@localhost]# mv alfresco.war circabc.war

 STEP 6 – Move dependencies

CIRCABC, to run correctly, needs some libraries to be loaded by Tomcat before

the application starts. All of these libraries are located in the "Endorsed" folder
and must be moved under Tomcat by running this command:

[root@localhost]# cp endorsed/* /usr/apache-tomcat-6.0.<version>/common/endorsed

<version> has to be replaced by the current version.

7.3 Configure CIRCABC to be running in your environment

Now, we will configure CIRCABC to take in account the specificities of your

environment. CIRCABC, to make the installation as simple and faster as possible,
provides a second AMP that erases the default configuration.

We describe below how to adapt the common properties to most environment

configurations. If yours ever needs to be most finely tuned, please refer to:
 the Alfresco Wiki: http://wiki.alfresco.com
 or the Alfresco forums: http://forums.alfresco.com/

Conceptually, the config.amp archive contains all common files to modify. These
modified files erase the existing ones in circabc.war.

For example, you wish to modify the web.xml file, located in circabc.war/WEB-
INF/web.xml. You can modify the existing config.amp/web/WEB-INF/ web.xml before
running the Module Management Tool.

Another example to illustrate how to modify the behaviour of the CIRCABC web
client: you consider that users cannot change their own password.

A. You extract the circa-web-client-config-actions.xml file with the command:

[root@localhost]# unzip circabc.amp *circa-web-client-config-actions.xml

You should see:

inflating: web/WEB-INF/classes/alfresco/extension/circa-web-client-config-actions.xml

CIRCABC OSS – Installation Guide -16- 24/10/2008

B. As seen before, you can open the extracting file with vi:

[root@localhost]# vi web/WEB-INF/classes/alfresco/extension/circa-web-client-config-actions.xml

C. Modify this bold line:

...
<!-- Actions for manage my account WAI Page -->
<action-group id="user_account_actions_WAI">
<action idref="change_own_password_WAI" hide="true"/>
</action-group>
...

D. Now you update config.amp by running:

[root@localhost]# zip -0 config.amp web/WEB-INF/classes/alfresco/extension/circa-web-client-

config-actions.xml

You should see:

updating: web/WEB-INF/classes/alfresco/extension/circa-web-client-config-actions.xml (stored 0%)

For more details, please refer to the Alfresco Wiki:

 http://wiki.alfresco.com/wiki/Web_Client_Configuration_Guide
 http://wiki.alfresco.com/wiki/Web_Client_Customisation_Guide

 STEP 7 – Configure your server Context

Due to some user actions, CIRCABC sends an email specifying the URL of the
application (i.e. any user, when applying for membership to the application,
receives an email which contains the URL of the activation page). Unfortunately,
in a clustering environment, CIRCABC is unable to reconstitute the main external
URL.

A. Extract circa-settings.properties:

[root@localhost]# unzip config.amp *circabc-settings.properties

You should see:

Archive: config.amp
extracting: web/WEB-INF/classes/alfresco/extension/config/circabc-settings.properties

B. Modify the web.root.url key

[root@localhost]# vi web/WEB-INF/classes/alfresco/extension/config/circabc-settings.properties

...
# Web root url
web.root.url=http://circabcserver:8080/circabc

CIRCABC OSS – Installation Guide -17- 24/10/2008

 ...

C. Update the AMP:

[root@localhost]# zip -0 config.amp web/WEB-INF/classes/alfresco/extension/config/circabc-

settings.properties

You should see:

updating: web/WEB-INF/classes/alfresco/extension/config/circa-settings.properties (stored 0%)

You can skip the next steps if your environment matches exactly the description
made in this document

 STEP 8 – Configure your database

The CIRCABC database configuration is defined in circabc-repository.properties

and overrides the original Alfresco file: repository.properties.

A. Extract circa-repository.properties:

[root@localhost]# unzip config.amp *circabc-repository.properties

You should see:

Archive: config.amp
extracting: web/WEB-INF/classes/alfresco/extension/config/circabc-repository.properties

B. If needed, modify the keys:

[root@localhost]# vi web/WEB-INF/classes/alfresco/extension/config/circabc-
repository.properties

Configure the database driver:

...
db.driver=org.gjt.mm.mysql.Driver
...

Configure the database name:

...
db.name=circabc
...

Configure the database url:

...
db.url=jdbc:mysql://localhost:3306/${db.name}
...

Configure the database user name and password:

...
db.username=circabc

CIRCABC OSS – Installation Guide -18- 24/10/2008

 db.password=circabc
...

Alternatively, you can provide a name for your database with JNDI:
...
db.jndiName=jdbc/circabcDB
...

C. Update the AMP:

[root@localhost]# zip -0 config.amp web/WEB-INF/classes/alfresco/extension/config/circabc-

repository.properties

You should see:

updating: web/WEB-INF/classes/alfresco/extension/config/circabc-repository.properties (stored 0%)

For more details on the database configuration, please refer to:

 http://wiki.alfresco.com/wiki/Database_Configuration

 STEP 9 – Configure another dialect

The CIRCABC database management layer is managed via Hibernate, a

Persistence Framework. Such tool offers mainly an abstraction layer between the
database and the application. It means that – theoretically – you have just to
change the dialect used in the circa-hibernate-cfg.properties file to enable
CIRCABC to run over any database managed by Hibernate.

If you use MySql, please pass to the next step. The example describe below
suppose that you use an Oracle Database.

A. Extract circa-hibernate-cfg.properties:

[root@localhost]# unzip config.amp *circabc-hibernate-cfg.properties

You should see:

Archive: config.amp
extracting: web/WEB-INF/classes/alfresco/extension/domain/circabc-hibernate-cfg.properties

B. Specify the dialect to use:

[root@localhost]# vi web/WEB-INF/classes/alfresco/extension/config/circabc-hibernate-
cfg.properties

Comment the MySql dialect call

...
#
# MySQL dialect
#
# hibernate.dialect=org.hibernate.dialect.MySQLInnoDBDialect
...

CIRCABC OSS – Installation Guide -19- 24/10/2008

 Uncomment the target database manager (i.e. Oracle)
...
#
# Oracle dialect
#
hibernate.dialect=org.hibernate.dialect.Oracle9Dialect
...

C. Update the AMP:

[root@localhost]# zip -0 config.amp web/WEB-INF/classes/alfresco/extension/domain/circabc-

hibernate-cfg.properties

You should see:

updating: web/WEB-INF/classes/alfresco/extension/domain/circabc-hibernate-cfg.properties
(stored 0%)

For more detail, please refer to:

 http://www.hibernate.org/hib_docs/reference/en/html/index.html

 STEP 10 – Configure your ALF_DATA

The configuration of the ALF_DATA, like the configuration of the database, is

located in the circa-repository.properties. As previously seen, the ALF_DATA is
the folder in which CIRCABC stores the files and indexes. The user who launches
Tomcat must have full rights on it.

A. Extract circa-repository.properties:

[root@localhost]# unzip config.amp *circabc-repository.properties

You should see:

Archive: config.amp
extracting: web/WEB-INF/classes/alfresco/extension/config/circabc-repository.properties

B. Modify the dir.root key:

[root@localhost]# vi web/WEB-INF/classes/alfresco/extension/config/circabc-
repository.properties

...
dir.root=/usr/env/circabc/alf_data
...

C. Update the AMP:

[root@localhost]# zip -0 config.amp web/WEB-INF/classes/alfresco/extension/config/circabc-

repository.properties

You should see:

CIRCABC OSS – Installation Guide -20- 24/10/2008

 updating: web/WEB-INF/classes/alfresco/extension/config/circabc-repository.properties (stored 0%)

 STEP 11 – Configure your log files directory

The logging of CIRCABC is managed by Log4j that is a configurable logging

framework. It is quite simple to configure it: you just have to adjust properties in
log4j.properties.

A. Extract circa-repository.properties:

[root@localhost]# unzip config.amp *log4j.properties

You should see:

Archive: config.amp
extracting: web/WEB-INF/classes/log4j.properties

B. If needed, modify the property keys:

[root@localhost]# vi web/WEB-INF/classes/log4j.properties

To modify the log file name and path:

...
log4j.appender.File.File=/usr/env/circabc/logs/circabc.log
...

[Good idea] To see all what happens during the bootstrap of the application, add
these bold lines at the end of the file:
...
###### Log level overrides #######
log4j.logger.org.alfresco.repo.importer.ImporterBootstrap=info
log4j.logger.org.alfresco.repo.domain.schema.SchemaBootstrap=info
log4j.logger.org.alfresco.repo.admin.ConfigurationChecker=info
log4j.logger.org.alfresco.repo.node.index.FullIndexRecoveryComponent=info

[Bad idea] To see all what happens inside Hibernate:

...
###### Log level overrides #######
...
log4j.logger.org.hibernate =info

Add lines carefully in this file to avoid the resulting log file to be huge,
unreadable and resource-eating. For example, an info logging level for Hibernate
can add thousand lines per minute and use too many resources to run CIRCABC
normally. Moreover the real error will be hidden in this big stream of log.

C. Update the AMP:

[root@localhost]# zip -0 config.amp web/WEB-INF/classes/log4j.properties

You should see:

CIRCABC OSS – Installation Guide -21- 24/10/2008

 updating: web/WEB-INF/classes/log4j.properties (stored 0%)

For more detail, please refer to:

 http://logging.apache.org/log4j

7.4 Install the new configuration

 STEP 12 – Apply config.amp

To install your custom properties and behaviour, you can apply the config.amp as
simply as previously shown (refer to the applying circabc.amp to alfresco.war):
[root@localhost]# /usr/java/jdk1.5.0_<version>/bin/java -jar alfresco-mmt-3b.jar install
config.amp circabc.war -nobackup -force -verbose

<version> has to be replaced by the current release of JDK. In this case (2008-
03-04), it should be “13”

Due to the optional verbose parameter, you should see the following warnings:
...
- WARNING: The file '/WEB-INF/classes/alfresco/extension/domain/circa-hibernate-cfg.properties'
is being updated by this module and has been backed-up to '/WEB-INF/classes/alfresco/module/
backup/0e6ff2e8-eada-11dc-96b8-971ab11437ba.bin'
- WARNING: The file '/WEB-INF/web.xml' is being updated by this module and has been backed-up
to '/WEB-INF/classes/alfresco/module/backup/0e704109-eada-11dc-96b8-971ab11437ba.bin'
...

You will perhaps get the following message:

Installing AMP 'config.amp' into WAR 'circabc.war'
The following modules must first be installed: [circabcAmp:*]
Module managment tool available commands:

In fact, this message appears because you try to install config.amp before having
circabc.amp.

7.5 Run CIRCABC

 STEP 13 – Copy CIRCABC

Copy the circabc.war file into the $TOMCAT_HOME/webapps directory. This operation
automatically deploys the application as you start Tomcat.
[root@localhost]# cp circabc.war /usr/apache-tomcat-5.5.<version>/webapps

 STEP 14 – Launch Tomcat

Run this command to start Tomcat:

[root@localhost]# /usr/apache-tomcat-5.5.<version>/bin/startup.sh

Wait a few minutes while CIRCABC creates the database schema and prepares
data and indexes in ALF_DATA.

CIRCABC OSS – Installation Guide -22- 24/10/2008

 If Circabc is not running successfully after the first start

Sometimes, when you shutdown Tomcat, the 'java' process can still be running.
In this case, the restarting of CIRCABC can be problematic and this error will
appear in the log file:
. . .
Caused by: java.rmi.AlreadyBoundException: alfresco/jmxrmi
. . .

Run these commands:

[root@localhost]# /usr/apache-tomcat-5.5.<version>/bin/shutdown.sh
[root@localhost]# ps -A | grep java

If no line is displayed, you can pass to the next step.

If this line appear (this line will a little bit different of you server. Only the last
term must be display 'java'.)
20505 ? 00:57:53 java
[root@localhost]# kill – 9 20505

20505 must replaced by your own process id (the first term of the list).

If Circabc is not running successfully after the first start

There could be an error triggered by Alfresco's persistence layer preventing the

application to start. It would look like this :
. . .
ERROR [org.apache.catalina.core.ContainerBase.[Catalina].[localhost].
[/alfresco]]:3733 Exception sending context initialized event to
listener instance of class
org.springframework.web.context.ContextLoaderListener
org.alfresco.error.AlfrescoRuntimeException: Not all patches could be
applied
. . .

If this error was triggered, simply shutdown and restart the Tomcat server.
During the next start, the missing patches should be applied successfully and the
application started.

 STEP 15 – Test the welcome page

Check if the CIRCABC welcome page is accessible through the following URL:

http://localhost:8080/circabc

“localhost” has to be replaced by the IP address of your server if you try from a
remote computer.

CIRCABC OSS – Installation Guide -23- 24/10/2008

 You should see:

Figure 1: The CIRCABC welcome page

At this time, CIRCABC is empty and no CIRCABC user is created. You can
connect to the Alfresco web client by entering this URL in your internet browser:

http://localhost:8080/circabc/faces/jsp/login.jsp

“localhost” has to be replaced by the IP address of your server if you try from a
remote computer.

Figure 2: the alfresco login page

If the login page is not displayed as illustrated above:

Due to security issues, the cookies of your browser may be corrupted so that the
expected result is reached by pasting two (rarely three) times the alfresco login
page URL.

CIRCABC OSS – Installation Guide -24- 24/10/2008

 Then, enter this connection values:

User Name: admin

Password: admin

Congratulation! CIRCABC is running fine. To use and configure the CIRCABC

application, please refer to the guides provided with this document.

 STEP 16 – Read the log files

Now, let us take a look to the CIRCABC log file. Some errors may appear but do
not care. These errors do not disturb the application. They might prevent you, for
instance, from managing image transformation, ftp … through the CIRCABC
capabilities.

For more details, please refer to

 eitherthe Alfresco Wiki: http://wiki.alfresco.com
 or the Alfresco forums: http://forums.alfresco.com/

Theses messages could appear without disturbing CIRCABC:

05 Mar 2008 18:30:38,430 ERROR
[org.alfresco.repo.content.transform.magick.AbstractImageMagickContentTr
ansformer] ImageMagickContentTransformer not available: Failed to
perform ImageMagick transformation:
Execution result:
os: SunOS
command: convert
/ec/acc/server/weblogic/circabca2/u010/home/circabca/data/CIRCABC_ACC/tm
p_dir/Alfresco/ImageMagickContentTransformer_init_source_1843.gif
/ec/acc/server/weblogic/circabca2/u010/home/circabca/data/CIRCABC_ACC/tm
p_dir/Alfresco/ImageMagickContentTransformer_init_target_1844.png
succeeded: false
exit code: 1
out:
err: convert: not found05 Mar 2008 18:32:09,469 ERROR
. . .
[org.alfresco.smb.protocol] Failed to get local domain/workgroup name,
using default of WORKGROUP
05 Mar 2008 18:32:09,469 ERROR [org.alfresco.smb.protocol] (This may be
due to firewall settings or incorrect <broadcast> setting)
05 Mar 2008 18:32:09,581 ERROR [org.alfresco.smb.protocol.netbios]
NetBIOSNameServer setup error:
java.net.BindException: Permission denied
at java.net.PlainDatagramSocketImpl.bind0(Native Method)
at
java.net.PlainDatagramSocketImpl.bind(PlainDatagramSocketImpl.java:82)
at java.net.DatagramSocket.bind(DatagramSocket.java:368)
at java.net.DatagramSocket.<init>(DatagramSocket.java:210)
at java.net.DatagramSocket.<init>(DatagramSocket.java:261)
at java.net.DatagramSocket.<init>(DatagramSocket.java:234)
at
org.alfresco.filesys.netbios.server.NetBIOSNameServer.openSocket(NetBIOS
NameServer.java:1085)
at
org.alfresco.filesys.netbios.server.NetBIOSNameServer.run(NetBIOSNameSer
ver.java:1611)
at java.lang.Thread.run(Thread.java:595)
05 Mar 2008 18:32:09,617 ERROR [org.alfresco.smb.protocol] Server
error :

CIRCABC OSS – Installation Guide -25- 24/10/2008

 java.net.BindException: Permission denied
at java.net.PlainSocketImpl.socketBind(Native Method)
at java.net.PlainSocketImpl.bind(PlainSocketImpl.java:359)
at java.net.ServerSocket.bind(ServerSocket.java:319)
at java.net.ServerSocket.<init>(ServerSocket.java:185)
at java.net.ServerSocket.<init>(ServerSocket.java:141)
at
org.alfresco.filesys.smb.server.SessionSocketHandler.initialize(SessionS
ocketHandler.java:257)
at
org.alfresco.filesys.smb.server.NetBIOSSessionSocketHandler.createSessio
nHandlers(NetBIOSSessionSocketHandler.java:165)
at org.alfresco.filesys.smb.server.SMBServer.run(SMBServer.java:495)
at java.lang.Thread.run(Thread.java:595)
05 Mar 2008 18:32:09,804 WARN
[org.alfresco.util.OpenOfficeConnectionTester] A connection to
OpenOffice could not be established.
...

CIRCABC OSS – Installation Guide -26- 24/10/2008

8 Annex - Character Set Issue

Warning: The 'locale' setting of the Operating System must be set on UTF-8. If
not, specific characters should 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 shows some "en_US. ISO-8859-15@euro", the configuration

has to be changed using command “export” as:

~$export LANG= en_US.UTF-8

Note: Only the ‘UTF-8’ part is important, the ‘en_US’ part can be configured
as you wish, as “ja_JP.UTF-8” or “de_DE.UTF-8”.

CIRCABC OSS – Installation Guide -27- 24/10/2008