Locked History Attachments

FenixSetup


Disclaimer

Before getting started, it should be clear that installing FÉNIX is not trivial!

FÉNIX is an enterprise class application. If you are not familiar with terms such as (but not limited to): web-container, j2ee, environment variable, mysql, innodb, etc, then you are probably in over your head. Many security issues must also be addressed:

  • network security
  • operating system security
  • application security

Moreover, once the FÉNIX application is correctly (and safely) installed, a much more complex and difficult issue arises: loading/importing data into the data repository.

This document should be considered a mere guideline to follow for setting up the FÉNIX application on a production server. It is not a complete document on setting up the FÉNIX application. Also keep in mind that this document may contain errors, and may omit important details.

We are here to help as much as we can, and we hope to someday see our beloved application thrive throughout the world, but the responsibility is in the hands of whomever takes on the task of setting up the application.

Requirements

Due to it's nature, a binary release of the FÉNIX application would only be usefull to a single academic institution. The application must be configured specifically for each institution where it will be installed. Simply put, this means that before we can install FÉNIX in an institution, we must first produce a binary release configured specifically for that institution. This section is therefore divided into two parts:

  • one that describes the requirements for producing a binary version of the application;
  • another that describes the requirements for running the application in a production environment.

Requirements for compiling

version

J2SE

1.6 or higher

http://java.sun.com/javase/downloads/index.jsp

Ant

1.6.3 or higher

http://ant.apache.org/bindownload.cgi

Requirements for running

version

J2RE

6.0 or higher

http://java.sun.com/javase/downloads/index.jsp

MySQL

5.0 or higher

http://dev.mysql.com/downloads/

Web Container

Servlet 2.4/JSP 2.0 Spec or higher (Tomcat 5.5.12 or higher is recommended)

http://tomcat.apache.org/download-55.cgi

  • Web Server (optional)

Environment Variables

JAVA_HOME

should be available system wide and should point to the directory where j2se is installed

JAVA_OPTS

should be se accordingly to the systems requirements and to the available virtual memory

ANT_HOME

should be available system wide and should point to the directory where ant is installed

ANT_OPTS

should be se accordingly to the systems requirements and to the available virtual memory

CATALINA_HOME

should be available to the user under wich the web container is run, and should point to the directory where Tomcat is installed

PATH

should include java, ant and tomcat executables

Obtaining the Source Code

The source code is available at https://fenix-cvs.ist.utl.pt/open/trunk/fenix. To obtain the source code with the svn client, the following command (or equivalent for other svn clients) can be used:

   svn co https://fenix-cvs.ist.utl.pt/open/trunk/fenix

This will result in downloading the source code from SVN TRUNK branch. This branch is the main line of development, which means it almost certanly contains an unstable version of the application. Before choosing which version to checkout, consult the page SVNOrganization. This page describes which lines of development are currently active, and also where stable code can be found. This page will also contain indications of any releases.

At IST we tag each version that is deployed onto the production servers. Additionally we log every deploy here: HeadIntegrationReports. This way we keep track of what version is being used, what new features each new version provides, and what scripts need to be run to upgrade. We strongly suggest that such registers be maintained at every institution that installs the FÉNIX application. It may be feasible to maintain this information on this wiki, but this will have to be authorized/arranged by the Project Leader.

Customizing

Configure

The first step to customizing the application is to configure the properties file that defines things such as what database to use, what Roles are to be made available, etc... the list is a bit extensive. To get started copy the build.properties.sample file:

  cp src/main/resources/configuration.properties.sample src/main/resources/configuration.properties

The configuration.properties file should be edited appropriately.

Presentation Details

The FÉNIX application is developed specifically for IST. This means that it shipped with logos and text specific to this institution. Installing FÉNIX at another institution means that such aspects must be changed. However this is not the focus of this document. If your getting started you probably want to tend to this later anyway.

Compiling

The name of this section is a bit miss-leading, it should probably read generating a distribution, but compiling has a nicer presentation. Once the application has been specifically customized to fit the needs of the institution, then a distribution can be generated. To do so, simply type the following instruction in the projects root directory:

  mvn clean package

This instruction will, generate a Web ARchive (WAR) in the target directory. (target/fenix-1.0-SNAPSHOT.jar)

Preparing the Database

First create the database where the applications data will be stored. Next create the necessary database structure with the following instructions (or run the init.sh script found int the projects root directory):

  mvn clean package
  mvn fenix:pre-init
  wget -O "content-structure.sql" --no-check-certificate https://fenix-ashes.ist.utl.pt/fenixWiki/FenixSetup\?action=AttachFile\&do=get\&target=content-structure.sql
  mysql -uroot ciapl < content-structure.sql
  rm -rf content-structure.sql

  mvn fenix:data-init
  echo "update IDENTIFICATION, LOGIN_ALIAS set IDENTIFICATION.PASSWORD = md5('pass') where IDENTIFICATION.OID = LOGIN_ALIAS.OID_LOGIN and LOGIN_ALIAS.ALIAS = 'admin';" > .tmp.init
  mysql -uroot ciapl < .tmp.init
  rm -rf .tmp.init

The above instructions also load some data. Most data can be introduced into the application with the existing interfaces. However, other information must be loaded through other means, or directly into the database. At this point the database is populated with the minimal amount of data and is ready to run, but no user can login yet. The initialize database script creates one user with access to the Manager portal. The username for this user is admin. To set a password run the following instruction replacing <password> with a secure password. This user will have privledges to attribute passwords, to grant roles to users, to create curricular plans, etc.

  update IDENTIFICATION, LOGIN_ALIAS set IDENTIFICATION.PASSWORD = md5('<password>')
      where IDENTIFICATION.OID = LOGIN_ALIAS.OID_LOGIN and LOGIN_ALIAS.ALIAS = 'admin';

Deploying

Deployment depends greatly on the configuration of the web container. The instructions in this section may therefor have to be adjusted.

To deploy the WAR file generated in the previous section, simply copy it into the webapps directory of the web container. It may be necessary to restart the web container. Additionally, we recommend deleting the contents of work and temp directories of the web container, each time you start the web container.

Security Issues

Upgrading

Upgrading the application is usually done in three steps:

  • updating the source code from the svn repository;
  • updating the database to reflect changes in the domain model;
  • deploying the upgraded code.

We won't go into much detail here regarding the first step because this varies, depending on what branch your working on and what version you wan't to upgrade to. Extensive documentation is available on the web regarding how to work with SVN, and many utilities are available that can help with this process.

Before updating the database remember to always have a backup! This is very important. If a database upgrade script should bappen to fail half way through the process, a backup means the problem can be fixed, the process repeated and no data lost. Having no backup, may result in an unrecoverable loss of data. Although this is not the focal point of this section, it is important to mention, and can never be over-stressed; always have a backup before updating the database.

The sql scripts that update the data repository are found in the folder etc/database_operations where they are organized in subfolders by date. They need to be run in cronological order. Only after running all the subfolders are run should the sql scripts that are placed directly in the folder etc/database_operations be run. Doing this by hand can be a nightmare, that gets worse the more time goes by between upgrades (this is because the more time goes by, the more sql scripts need to be run). To help this process we provide a litle tool that produces a single shell script that will run each sql file in the correct order. To run this tool you must specify the first date of sql scripts you wish to run. So for example, if your previouse verion was tagged on 2005-12-26, then you would need to run every sql script after that date, so you would use the following instruction:

  mvn -Dfull-run-file.from=2005-12-27 fenix:full-run-file

This will produce a bash shell script called run in the directory etc. Invoke this shell script passing two arguments (the name of the database the username to use to access the database), for example:

  sh run fenix marvin 

This shell script will prompt you for the password.

Finally, compile the updated code, and deploy it to the webcontainer, and that's it.

Usually, the above described a regular update process, however, if your upgrading from a version prior to 2006-12-20 to later version, then you have to do the update process twice. The scripts that update the data repository are "always" sql scripts, or at least the should be. This will be corrected with this "two-phase" update. So if your upgrading from a version prior to 2006-12-20 to later version, don't update directly to the later version. First update to the tag D2006_12_20_16h36, run the sql scripts as described above, and then run the following java script from the scripts project:

  ant -f build_run_once.xml FillGroupExpressionValues

Next, update normally to the pretended later version as usual.

Remarks