I. Environment Installation

1. MySQL Installation

Download MySQL from the following url : http://dev.mysql.com/downloads/

Mysql installation manual can be found at the following url : http://dev.mysql.com/doc/

Update your OS environment PATH by adding the path to the bin of MySQL installation folder.

If you want to store big files in the database, we advise you to increase the maximum size of packets (max_allowed_packet). You only have to edit the my.ini file in the installation directory of MySQL and to add the following property :


Launch the MySQL server, if it is not already done automatically.

2. Database Creation

Two installation procedures are proposed for setting up lutece database :

  • Database creation using Ant.
  • Database creation using MySQL.

2.1 Setting up the database using Ant

The easiest and fastest way to create the database is to use Ant. That's why, before that, you have to install Ant.

Please follow this procedure in order to install it :

2.1.a Ant Installation

Download Ant from the following url : http://ant.apache.org/bindownload.cgi.

Update your OS environment PATH by adding the path to the bin of Ant installation folder.

2.1.b Database Creation

Now, you only have to create the lutece database.

To do this, please go to the WEB-INF/sql folder in the webapp and execute the following command :

[Win32] & [Unix] : ant

Information : This command creates and initializes the database and the tables. It uses the build.xml file which is automatically generated during the project building. This script will use all SQL files in the WEB-INF/sql directory of the webapp. First, it will call creation and initialization files of the lutece core tables (create_db_lutece_core.sql and init_db_lutece_core.sql). After that, if the webapp contains some plugins, the script will execute the SQL files for each plugin which are in the WEB-INF/sql/plugins directory (these files can be creation and initialization scripts for plugin tables but can also initialize core tables).

This script uses the db.properties file to connect to the database. To configure this file, please go to the part II.2. Update of db.properties file

Notice : If a plugin needs a particular connection pool, it has to set this pool in the db.properties file. This pool must have the same name than the plugin which will use it.

2.2 Setting up the database using MySQL commands

The other way to install the database is to use MySQL commands. To do that, you only have to have MySQL installed. To install and configure MySQL, please go to the the part I.1. MySQL Installation.

Information : the *.sql files are used by "source" MySQL command are found in the WEB-INF/sql folder.

To use the "source" command as mentioned below, put the *.sql files in the MySQL bin folder. Otherwise, indicate the absolute path of the files in the command.

Create Lutece database :

[Win32] :

Launch MySQL from the bin folder <mysql_home> (where <mysql_home> is the mysql installation folder).

Run the following command :

mysql> create database lutece;

[Unix] :

# mysql -u root -p new_password

mysql> create database lutece;

Connect to the database :

[Win32] & [Unix] :

mysql> use lutece;

Create and initialize the database : (the SQL scripts are packed in Lutece distribution)

For this step, you have to differenciate core tables and plugin tables.

  • Core tables :

[Win32] & [Unix] :

mysql> source create_db_lutece_core.sql;
mysql> source init_db_lutece_core.sql;
  • Plugin tables (if these plugins are deployed in the webapp) :

In the WEB-INF/sql/plugins directory, you have to execute all SQL scripts (create_<X>.sql and init_<X>.sql) of each sub-directory.

[Win32] & [Unix] :

mysql> source create_<X>.sql;
mysql> source init_<X>.sql;

To verify whether the database is correctly configured for user lutece (by default), run the commands :

[Win32] & [Unix] :

mysql> show tables;
mysql> select * from core_admin_right;

3. Application Server Installation

The installation described below concerns the Tomcat Server.

3.1 JDK 5.0 Installation

Tomcat installation needs the installation of Java 2 SDK Standard Edition (the version used must be at least jdk 1.5.0) on the server.

Installation of Java 2 SDK, Standard Edition :

Download the JDK version from Sun website : http://java.sun.com/j2se/downloads.html.

Configure the JAVA_HOME environment variable value to the path of the JDK containing folder.

Update the environment variable PATH by adding JAVA_HOME\bin to its definition.

3.2 Tomcat Installation

Download Tomcat from the following address: http://jakarta.apache.org/tomcat/index.html.

Then configure the TOMCAT_HOME environment variable value to the path of the Tomcat folder.

Reload the file containing the environment variables for the update to take effect.

3.3 Installation Checking

  • Run Tomcat : (<tomcat_home> is the installation folder of Tomcat).

    [Win32] : <tomcat_home>/bin/startup.bat

    [Unix] : <tomcat_home>/bin/startup.sh

  • Run a browser and type the following url : http://localhost:8080. The Welcome page of Tomcat should appear.
  • To stop Tomcat :

    [Win32] : <tomcat_home>/bin/shutdown.bat

    [Unix] : <tomcat_home>/bin/shutdown.sh

3.4 Server Configuration

  • To disable the list file display from the webapp URL, modify the <tomcat_home>/conf/web.xml file :

  • Modify the size of the memory allocated for the java virtual machine :

    Add the line below in the files <tomcat_home>/bin/catalina.bat and <tomcat_home>/bin/catalina.sh :

    CATALINA_OPTS="-Xms128m -Xmx512m"

    to set the initial (128 Mo) and maximum (512 Mo) amounts allocated for the JVM.

4. Application Installation

  • Download the Lutece zip files. You can go to the Download page to download these files.
  • Build Lutece project if you use the sources and not the .war file.
  • Copy the Lutece war file in the Tomcat webapps folder.
  • Launch Tomcat to deploy the application.
  • Edit the configuration files config.properties and db.properties to update the paths.

    The content of these files is described below.

II. Lutece Configuration

Application configuration files are located in the WEB-INF/conf folder of the webapp. The files that need to be configured are the following:

  • config.properties
  • db.properties

1. Configuration of the config.properties file

Needs update during the deployment process:

During the first launch of the application, autoInit is set to true to allow the update of the absolute paths of the file. Then it is set to false.

# AutoInit for first deployment


Adjust necessary information to send emails (including the IP of the SMTP server).

# Mail sending parameters







Adjust the absolute paths to access to the property files lutece, jtidy and webmaster.

# Property files





Adjust the absolute paths of the log files.

# Log files




If error.page.debug=true, the detail of the error is visible on the page. If error.page.debug=false, the message defined in error.page.message will be visible in the page.

# Error page management


error.page.message=Please contact the administrator of the site

Activate or deactivate the cache management for templates, page content or articles. In a production environment , it is advised to place the values to true.

# Caches management




Indicate the paths of the files application.log, error.log and pool.log.

# log4j parameters

log4j.rootLogger=WARNING, Error

log4j.logger.lutece.error=ERROR, Error, Console

log4j.logger.lutece.pool=ERROR, Error





2. Update of the db.properties file

Connection service choice :

  • LuteceConnectionService to use Lutece connection pool.
  • TomcatConnectionService to use Tomcat connection pool.




Indicate the name of the driver required to access a MySQL database.


Indicate portal.url to identify the jdbc datasource of the Lutece database. portal.user and portal.password indicate the login and password required to connect to the database.




Indicate the initial connections number to the database.


Indicate the maximal connections number supported by the pool.


Indicate the maximum time to wait for a connection (in milliseconds).


Request enabling to test the validity of the connection. This value varies from a database to another:

  • SELECT 1 for a MySQL database.
  • SELECT SYSDATE FROM dual for an Oracle database.

portal.checkvalidconnectionsql=SELECT 1

Notice : if you are modifying one or more property files, you must stop and restart the tomcat server for the update takes effect.

The webmaster.properties file can also be adjusted. An interface enables to do that simply in the administration module.

III. Launching the application

To launch the webapp, type in your browser the following URL (the tomcat server must be running): http://localhost:8080/lutece/.

IV. Connection to Lutece administration module

Type the following URL to go into the administration module: http://localhost:8080/lutece/jsp/admin/AdminLogin.jsp.

Two accounts are created by default:

  • Login : admin - Password : admin (Technical administrator account).
  • Login : lutece - Password : lutece (Content administrator account).