Installing Alfresco Labs 3b and Ingres

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Table of Contents

• 1 Preamble


• 2 Updates


• 3 Installing Alfresco and Ingres
  
  
  
  • 3.1 Alfresco 3.0
  
  
  • 3.2 Ingres Database 9.2
    
    
    
    • 3.2.1 Installing using the 'ingbuild' tool
    
    
  
  


• 4 Configuring Alfresco and Ingres
  
  
  
  • 4.1 Ingres Database
    
    
    
    • 4.1.1 Allow clients to connect to Ingres remotely by enabling the authentication
    
    
    • 4.1.2 Configure the size of the transaction log file, page sizes, cache sizes ...
    
    
    • 4.1.3 Create the database which will be used by Alfresco
    
    
    • 4.1.4 Set the Hibernate configuration properties
    
    
    • 4.1.5 Modify the content inside the Alfresco web application archive
    
    
  
  


• 5 Test your installation


• 6 Attachements

Preamble

This document is a written in the style of a tutorial to get Alfresco 3.0 running with Ingres on Linux.

Updates

• Aug the 24th '09: Created a new article which extends this one. It explains how to install the Alfresco 3.2 Community Edition with the Ingres Database 10 Community Edition. This tutorial can be found here: Installing_Alfresco_Community_32_and_Ingres_10
  

• Jan the 23th '09: Updated the section 'Modify the content inside the Alfresco web application archive'. You should use the Ingres specific files instead using the PostgreSQL ones.
  

• Jan the 23th '09: Alfresco Labs 3c is also out of date. So I am attaching the first draft of the database schema for Alfresco Labs 3 Stable. The file is named 'precreateschema_30stable.sql'.
  

• Jan the 21th '09: Ingres 9.3 b141 is available on esd.ingres.com, but please use Ingres 9.2 , which is also available there, to follow this tutorial!
  

• Jan the 19th '09: Alfresco Labs 3.0c was released meanwhile. Because of changes in the database schema the attached file 'precreateschema_30b.sql' does no longer work. I will publish 'precreateschema_30c.sql' as soon as possible.
  

Installing Alfresco and Ingres

This chapter describes how to install Alfresco and Ingres.

Alfresco 3.0

I decided to install the package 'Alfresco-Labs-3b-Linux-x86-install'. The package is preconfigured to use Derby. As Derby is included only for experimental purposes, I will exchange Derby with Ingres. Installing Alfresco using this package is a simple process.

1. As user 'root' create the installation destination folder: # mkdir /opt/Alfresco3
   
2. Create a user who will be the owner of this installation, you can also use an existing user: # useradd alfresco;passwd alfresco; mkdir /home/alfresco; chown alfresco /home/alfresco
   
3. Change the owner of the installation destination folder: chown alfresco /opt/Alfresco3
   
4. Switch the user to the one who should own your Alfresco installation: # su alfresco
   
5. Let's assume the installer is located in your home folder, so change the directory to this location: > cd $HOME
   
6. Change the mode of the binary file to executable: > chmod 755 $HOME/Alfresco-Labs-3b-Linux-x86-install
   
7. Execute it: > $HOME/Alfresco-Labs-3b-Linux-x86-install
   
   
8. Follow the instructions on your screen and choose the following destination directory: /opt/Alfresco3
   

Note: There is more about configuring Alfresco in later chapters.

Note: If you would like to install Alfresco into an existing application server/container like Tomcat or JBoss, you should read the Alfresco documentation to get further information.

Ingres Database 9.2

You can download the 'Ingres' Database from http://esd.ingres.com or you can build it from the source code.


The latest available Community Version is available on http://esd.ingres.com.  Select 'Community Projects' from the Product drop down and then 'Ingres Database' from the Release drop down.

Note: The current GA version (Enterprise Edition) of Ingres is 9.2. It comes with full Enterprise Support. If you want to use Ingres with Alfresco in production you should use the Enterprise Edition. Please contact Ingres (products@ingres.com) for further information.

Installing using the 'ingbuild' tool

Installing Ingres using the RPM based installer is very easy but requires a graphical user interface. The text mode installer is named 'ingbuild'. In this chapter you will learn how to install Ingres using 'ingbuild'.

Preparations:  

1. Create a user named 'ingres': # useradd ingres
   
2. Assign a password to this user: # passwd ingres
   
3. Create the folder /opt/Ingres: # cd /opt; mkdir Ingres
   
4. Create a subfolder named by your installation identifier. In our case we name it 'A3': # cd /opt/Ingres; mkdir A3
   
5. Change the owner of the directories to user 'ingres': # chown -R ingres /opt/Ingres
   
6. Switch the user to 'ingres': # su - ingres
   
   
7. Create a script  which sets the installation environment inside the folder '/opt/Ingres/A3'. Name the script 'loadA3env.bash'. Add the following lines:
   

#!/bin/bash
export II_SYSTEM=/opt/Ingres/A3
export PATH=/bin:/usr/bin:$II_SYSTEM/ingres/bin:$II_SYSTEM/ingres/utility
export LD_LIBRARY_PATH=/lib:/usr/lib:$II_SYSTEM/ingres/lib
export II_INSTALLATION=A3

Note: The following steps must be performed logged in as user 'ingres'.

Installing Ingres:

1. Load the installation environment : > source /opt/Ingres/A3/loadA3env.bash
   
2. Extract the file 'ingres.tar' from the archive 'ingres-x.x.x-yyy-NTPL-com-pc-linux-ingbuild-i386.tgz' that you downloaded from http://esd.ingres.com. (Where 'x' stands for the Ingres version and 'y' for the build number.) : > gunzip ingres-x.x.x-yyy-NTPL-com-pc-linux-ingbuild-i386.tgz; tar -xvf ingres-x.x.x-yyy-NTPL-com-pc-linux-ingbuild-i386.tgz
   
3. Copy the file 'ingres.tar' to the Ingres installation folder: > cp ingres.tar $II_SYSTEM/
   
4. Change the directory to the Ingres installation directory: > cd $II_SYSTEM
   
5. Create a subfolder named 'ingres': > mkdir ingres
   
6. Extract the 'ingbuild' tool from 'ingres.tar': > tar -xvf ingres.tar install
   
7. Move the folder 'install' to it's final destination: > mv install ingres/
   
8. Run the 'ingbuild' installation tool: > $II_SYSTEM/ingres/install/ingbuild -express $II_SYSTEM/ingres.tar
   
9. Remove the temporarily created file 'ingres.tar': > rm ingres.tar
   

Note: This sets up all products that are available in your distribution of Ingres. 'ingbuild' can also be used to install only the required features. Please read the Ingres documentation for further details.

Check your installation succeeded:

1. Change to user ingres: > su - ingres
   
2. Load the environment: > source  /opt/Ingres/A3/loadA3env.bash
   
3. Start Ingres, and qualify all services are starting up without problems: > ingstart
   
4. Stop Ingres, and qualify all services are shutting down without problems: > ingstop
   

Note: Find more about the Ingres configuration basics in the next chapter.

Configuring Alfresco and Ingres

This chapter describes how to perform the basic configuration to get Alfresco and Ingres working together.

Ingres Database

Allow clients to connect to Ingres remotely by enabling the authentication

It is recommended to have 'make' and 'gcc' installed before performing the next steps. Therefore simply type 'which gcc' and 'which make' on your console. If a path is returned the tools are already installed. If not,  you may have to install them using the package manager of your Linux distribution.

1. Switch the user to 'root': > su root
   
2. Load the environment: # /opt/Ingres/A3/loadA3env.bash
   
3. Run the program which creates the password validation program: # mkvalidpw
   
4. Restart Ingres
   

Note: Not creating the password validation program will result in error messages like 'invalid username/password' if trying to connect remotely to any database.

Configure the size of the transaction log file, page sizes, cache sizes ...

Your Ingres specific configuration depends of your 'use case'. So we created a shell script which performs several configuration steps for you to optimize the Ingres configuration for Alfresco (other Hibernate based applications will benefit from this configuration). The script is named  'IngresPostConfigureAlfresco.bash' and is attached to this site. It allows you to choose between the configuration guidelines 'small', 'medium', 'large' and 'huge'. Be aware of the fact that the system requirements are correlated to the chosen guideline. The 'small' configuration guideline is recommended for testing, so let us choose this one.

Note: The 'huge' configuration does require a substantial amount of physical resources.

1. Log in as user 'ingres', load the Ingres environment and STOP your Ingres installation
   
2. Run the configuration script: > bash IngresPostConfigureAlfresco.bash $II_SYSTEM small
   
3. Try to restart Ingres: > ingstart
   
4. If you get an error message like 'Your system has not enough resources to start Ingres. XXX shared memory is required', then you have to change your kernel's shared memory settings. Therefore log in as user 'root' and edit the file '/etc/sysctl.conf', add the lines 'kernel.shmall=XXX' and 'kernel.shmmax=XXX' and load this new settings by issuing the command '/sbin/sysctl -p'. Try to restart Ingres!
   

Create the database which will be used by Alfresco

We will assume you are logged in as user 'ingres', the Ingres environment is set and Ingres is started up properly. 

1. Create a database named 'alfresco': > createdb alfresco
   
2. Create the required database schema. Therefore you can find the SQL script 'precreateschema_30b.sql' attached to this article.: > sql alfresco

dir.root=/opt/Alfresco3/alf_data
dir.indexes=${dir.root}/lucene-indexes
db.schema.update=false
db.driver=com.ingres.jdbc.IngresDriver
db.name=alfresco
db.url=jdbc:ingres://localhost:A37/${db.name}
db.username=ingres
db.password=password_of_user_ingres
db.pool.initial=10
db.pool.max=100

Note: The connection string contains the the port information 'A37'. The installation identifier we used to install Ingres is 'A3'. Internally the string 'A3' will be translated to an unique port address. This port address plus the offset 7 results in another port address which is assigned to the installation's Data Access Server. The Data Access Server handles the JDBC connections.

Set the Hibernate configuration properties

Alfresco is using Hibernate as O/R mapper. The configuration file can be found inside the directory '/opt/Alfresco3/tomcat/shared/classes/alfresco/extension' and it is called 'custom-hibernate-dialect.properties'. You have to set the following properties:

hibernate.dialect=org.hibernate.dialect.IngresDialect
hibernate.query.substitutions=true 1, false 0, yes 'Y', no 'N'
hibernate.connection.isolation=2
hibernate.jdbc.use_scrollable_resultset=true

Modify the content inside the Alfresco web application archive

Alfresco comes as the single file 'alfresco.war' which will be deployed by an application server like Tomcat. You can find this web application archive inside the folder '/opt/Alfresco3/tomcat/webapps/'. The easiest way to edit  files inside this archive is to use the tool named 'Midnight Commander'.  It allows you to open an archive (for instance *.zip, which means also *.war) and to edit the files inside it.

1. Open the the 'alfresco.war' file using the 'Midnight Commander': > cd /opt/Alfresco3/tomcat/webapps; mc
   
2. Inside the 'alfresco.war' file, change the directory to '/WEB-INF/classes/alfresco/activities
   
3. There you can find some directories named by the Hibernate dialect of each DBMS.
   
4. Copy the contents of the file 'org.hibernate.dialect.IngresDialect.zip', which is attached to this article, to '/WEB-INF/classes/alfresco/activities' to create an entry for Ingres
   

Note: Midnight Commander is available as part of many Linux distributions. Use the package manager of your Linux distribution to install it!

Test your installation

Alfresco and Ingres are now installed and configured completely. Please perform the following steps to confirm your installation starts up without problems:

1. Start your Ingres installation 'A3'
   
2. Start Alfresco: > /opt/Alfresco3/alf_start.sh
   
3. Inspect the log file: > tail -f /opt/Alfresco3/tomcat/logs/catalina.out
   
4. You should see the message 'INFO: Deploying web application archive alfresco.war'
   
5. Some non critical errors related to SMB, SWF2PDF, OpenOffice and ImageMagick may appear.
   
6. Open the Alfresco Web Client using a web browser. The URL is 'http://ip_or_hostname:8080/alfresco'
   
7. Log in as user 'admin' with password 'admin'
   

Note: If errors related to SMB, SWF2PDF or OpenOffice are appearing, you have to configure Alfresco's internal SMB server, to install SWF2PDF, OpenOffice and ImageMagick. Further information can be found in the Alfresco documentation and Wiki.

--david.maier@ingres.com 18:08, 20 October 2008 (BST)

---

Attachements

IngresPostConfigureAlfresco.bash
precreateschema_30b.sql
precreateschema_30stable.sql
org.hibernate.dialect.IngresDialect.zip

Note: It may be necessary to run dos2unix on the scripts.
Installation
Labs 3
Ingres