Installation procedure for debian 7

This page contains the instructions for a developer who wants to install OEAF on a Debian 7 platform.

To perform this procedure, you will need superuser privileges. . In case you don't have superuser privileges, ask your system administrator to add your user as a sudoer. To do this, as root, type:

echo "your_user ALL=(ALL) ALL" > /etc/sudoers.d/oeaf

or, if you don't want to constantly enter your password each time you use sudo (especially useful when using scripts):

echo "your_user ALL=NOPASSWD: ALL" > /etc/sudoers.d/oeaf

Install packages

sudo aptitude install default-jdk tomcat7 tomcat7-admin maven2 git

Special accesses

You will need writing permissions on some Tomcat's directories to deploy web applications and perform other configurations. Adding your user to Tomcat's group makes this possible:

sudo adduser your_user tomcat7

As it's also likely that you will want to read Tomcat's log files, you should also add your user to the adm group:

sudo adduser your_user adm

You will have to log out and come back to enable these changes. To verify if your user is effectively in the required groups, the following command should contain tomcat6 and adm in its output:

groups

Set up Tomcat

Add manager user

Edit file: /etc/tomcat7/tomcat-users.xml

In the <tomcat-users> element, add:

<role rolename="manager-gui"/>
<role rolename="manager-script"/>
<role rolename="manager-jmx"/>
<role rolename="manager-status"/>
<user username="admin" password="*****" roles="manager-gui,manager-script,manager-jmx,manager-status"/>

Make sure that the declaration of the users are not between comment marks.

Add jvm parameters

Edit file: /etc/default/tomcat6

Add this line right after the declaration of JAVA_OPTS:

JAVA_OPTS="-Xmx1024m -XX:PermSize=1024m -XX:MaxPermSize=1024m -Dfile.encoding=UTF-8 -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true ${JAVA_OPTS}"

In your environment or .bashrc, set up

export CATALINA_HOME=/usr/share/tomcat7 export CATALINA_BASE=/var/lib/tomcat7

Set up Maven

Increase memory

To prevent OutOfMemoryException when using Maven, you can define the MAVEN_OPTS environment variable. You usually do this by adding this entry at the end of your .bashrc file:

export MAVEN_OPTS="-Xmx768m"

Set up Maven repository cache server (optional)

To improve efficiency when downloading Maven dependencies and to prevent work interruption in the case where a Maven repository is down and that some dependencies are impossible to download, an Artifactory Repository instance is available here:

http://hades.licef.ca:8080/artifactory

The Artifactory Repository acts as a proxy to access external Maven repositories. It also caches all the accessed jar files.

To make Maven uses the Artifactory Repository, edit the /.m2/settings.xml file and add the following mirror declaration:

<mirror>
    <id>artifactory</id>
    <mirrorOf>*</mirrorOf>
    <url>http://hades.licef.ca:8080/artifactory/repo</url>
</mirror>

Download source code

The source code can be obtained using Git.

As a developer:

git clone [email protected]:GTN-Quebec/oeaf.git

Or as an anonymous user:

git clone https://github.com/GTN-Quebec/oeaf.git

An oeaf folder will be created with all the source code in your current location. This oeaf directory will be referenced as $OEAF_SRC.

Build the application

Set up the environment

A JAVA_HOME variable must be defined.

You usually do this by adding this entry at the end of your .bashrc file:

export JAVA_HOME=/usr/lib/jvm/default-java

Generate the main config file

Type:

cd $OEAF_SRC ant sample-config

Adjust the config to your environment

Now edit $OEAF_SRC/src/main/core.properties file and adjust values with your own settings.

Detailed information concerning each property with some sample values can be found here.

Build the application

Before compiling the whole project or a specific module, it's recommended to stop Tomcat. Failing to do can make a Tomcat contexts to disappear.

Type:

mvn install -Dmaven.test.skip=true

A special folder must be created where some data, executables, and other resources will be stored by OEAF while running. This folder can be anywhere but we suggest to put it /var/lib/oeaf:

sudo mkdir /var/lib/oeaf sudo chown tomcat7.tomcat7 /var/lib/oeaf sudo chmod 775 /var/lib/oeaf

You should define an environment variable $OEAF_HOME that points to this location in your .bashrc file.

export OEAF_HOME=/var/lib/oeaf

Deploy the application

There are many ways to deploy the web applications within Tomcat. The 2 most popular are either by deploying the war files into Tomcat's webapps directory or by defining Tomcat context files pointing to the target directories that are built by Maven.

If you choose the first option, on Debian, the location of the webapps directory is /var/lib/tomcat7/webapps (or $CATALINA_BASE/webapps).

For development, the second option is more convenient. You can create the context files like this:

cd $OEAF_SRC
sudo ant deploy-proeaf

While developing, it might be better to prevent Tomcat service from starting automatically:

cd /etc/init.d
sudo update-rc.d tomcat7 disable

To start the Tomcat service manually, you do:

sudo /etc/init.d/tomcat7 start

To stop the Tomcat service manually, you do:

sudo /etc/init.d/tomcat7 stop

If you want to reenable the Tomcat service to start automatically:

cd /etc/init.d
sudo update-rc.d tomcat6 enable