Overview

Documents setting up code, config, and data in a development environment using Eclipse.

 

Prerequisites

As this project is organized around Maven and may make use of resources on IHTSDO Nexus, properly configure your Settings.xml Page.

Details

Step 1 - Create directories

  Setup for Windows

  • Create a directory to hold your data files (e.g. c:/mapping/data)
  • Create a directory to hold your config files (e.g. c:/mapping/config)
  • Create a directory to hold the code (e.g. c:/workspace/OTF-Mapping-Service)
  • Make sure the "mvn" executable for your local maven installation is in the path
    • On Windows this means adding to the PATH variable so that it runs in a "cmd" shell without fully qualified path.

  Setup for Unix/Linux/Mac

  • Create a directory to hold your data files (e.g. ~/data)
  • Create a directory to hold your config files (e.g. ~/config)
  • Create a directory to hold the code (e.g. ~/code)
  • Make sure the "mvn" executable for your local maven installation is in the path

Step 2 - Clone repositories

Clone the Github repository to the directory created to hold the code.

Clone the mapping tool data project (e.g. https://git.ihtsdotools.org/ihtsdo/ihtsdo-mapping-tool-data.git) to the directory created to hold your data files. You'll need an account on git.ihtsdotools.org for this - contact techsupport@ihtsdo.org for an account.

Step 3 - Build project

Build all project modules with "mvn clean install" at the top level - either through Eclipse or via the command line.

  • NOTE: this uses the standard "dev-windows" configuration.  To use a different configuration artifact pass the following three parameters:
    • -Dconfig.groupId=...
    • -Dconfig.artifactId=...
    • -Dconfig.version=...
  • NOTE: the specified configuration artifact must either have been built locally or be an a repository accessible based on the settings.xml file
  • NOTE: index viewer data is similarly configured.  Stock config files reference release versions of index viewere data hosted on https://nexus.ihtsdotools.org.  Consider adding this as an extra repository in your settings.xml
  • For most dev deployments, the default build is fine because the only setting really used for the rest/webapp packages is the "base.url" which by default is set to http://localhost:8080/mapping-rest.
  • For a UAT or production deployment, you would want to use a different setting.  For example, see Deploy Instructions, the prod deployment instructions.


Step 4 - Setup Configuration

Choose a "dev-windows", "uat", or "prod" config project target and unzip it into the directory created to  hold your config files.

  • config/dev-windows/target/mapping-config-dev-windows.*.zip
  • config/prod/target/mapping-config-prod.*.zip
  • config/uat/target/mapping-config-uat.*.zip
     

Step 5 - Edit configuration

Edit the "config.properties" file in your config files directory to set correctly for your environment.  In particular, edit these:

  • javax.persistence.jdbc.url
  • javax.persistence.jdbc.user
  • javax.persistence.jdbc.password
  • hibernate.search.default.indexBase  ( recommend choosing something in your data dir, e.g. c:/mapping/data/indexes or ~/indexes)
  • ihtsdo.security.activated (set to false for dev environment)
  • mail.smtp.to (list for automated system emails)
  • send.notification.recipients (list for automated tools, like reports generation and database qa)

Step 6 - Create database

Create a MySQL UTF8 database. e.g.

CREATE database mappingservicedb CHARACTER SET utf8 default collate utf8_unicode_ci;

 


Step 7 - Load data

Run the admin loader script for your platform.  In your config/src/main/resources/bin directory there will be a handy loader script that sets up a basic dev environment based on the data provided from the "mapping-service-data" CollabNet project.

  • Edit the file to set the MAPPING_CODE, MAPPING_CONFIG, and MAPPING_DATA properties
  • Run appropriate script for your platform (only one will be available, depending on the configuration settings you unpacked in Step 4).
    • load.bat - for Windows
    • load.sh - for Unix/Linux/Mac

NOTE: if re-running this, you first have to run the sql in "truncate_all.sql" to clear your database of tables.

Download and unpack the data file (mapping-demo.zip) into your data directory (e.g. c:/mapping/data): 

mapping-demo.zip

Run the "Reset Demo Database" integration-test. You must specify 3 parameters:

  • run.config=c:/mapping/config/config.properties
  • skipTests=false
  • maven.home=c:/apache-maven-3.3.9

See images below to set up a JUnit run configuration that will generate your demo database.


Step 8 - Deploy wars

Deploy the mapping-rest.war file to a Tomcat server - either through Eclipse or a standalone tomcat installation.

Setting up Tomcat in Eclipse is very easy, you follow these steps.

  • Download and install apache tomcat 7 in c:/apache-tomcat-XXXX
  • In Eclipse use the J2EE perspective and click on the "Servers" tab.
  • From here, you can add a server which simply involves pointing Eclipse to the Tomcat install directory.
  • You can right-click on term-server-rest.war file and use "Run As->Run on Server" to deploy to Tomcat.
    • NOTE: sometimes in Eclipse this doesn't work and the tomcat does not properly recognize or deploy the app.
    • In this event, double-click on the tomcat server installation in the servers tab.
    • In the configuration screen click "Open launch configuration"
    • There, look on the Arguments tab and find the -D setting for "catalina.base", e.g.

       

      -Dcatalina.base="C:\Users\Brian Carlsen\workspace-luna\.metadata\.plugins\org.eclipse.wst.server.core\tmp0"
    •  If you open this directory you'll see a "webapps" folder.  To deploy you simply build and copy the  war files to that directory and launch the server in Eclipse.
       
  • The Tomcat server needs to be able to find the configuration file from step 3. Double-click on the Tomcat server you installed, open the launch configuration and add this setting to the "Arguments" tab:

     

    -Drun.config=/path/to/your/config.properties

Step 9 - Test

Check that it all works by going to

http://localhost:8080/mapping-rest/index.html 

This should be the login page for the application. If you have security disabled, you should be able to log in using a username and matching password of 'lead1' or 'specialist1' or any of the usernames listed in the config.properties file.

 

 

 


  • No labels