Skip to content

Bgee apps installation

Jump to bottom
Sebastien Moretti edited this page Oct 2, 2017 · 4 revisions

Table of content:

Environment

Git

The Bgee application is versioned using Git. Version >= 1.7.0 is recommended.

Java

You need to install a JDK version 7, see JDK download page, the JDK 7 is down the page.

The project is currently configured to be compiled in Java 7, because we have not yet installed Java 8 on all our servers. So you absolutely need a JDK 7. See Maven configuration for more information.

Maven

Install Maven (mvn command in terminal). Any non-prehistoric version should be fine.

Eclipse

Recommended IDE is Eclipse:

  • Install Eclipse IDE for Java EE Developers (see Eclipse download page). You need the "Mars" version (there is a problem of type resolution in lambda expression in Eclipse Luna).

  • Install m2e (a connector between Maven and Eclipse)

  • Install m2e-wtp (a connector between m2e and the Eclipse Web Tools Project (WTP))

MySQL

If you want to be able to run integration tests (not mandatory), you need to install a MySQL database somewhere, version >= 5.6 (hmm, version >= 5.0 should be fine).

Configuration/Installation

Maven

Minimal configuration

(Note: remove this step after moving to Java 8)

  • Bgee is currently built using Java 7 (see Java section), so you need to define properties to indicate where your Java 7 home is on your computer (these properties are then used in the Bgee Maven configuration file, BGEE_APPS_HOME/pom.xml).

  • To do so, you need to edit a settings.xml configuration file, either in your ~/.m2 directory, or in the MAVEN_HOME/conf directory (e.g., /usr/share/maven/conf). Such a file should already exist in these directories.

  • You can ALSO use the pre-configured settings.xml files available in the repository: BGEE_APPS_HOME/bgee-webapp/ (see https://stackoverflow.com/questions/1261215/maven-command-to-determine-which-settings-xml-file-maven-is-using)

mvn install --settings BGEE_APPS_HOME/bgee-webapp/settings_prod.xml
  • You need to edit the <profiles> and <activeProfiles> sections:
<settings>
  ...
  <profiles>
    ...
    <profile>
      <id>bgee-compiler</id>
      <properties>
        <JAVA_1_7_HOME>/path/to/java/7/home (e.g., /Library/Java/JavaVirtualMachines/jdk1.7.0_71.jdk/Contents/Home)</JAVA_1_7_HOME>
        <JAVA_1_7_BOOTCLASSPATH>/path/to/java/7/bootclasspath (e.g., /Library/Java/JavaVirtualMachines/jdk1.7.0_71.jdk/Contents/Home/lib/*.jar)</JAVA_1_7_BOOTCLASSPATH>
      </properties>
    </profile>
  ...
  </profiles>
  ...
  <activeProfiles>
    <activeProfile>bgee-compiler</activeProfile>
    ...
  </activeProfiles>
  ...
</settings>

Build the project

When building the project, Maven will put all the built files in the target/ directory of each module (e.g., the Bgee webapp WAR file will end up in BGEE_APPS_HOME/bgee-webapp/target/).

  • To fully build the entire project, but skipping integration tests and javadoc generation, go to the root directory of the project (denoted as BGEE_APPS_HOME), and run the command:
mvn clean install -DskipITs -Dmaven.javadoc.skip=true

(Integration tests require by default a local MySQL database running, and to follow the advanced configuration steps; however, unit tests will still be run using this command. Javadoc generation currently requires to have the JDK 8 intalled, with JAVA_HOME var pointing to it; I won't go into details here, but we will completely move to Java 8 soon anyway, this will avoid this problem)

  • To build the entire project, running all tests, skipping javadoc:
mvn clean install -Dmaven.javadoc.skip=true
  • Super-combo-lazy command, skipping all tests (even the unit tests), javadoc generation, and building only the module bgee-webapp:
mvn clean install -DskipTests -Dmaven.javadoc.skip=true --projects bgee-webapp

(See more command examples in the Maven tips section)

Eclipse import

First, make sure to have followed the minimal configuration step for Maven. Then, import the Bgee project:

  • in the Eclipse menu: File > Import > Maven > Existing Maven Projects; select the root directory of bgee-apps. That's it.
  • By default, we have disabled workspace resolution for Maven dependencies. Keep it that way (do not commit changes in the Eclipse configuration files versioned by Git). To verify this setting, in Eclipse you can right click on each Bgee Maven module (BGEE_APPS_HOME, bgee-core, bgee-dao-api, bgee-dao-sql, bgee-pipeline, and bgee-webapp), and select: Maven > Disable workspace resolution. If you see Enable workspace resolution, then it's fine.
  • Note that Git is fully integrated within Eclipse. However, each time you use git checkout to change branch, you should rebuild the project in Eclipse if you want to use a command such Run As > Run on Server (to rebuild the project, select the modules you want, right click, then Maven > Update project, check Force Update of Snapshot/Releases, press OK)

Troubleshooting/Tips

Maven troubleshooting

  • If you have the error:
Unable to find javadoc command: The environment variable JAVA_HOME is not correctly set

Just set your JAVA_HOME (on Mac: export JAVA_HOME=$(/usr/libexec/java_home))

  • If you have never built the entire project yet (use of --projects option to build only specific modules), Maven might complain about missing dependencies when building a specific module. Go to the directory BGEE_APPS_HOME/m2_local_repository/ and run the script mvn-install-file.sh (you really need to run it from that directory). This is because they are not in the central Maven repository, they are automatically installed when building the root project BGEE_APPS_HOME, not when building some specific modules.

  • If you get an OutOfMemory error, you need to increase the java heap space, through the MAVEN_OPTS var, that allows to provide options to the JVM. For instance, use:

   export MAVEN_OPTS="-Xmx2g"; mvn clean install

This cannot be done in the pom.xml, because the JVM is already started when the pom.xml is read. It is possible to configure the maven-surefire-plugin in the pom.xml, to increase heap space for unit tests, but then the build after unit tests might fail with an OutOfMemory error.

This should be required only if you run the build on a machine with low memory.

Maven tips

  • To build only specific modules:
mvn clean install --projects bgee-dao-api,bgee-dao-sql,bgee-core,bgee-webapp
  • To skip all tests (both unit and integration):
mvn clean install -DskipTests
  • To skip unit tests but run integration tests:
mvn clean install --Dskip.surefire.tests=true
  • To skip javadoc generation:
mvn clean install -Dmaven.javadoc.skip=true

Explanations about Maven phases

Note: the order of the phases of the maven build cycle is: validate, compile, test, package, integration-test, verify, install, deploy. If you launch a phase, all previous phases will be executed. So:

  • if you want to run only unit tests, use:
mvn clean test
  • if you want to package the applications (as jar or war file depending on the module):
mvn clean package
  • if you want to run integration tests:
mvn clean verify

As you can see from the order of the phases, this command would also execute unit tests, and package the applications.

  • if you want to install the applications in your local repository, to be used as dependency:
mvn clean install

Based on the order of the phases, this command would execute unit tests, and integration tests. Note that we have attached the generation of the javadoc and of the source jar to this install phase.

Eclipse troubleshooting

  • If you have never built the project from the command line yet, Eclipse will complain about missing dependencies (because they are not in the central Maven repository; they are automatically installed when building the project from the command line):

    • go to the directory BGEE_APPS_HOME/m2_local_repository/ and run the script mvn-install-file.sh (you really need to run it from that directory);
    • then, in Eclipse, you can right click on the module, and select Maven > Update project, and check Force Update of Snapshot/Releases.

  • If Eclipse complains about not finding a compiler for Java 7, you can point to your Java 7 home. Go to Preferences > Java > Installed JREs, and edit the values for Java SE 7.

  • After updating a pom.xml, or a repository, etc, a simple "refresh" in Eclipse might not be sufficient. In that case, right click on the project, Maven > Update project. Check Force update of Snapshots/Releases if you use snapshot dependencies (we do).

  • If a modification of the source code of a module is not seen in another module, it is because we disabled workspace resolution in Eclipse. You need to compile the source code and make it available in the local Maven repository each time you want the changes to be reflected (see Maven tips for a command skipping tests, javadoc, and to target only a specific module).

  • If a library present in the Maven local repository is not seen in Eclipse: Window > Show View > Other. Select Maven repositories. From the new view, right click on the Local repository and select Rebuild index. If the option is not available, turn on the option Full index enabled. Do the same for all bgee-local-repository listed under Project repository.

  • If modifications of a library in the Bgee m2 local repository is not seen by the project, check that you don't have also the dependency in your maven default repository (~/.m2/repository/), as it would override the version in the Bgee local repository.

  • If a class of a library in the bgee m2 local repository is not seen by the project, it might also be because the workspace resolution is turned on, the project corresponding to the library exists in the workspace, but not the class you try to use (while the class does exist in the library in the repository). In that case, turn off workspace resolution.

Eclipse tips

  • To launch a Maven build from Eclipse, select Run configuration > Maven Build from the left menu.

  • To change an already existing project into a maven project, right click on the project > Configure > Convert to Maven Project.

Advanced configuration

Bgee Maven project

  • If you'd like to run integration tests, you need an additional configuration (note: you will still be able to run unit tests in any case; but integration tests depend on the machine environment, this is why you need to add a configuration in your settings.xml file).

  • For these integration tests, you will need a MySQL database running (Maen won't start it for you), and you need to provide the root username and password in your settings.xml (see below).

  • You'll also need to have the R software installed, notably, its command line script.

  • Example settings.xml:

<settings>
  ...
  <profiles>
    ...
    <profile>
      <id>bgee-integration-test</id>
      <properties>
        <bgee.database.root.username>rootUsername</bgee.database.root.username>
        <bgee.database.root.password>rootPassword</bgee.database.root.password
        <it.org.bgee.core.topAnatRScriptExecutable>/usr/bin/Rscript</it.org.bgee.core.topAnatRScriptExecutable>
      </properties>
    </profile>
  ...
  </profiles>
  ...
  <activeProfiles>
    <activeProfile>bgee-integration-test</activeProfile>
    ...
  </activeProfiles>
  ...
</settings>
  • If the MySQL server used for running integration tests is not on your machine, or does not use the default port, you should provide the JDBC connection URL to connect to the server. The property is bgee.jdbc.connectionURL. Default value is jdbc:mysql://127.0.0.1/. Note that this URL should not contain any database name or properties, and should be solely defined for MySQL (needs to start with jdbc:mysql, do not parameterize log4jdbc here for instance). Example:
mvn verify -Dbgee.jdbc.connectionURL=jdbc:mysql://myOtherHost/
Clone this wiki locally