Setting Up A Development Environment

The DDMS build system is ant based. Our preferred development IDE is Eclipse, coupled with AspectJ weaving plugins. The database is Postgres with PostGIS.

Install Eclipse

Install Eclipse

Go to the Eclipse downloads website and install Eclipse Enterprise Edition. Most likely you don’t want to install the latest version of Eclipse because it may have issues with the AJDT plugin. Check this site first to see what version of Eclipse to download:

Install AJDT

1. Install a version of AJDT that is compatible with your Eclipse. You need to make sure the version numbers line up. This is an Aspect weaving plugin which we use on the server project primarily to assist with transaction and request management.
2. In Eclipse go to ‘help -> Install New Software’
3. Enter this URL in the input field ‘http://dist.springsource.org/release/AJDT/configurator/’

Install Oracle Java 8

It is not required to install Oracle Java into your Eclipse, however it is recommended because the GeoRegistry is tested with Oracle java and is not guaranteed to work with the Open JDK. Additionally, Oracle java is faster than the open source competitors. Therefore, we recommend installing Oracle Java 8 and configuring your Eclipse to use it.

Install The Database Software

The DDMS currently only supports PostgreSQL 9.5.

1. Install PostgreSQL 9.5 using whatever method you prefer.
2. Install PostGIS 2.2+ into your PostgreSQL.

Install Tomcat 8.5

1. Download and extract Tomcat 8.5 to a local directory on your filesystem. Do not use Eclipse WTP to download and manage Tomcat, our ant scripts do not support it.
2. Download GeoServer 2.9.1 from here and place it into Tomcat's webapps directory.
3. Download ODK Aggregate from here and place it into Tomcat's webapps directory. Rename the war file to be 'DDMSMobile.war'.
4. Download these jars and place them into your tomcat/lib directory.
   • credentialsSingleton.jar
   • runwaysdk-tomcatcl

Download and Load the DDMS Into Eclipse

1. Load DDMS Into Eclipse

The DDMS Github project currently uses git lfs. Mostly that is to support the build system, you don't need it for local development.

1. Clone the DDMS locally
   • git clone https://github.com:terraframe/ddms.git
2. Open Eclipse and import the DDMS directory (DDMS/DDMS). This DDMS repository is divided into many different sub-projects. The DDMS project is the core DDMS webapp, the rest are supporting projects.

2. Configure the DDMS

1. The root database credentials are set in the profiles/default/server/database.properties.
2. Set a path to your tomcat installation by setting deploy.root in profiles/default/common/terraframe.properties
3. Set a path to your DDMS project by setting local.root in profiles/default/common/terraframe.properties
4. If you need to change your database port you may do so in profiles/default/server/database.properties
5. Set your databaseBinDirectory in database.properties
   1. On mac with the postgres app mine resolves to: /Applications/Postgres.app/Contents/Versions/9.6/bin
6. Change your site to the site of the backup. This means setting the domain property in terraframe.properties. If you don't know the site of your backup, try setting it to 0.mdss.ivcc.com. When the backup import runs, if you get an error of com.runwaysdk.dataaccess.SiteException, it will tell you what site to use.
7. Set default in profiles/default/server/vault.properties and profiles/deploy/server/vault.properties to <the path of your DDMS project>/vault.
8. Find and replace mdssdeploy with mdssdevelop in profiles/default and profiles/deploy.

Do not ever commit these changes.

Build your database

The DDMS database can be built from a backup using a class called the BackupDevImporter. This Java class will restore the backup and patch it using your latest metadata and localization / term data / etc. Any required generated source will be extracted to src/backup. After running this class, the updates can be deployed to Tomcat using our ant build system. If you don't already have a production backup to import, you may use this backup, which was produced from a "fresh install", which does not have any data in it.

1. Add your password to a ~/.pgpass file with host 127.0.0.1 (NOT LOCALHOST) that the psql import process will use when importing the sql files. If your pgpass file doesn't exist, that is OK. Just create the file, and put this line in it: 127.0.0.1:5432:mdssdevelop:mdssdevelop:mdssdevelop

   Make sure to chmod it: sudo chmod 600 ~/.pgpass

2. Create user mdssdevelop

3. Create a new database of name mdssdevelop with owner: mdssdevelop

4. Modify your database search_path to ddms,public: ALTER DATABASE mdssdevelop SET search_path=ddms,public; alternatively: ALTER ROLE mdssdeploy SET search_path = ddms,public;

5. Install the postgis extension: CREATE EXTENSION postgis;

6. Install another extension: CREATE EXTENSION fuzzystrmatch

7. Build your DDMS project using Eclipse

8. Create an Eclipse launch to run the BackupDevImporter. Set the first and only argument as an absolute path to the backup zip on the filesystem.

9. Compile and deploy the new source we just loaded from the backup to your tomcat server

Deploy and run Tomcat

The primary build system of the DDMS is ant. There is a launch in DDMS/launches called DDMS - Deploy.launch. Run this launch and it will deploy the DDMS to your Tomcat which you configured earlier in profiles/default/common/terraframe.properties.

Once the deploy finishes, open up a terminal and cd to the tomcat/bin directory. Run the startup.sh to start tomcat, and shutdown.sh to stop it. The webserver will be available at http://localhost:8080/DDMS.