Locked History Attachments

GettingStartedFenix

Howto setup FÉNIX for development


Intention

The purpose of this page is to give a rough idea of the necessary steps to setup a development environment for working on the Fénix project. While it is perfectly possible to work with any java compatible IDE, here we will focus on using Eclipse.

Ubuntu

This is a quick tutorial to get you ready for the development in the Fénix Project, using Ubuntu.

You may install another distribution of linux if you prefer, most of the steps below are alike in other distros.

1. Install Ubuntu

(NOTE: When installing Ubuntu, please make sure to use other filesystem than ext4 due to limit length of filenames. The XFS is suggested)

(If you choose the partitions manually, remember to create a swap partition of at least 4GB+)

Inside your home folder, create the folders: programs/ scripts/ and workspace/

2. Install mysql

- sudo apt-get install mysql-server (if there is an error installing this package on Ubuntu, install mysql-server-5.5 or the latest version, manually)

- Follow the tips at MySQLOptimizations to configure your mysql server.

  • (The file you'll have to change is /etc/mysql/my.cnf)

- Create a database for fenix called "ciapl":

create database ciapl;

- Download the fénix dump file, extract it and import the dump file into the local mysql database:

It is recommended that you do this at the end of the day (may take several hours)

Follow the instructions from Loading_Test_Data

  • (There are access restrictions to the database dump, ask your colleagues if you have no access.)

3. Install Java 8

http://www.oracle.com/technetwork/java/javase/downloads/index.html

Create a Programs/ folder inside your home folder and extract the tar.gz file inside

4. Install Maven 3

Download maven from apache:

http://maven.apache.org/download.cgi

- Extract the tar.gz to your programs folder

Check if maven was properly installed:

$ mvn --version

After asking for an account on nexus, you will need to run a shell script that will magically connect your workstation to nexus.
Create a file called mvn-passwd.sh:

$ nano -w mvn-passwd.sh

Paste in this text:

istid=$1
istpass=$2

function addserver {
  echo "    <server>
      <id>$1</id>
      <username>$istid</username>
      <password>$2</password>
    </server>" >> ~/.m2/settings.xml
}

function set_master_pass {
  master=$(LC_ALL=C; cat /dev/urandom | tr -dc "a-zA-Z0-9-_" | head -c 8)
  echo "<settingsSecurity>
  <master>$(mvn --encrypt-master-password $master)</master>
</settingsSecurity>" > ~/.m2/settings-security.xml
}

function create_servers {
  pass=$(mvn --encrypt-password $istpass)

  echo "<settings xmlns=\"http://maven.apache.org/SETTINGS/1.0.0\"
    xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
    xsi:schemaLocation=\"http://maven.apache.org/SETTINGS/1.0.0
                         http://maven.apache.org/xsd/settings-1.0.0.xsd\">
    <servers>" > ~/.m2/settings.xml
  addserver "fenix-ashes-private" $pass
  addserver "fenix-ashes-releases" $pass
  addserver "fenix-ashes-snapshots" $pass
  addserver "fenix-core-releases" $pass
  addserver "fenix-core-snapshots" $pass
  addserver "fenix-framework-releases" $pass
  addserver "fenix-framework-snapshots" $pass
  echo "  </servers>
  </settings>" >> ~/.m2/settings.xml
}

set_master_pass
create_servers

And finally just run it:

$ ./mvn-passwd.sh <ISTID> <PASSWORD>

... and clear the bash history:

$ clear
$ history -c

(The script credits go to João Antunes <joao DOT antunes AT tagus DOT ist DOT utl DOT pt> )

Finally, open the file in ~/.m2/settings.xml with a text editor. Inside the <settings> tag, but after the </servers>, insert the following:

    <mirrors>
        <mirror>
          <id>Fenix Ashes Maven Repository</id>
          <name>Fenix Ashes Maven Repository</name>
          <url>https://fenix-ashes.ist.utl.pt/nexus/content/groups/fenix-ashes-maven-repository/</url>
          <mirrorOf>central</mirrorOf>
        </mirror>
    </mirrors>

   <profiles>
       <profile>
           <id>nexus</id>
           <!--Enable snapshots for the built in central repo to direct -->
           <!--all requests to nexus via the mirror -->
           <repositories>
               <repository>
                   <id>central</id>
                   <url>http://central</url>
                   <releases><enabled>true</enabled></releases>
                   <snapshots><enabled>true</enabled></snapshots>
               </repository>
           </repositories>
           <pluginRepositories>
               <pluginRepository>
                   <id>central</id>
                   <url>http://central</url>
                   <releases><enabled>true</enabled></releases>
                   <snapshots><enabled>true</enabled></snapshots>
               </pluginRepository>
           </pluginRepositories>
       </profile>
    </profiles>
 
    <activeProfiles>
        <!--make the profile active all the time -->
        <activeProfile>nexus</activeProfile>
     </activeProfiles>



5. Install and configure apache-tomcat 7

(Same as above)

In the tomcat folder, edit the file: /conf/server.xml

Edit the line with: <Connector port="8080" protocol="HTTP/1.1"

  • connectionTimeout="20000"

    redirectPort="8443" >

to the following: <Connector port="8080" protocol="HTTP/1.1"

  • connectionTimeout="20000"

    redirectPort="8443" URIEncoding="UTF-8">

6. Edit the .bashrc file

- Open the .bashrc file in your home folder (visible with Ctrl+H or "ls -a")

- At the end of the file, enter the following lines (change the first 4 lines if necessary):

# FenixEdu development properties for java, ant, maven, and tomcat

export DEFAULT_USER="user"
export PROGRAMS="/home/$DEFAULT_USER/programs"
export SCRIPTS="/home/$DEFAULT_USER/scripts"
export WORKSPACE="/home/$DEFAULT_USER/workspace"



export JAVA_HOME="$PROGRAMS/jdk1.7.0_11"
export JAVA_OPTS="-server -da -dsa -Xms2048m -Xmx2048m -XX:PermSize=256m -XX:MaxPermSize=512m -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:ParallelGCThreads=2"

export ANT_HOME="$PROGRAMS/apache-ant-1.8.4"
export ANT_OPTS=$JAVA_OPTS

export MAVEN_HOME="$PROGRAMS/apache-maven-3.0.4"
export MAVEN_OPTS=$JAVA_OPTS

export CATALINA_HOME="$PROGRAMS/apache-tomcat-7.0.35"
export CATALINA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Dfile.encoding=UTF-8"
export JPDA_TRANSPORT="dt_socket"
export JPDA_ADDRESS="8000"

export PATH="${PATH}:$JAVA_HOME/bin:$ANT_HOME/bin:$MAVEN_HOME/bin:$CATALINA_HOME/bin:$SCRIPTS"

8. Install Eclipse

- Download the latest version of Eclipse IDE for Java EE Developers: http://www.eclipse.org/downloads/

- In eclipse.ini, at the end of the file, edit the following lines:

-Xms512m
-Xmx1024m

- Perform the following operations:

mkdir $PROGRAMS/eclipse/jre/
mkdir $PROGRAMS/eclipse/jre/bin/
ln -s $JAVA_HOME/jre/bin/java $PROGRAMS/eclipse/jre/bin/java

- Launch Eclipse for the first time, type in your Workspace folder, check "Use as default" and press OK

- Change the Eclipse's perspectives and views to your liking (Java with Navigator view, Debug, Team Synchronizing...)

9. Install Maven Eclipse Plugin

  • - In Help > Install New Software, search for "m2e" in All Available Sites - Install "m2e - Maven Integration for Eclipse", under "Collaboration".

11. Checkout the fenix source code

- Right click on your Navigator window, and click New > Project...

- Choose "Project from SVN"

- Choose(add) the repository https://fenix-ashes.ist.utl.pt/ksvn

- Click "Browse..." and choose the fenix folder (should be inside the trunk)

- Press "Finish", checkout the project with the name "fenix", and "Finish" again

12. Configure Eclipse

- Copy Workspace/fenix/EclipseFenixCodeSyle.xml to eclipse's install folder.

- Inside Eclipse, Window > Preferences; Java > Code Style > Formatter, press "Import..." and choose the copy of EclipseFenixCodeSyle.xml.

- Still in the preferences, in Java > Editor > Save Actions, check: "Perform the selected actions on save", "Format source code", "Organize imports", "Additional actions", and press "Configure...".

- In Code Style, check "Use Blocks in if/while/for/do statements", "Convert for loops to enhanced", and "Use modifier 'final' where possible: 'Private Fields'"

- In Missing Code, check all the options

- In Unnecessary code, check "Remove unnecessary casts", and "Remove unnecessary $NON-NLS$ tags"

- The resulting "Additional actions" should now look like this:

  • Convert control statement bodies to block
  • Convert 'for' loops to enhanced 'for' loops
  • Add final modifier to private fields
  • Add missing '@Override' annotations
  • Add missing '@Override' annotations to implementations of interface methods
  • Add missing '@Deprecated' annotations
  • Remove unnecessary casts
  • Remove unnecessary '$NON-NLS$' tags

- In Java > Editor > Typing, check "Semicolon" and "Braces"

- In General > Editors > File Associations, add a new file type of '*.dml', and associate it with the Java Editor.

- In General > Editors > Text Editors, check "Show line numbers"

- In General > Editors > Text Editors > Spelling, uncheck "Enable spell checking"

- In General > Content Types, expand the "Text" node, and for each child node, set the encoding "UTF-8", except for "Java Properties File" which should have the encoding "ISO-8859-1

- In General > Search, uncheck "Reuse editors to show matches" (optional)

13. Configure fénix to execute locally with tomcat

- Right click on fénix project > Properties, Java Build Path, Source; remove "fenix/src_remote" and "fenix/src_gen_remote"

- Copy fenix/src/main/resources/configuration.properties.sample to fenix/src/main/resources/configuration.properties, and edit the following line:

filter.request.with.digest=false

- In the shell, in workspace/fenix:

mvn clean package

- If you want to run Jetty, to be able to change .jsp files on-the-fly, check the fenix/README file for more information

- Return to Eclipse and refresh the project in the workspace

  • (if you get a NullPointerException while "Refreshing external folders", try closing the project and opening it again)

- Create a symbolic link to the fénix web folder in the tomcat webapps folder with (change folders/versions if necessary):

ln -s -T $WORKSPACE/fenix/target/fenix-1.0-SNAPSHOT $CATALINA_HOME/webapps/ciapl

To start tomcat, stop it, and view the logs, use, respectively:

catalina.sh jpda start
catalina.sh stop
tail -f $CATALINA_HOME/logs/catalina.out

(jpda makes the tomcat initialization slower, but allows you to connect a debugger)

After starting tomcat, you may access fenix locally using this link:

http://localhost:8080/ciapl/loginPage.jsp

14. Configure Eclipse to run in debug mode with tomcat

- Change to the debug prespective

- Click on the down arrow, on the right side of the green bug icon > Debug Configurations...; right click in Remote Java Application > New

  • Name = "fenix-debug" Project = "fenix"

- Save the debug configuration by pressing "Debug"

(If the "Errors in workspace" message appears, choose: "Launch anyway and do not show this message again")

(If the "Connection refused" message appears, it just means that you forgot to start tomcat before launching the debug on Eclipse.)

(to launch the debug mode later, just press the down arrow and click on "1 fenix-debug")

(OPTIONAL) Install the ResourceBundle plugin

- Follow the instructions from the first paragraph of I18NConventions


Useful Links:

http://fenix-ashes.ist.utl.pt/fdb/ - Graphical fenix domain browser

https://rt.ist.utl.pt/ciist/ - RT ticket management

Trac project pages for fenix and related frameworks:

https://fenix-ashes.ist.utl.pt/trac/fenix

https://fenix-ashes.ist.utl.pt/trac/fenix-framework

https://fenix-ashes.ist.utl.pt/trac/fenix-web-framework


After having the system fully installed, it is advisable to keep the source code and local database schema updated.

On a daily basis, you should:

- Update the fénix source code, by right clicking on the fénix project > Team > Synchronize with Repository

  • (Agree to change to the Team Synchronizing perspective)

- Solve any conflicts and make sure the last version of the code compiles correctly.

- Run the new mysql scripts in workspace/fenix/etc/database_operations; On the shell, for each folder:

chmod +x *
./run ciapl root localhost IST

(in Ubuntu, if you always do these 2 commands together, scripts that have already been executed will be shown in green, and new ones in white)


FINAL IMPORTANT NOTES:

BEFORE COMMITTING CODE:

- Test the changes that you made to the application (exhaustive tests are not necessary)

- Review your code changes, and refactor if necessary.

- Update the source code one last time, solve any conflicts and recompile the code if necessary.

DURING the COMMIT:

- Verify that you are commiting the correct files.

- Write a detailed commentary, describing your changes, in English.

- Start the comment with "Minor Change:", "Refactor:", "Bug fix:", or "New feature:".

- Commit.


Under Windows

- Edit server.xml in ${CATALINA_HOME}/conf and add under <Host> element:

<Context docBase="<workspace>/fenix/web" path="/ciapl" debug="0" reloadable="true" />

Alternate setup for windows:

- Format your PC to avoid infestation.

- Install linux.

- Follow steps 1-12.


After completing this tutorial, to install the myorg application, follow the instructions at Setting up myorg for development

To configure the fenix remote plugin, follow the instructions at Configuring the fenix remote plugin