Agilefant installation guide

IMPORTANT! Those upgrading from versions previous to 3.1.1 must install 3.1.1 first, start it once, and only after that upgrade to more recent versions. Otherwise, database schema migration will fail. Check the upgrading instructions for details.

Database connection settings are from 3.1.1 onwards configured in agilefant.properties; see the installation guide for details. If you're having trouble, check out if there's something in Ubuntu installation guide (based on ckhoo's addendum to the install guide (on Ubuntu)) that helps!

Check out the system and browser requirements!

Generic installation guide

Below are the instructions on how to install Agilefant. If you need more details you can check out the Ubuntu installation guide.

Phases 0-2 are mandatory. Phase 3 is optional for users who want to use Apache as part of their installation.

In the instructions the following references are used:

[Tomcat path]

The path to Tomcat. For example, /var/lib/tomcat7 on Ubuntu or C:\Program Files\Apache Software Foundation\Tomcat 7.0\ on Windows

[Agilefant instance name]

The name you can choose for your Agilefant instance

[strong unique password]

The password for your Agilefant database. Create one yourself, or on Ubuntu you can create one by running: pwgen -s 16

[mysql username] and [mysql password]

The username and password used to access your mysql database. These are created during the installation of mysql

[Apache settings path]

Used only in the optional Apache phase. The path to Apache's settings. For example: /etc/apache2 on Ubuntu or C:\Program Files\Apache Software Foundation\Apache2.2\conf on Windows

0. Install the needed software

• Install Java runtime environment (JRE, Oracle Java 7 recommended) and set environment variables
• Install Tomcat (Tomcat 7 recommended)
• Install MySQL
• Download Agilefant release .zip from https://sourceforge.net/projects/agilefant/files/latest/download
• Unpack the Agilefant release .zip and rename agilefant.war as [Agilefant instance name].war

1. Create the database for the Agilefant instance in MySQL

• Generate & record a [strong unique password] to use for the organization's database
• Run the following commands in console: mysql -u [mysql username] -p (enter [mysql password] when asked) create database [Agilefant instance name]; grant all on [Agilefant instance name].* to [Agilefant instance name]@localhost identified by '[strong unique password]'; exit;

2. Configure Agilefant to connect to the created database and deploy the war in Tomcat Manager

• Edit /WEB-INF/agilefant.conf in the [Agilefant instance name].war package change username, password and url based on the agilefant name and password created previously: username = "[Agilefant instance name]" password = "[strong unique password]" url = "jdbc:mysql://localhost/[Agilefant instance name]?relaxAutoCommit=true&;autoReconnect=true&;useUnicode=true&;characterEncoding=utf-8&;autoReconnectForPools=true"
• Deploy [Agilefant instance name].war by either copying it to [Tomcat path]/webapps/ or use Tomcat Manager
• You can test that the Agilefant has been set up correctly by clicking on it from Tomcat Manager app list.
• Test that the 'Fant works at address localhost:8080/[Agilefant instance name] by logging in with admin:secret (Default Tomcat Connector port should be 8080 on Ubuntu. You can see it from [Tomcat path]/conf/server.xml)
• If yes, you're set!

3. Optional phase: Configure Apache to allow access to the new Agilefant instance from outside localhost and restart

• Install Apache
• Open [Apache path]/httpd.conf in a text editor, and add the text below to the end of the file:

------ clip clip ------

<Location /[Agilefant instance name]>

ProxyPass http://localhost:8080/[Agilefant instance name]

ProxyPassReverse http://localhost:8080/[Agilefant instance name]

Order Allow,Deny

Allow from all

</Location>

------ clip clip ------

• Restart Apache (service apache2 reload should be enough on Ubuntu)
• Test that the 'Fant works at address localhost/[Agilefant instance name] by logging in with admin:secret

Installation guide for Ubuntu

This installation guide is for Agilefant 3.1.1+ (which will not work on Tomcat 6).

This guide is an extension to Jarno's original installation guide. It that adds some additional steps required to get Agilefant running properly with Tomcat 7 on Ubuntu 12.04 LTS.

Here's my recommended list of environment changes

(1) Use Oracle's JDK instead of OpenJDK

Why: Getting chart drawing to function with OpenJDK is near impossible. The easiest solution is to use Oracle's JDK instead.

Solution: we'll install the Oracle JDK for Ubuntu from the webupd8 PPA

Steps:

• Install add-apt-repository -- Execute sudo apt-get install python-software-properties
• Add the webup8 PPA package list -- Execute sudo add-apt-repository ppa:webupd8team/java -- Execute sudo apt-get update
• Install the Oracle Java 7 JDK -- Execute sudo apt-get install oracle-java7-installer
• Check that the default java version is 1.7 -- Execute java -version
• If the default JDK library is not Oracle Java 7, then update the machine to default to Oracle's Java JDK (correct path to JDK can be found by executing sudo update-java-alternatives -l) -- Execute sudo update-java-alternatives -s /usr/lib/jvm/java-7-oracle
• Force Tomcat 7 to use the Oracle JDK (The Tomcat 7 prefers OpenJDK over Oracle JDK even if the Oracle JDK is the default java environment) -- Edit /etc/default/tomcat7 -- Add the following line: JAVA_HOME= The default path should be /usr/lib/jvm/java-7-oracle

(2) Install fonts

Why: Agilefant's chart rendering requires fonts. Unfortunately, the Ubuntu installation may not necessarily have installed any fonts.

Solution: install some fonts

Steps:

• Install the common dejavu fonts -- sudo apt-get install ttf-dejavu
• Install the Microsoft TrueType core fonts -- sudo apt-get install ttf-mscorefonts-installer

(3) Increase Tomcat's memory allocation and aggressive reclaim memory space

Why: Tomcat 7 and Agilefant is fairly resource heavy. We'll need all the space we can get.

Solution: we'll apply the following JVM options to address these problems:

(a) Enable chart rendering functions on GUI-less Ubuntu installation: -Djava.awt.headless=true (b) Increase Tomcat's heap space -Xms256m -Xmx1024m (c) Increase Tomcat's Perm Space so that the charts rendering have enough memory -XX:PermSize=256m -XX:MaxPermSize=512m

Steps:

• Edit /etc/default/tomcat7
• Add/modify the JAVA_OPTS setting and apply the following options: -Djava.awt.headless=true -Xms256m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512m

Restart Tomcat.

If the changes are successful, Tomcat's server status should report that:

• Tomcat's JVM version number should match the java binary version number
• Tomcat's total memory is approximately 256 MB and its maximum memory is approximately 1 GB.