Agilefant.org

Agilefant installation guide using ZIP-file

Using this guide you are not required to have SVN-client, Apache Ant or Hibernate tools installed.
However, you are recommended to check out that your server has all the required services available.

Some steps have alternative section that gives tips on improvings security or customization.

Download the latest release

Download the latest release from Agilefant homepage.

Unzip the file to a temporary directory

Use your favorite zip program to unzip the package. The directory containing the unzipped files is referred in this installation guide as TEMP_DIR.
The files in the directory are required during installation. You can remove the files after installation is complete.

Create and initialize database

Login to MySQL as root user (or any other user with sufficient privileges):

mysql -uroot -p
CREATE DATABASE agilefant;
GRANT ALL ON agilefant.* to agilefant IDENTIFIED BY 'agilefant';

Exit from the MySQL monitor and log back in as agilefant;

exit;
mysql -uagilefant -pagilefant
use agilefant;
source TEMP_DIR/create-db.ddl;
source TEMP_DIR/insert-users.sql;
exit;

Alternative

The section above assumes that your MySQL database is not accessible to outsiders and thus using very weak and public password for the Agilefant database is not an issue.
If you want to improve your security you can use more secure password, referred bellow and later on as MY_PASS, when issuing the GRANT statement:

GRANT ALL ON agilefant.* to agilefant IDENTIFIED BY 'MY_PASS';

If you use a password different from the default you need to configure the agilefant web application by hand later on in section Deploy to Tomcat.

Deploy to Tomcat

Setting Agilefant security policy

If you use Tomcat's security manager, e.g. Tomcat is stared with option -security, you need to grant Agilefant operating rights. In this guide we grant Agilefant all rights, but if you are adventurous and worried about security you might want to explore the possibilities of limiting the rights Agilefant is granted.

The location of the correct .policy file depends on your Tomcat setup. On Debian-based systems where Tomcat 5.5 is installed using apt-get the correct .policy file is

/etc/tomcat5.5/policy.d/50user.policy

Open the file with text editor and add the following lines to the end of the file

grant codeBase "file:${catalina.base}/webapps/agilefant/-" {
	permission java.security.AllPermission;
};

After saving the file you need to restart Tomcat.

If you really don't want to restart Tomcat, you probably can use Tomcat admin application to set the policy without restarting Tomcat. The realization of this task is however outside the scope of this guide. See Tomcat documentation for more help.

Deploy with Tomcat manager application

Open Tomcat manager with your web browser (e.g. http://localhost:8180/manager/html)
Press "Select WAR file to upload" Browse-button and select agilefant.war from TEMP_DIR.
Press Deploy.

If everything goes well, agilefant should appear to the Applications list with status Running true.

If the manager application has not been installed you need to do the deployment by hand. See Tomcat documentation for details.

Alternative

The section above assumes that your web server setup allows and enables automaticly connections to deployed webapps.
Depending on your setup, you might need to configure Tomcat, Apache web server or your firewall to allow connections to the Agilefant webapp.
The user runnign Tomcat daemon must be allowed to access MySQL service.

If you used alternative password in the Create and initialize database section you need to configure the password to Agilefant.
Open the database.properties file in your tomcat/webapps/agilefant directory (e.g. /var/lib/tomcat5.5/webapps/agilefant/WEB-INF/database.properties) with text editor.
Edit the line

hibernate.connection.password=MY_PASS

and save the file.

Connect to Agilefant

You should now be able to connect to Agilefant with your web browser. The URL depends on your web server setup, but might be something like
http://localhost/agilefant:8180, which is the agilefant context in default Tomcat port.
Log in with username admin and password secret. Don't forget to change the password from the User tab right after you log in to the system.

(Alternative) Tomcat configuration

Selecting Java version

The Java version Tomcat is using is configured from the initialization script usually located in /etc/init.d/. Stop Tomcat using the initialization script before before editing the initialization.

JAVA_HOME variable in the initialization script should point to your chosen Java version. Java runtime environment installations are susually located in /usr/lib/jvm/.

JAVA_HOME=/usr/lib/jvm/java-6-sun

 After changing the path you can restart Tomcat.

Disablin Tomcat security manager

If your Tomcat is in secure environment not accessible to outsiders you might want to disable the security manager to avoid any permission based problems. This can usually be done with Tomcat startup script located in file

/etc/init.d/tomcat5.5

Open the file with text editor and change the line

TOMCAT5_SECURITY=no

Save the file and restart tomcat.

Fixing UTF-8 encoding

 If UTF-8 encoding doesn't seem to work, make sure that your server.xml file doesn't have property useBodyEncodingFormURI="true". server.xml is usually located in tomcat/conf directory.

<Connector port="8380" useBodyEncodingFormURI="true" /> <!-- WRONG -->

should be

<Connector port="8380" URIEncoding="UTF-8"/> <!-- CORRECT -->