How To Set Up A Development Environment

Webapp Development

Pre-requisites

• Install NodeJS and NPM (Node Package Manager) - NPM is now included in the NodeJS install, so this is only one installation

Initialise

• Once the source code for the cpm module has been cloned, go to the root directory and run (Mac or *nix may require sudo):

  $ npm install -g

Eclipse Setup [obsolete?]

• Import OpenMRS into Eclipse as a maven project
• Setup a Maven run configuration:
  • Add the goal jetty:run
  • Add the following recommended jvm args to the "JRE" tab: -Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512m -XX:NewSize=128m
  • Optional: To allow the module to be debugged add the necessary module folders in the "Source" tab of the run configuration

Streamlining edit-compile-run cycle

Option 1: Adding modules directly to core code's webapp directory

• Link/copy the module's build artifact to <openmrs>/webapp/src/main/webapp/WEB-INF/bundledModules I've added an ant task to the module's pom to remove the old artifact from bundledModules and copy the new one across rather than use a softlink as the build number keeps changing. See below for the snippet.
• To include bundledModules to Jetty's auto reload scanpath, add <scanTarget>src/main/webapp/WEB-INF/bundledModules</scanTarget> to the jetty config in <openmrs>/webapp/pom.xml.

Option 2: Using OMOD Reloader

• Install the OMOD Reloader module into your test OpenMRS instance
• Restart OpenMRS with the flag: -Domodreloader.paths=/path/to/openmrs-cpm/omod/target
  • With maven & jetty this is done with export MAVEN_OPTS="-Domodreloader.paths=...."
• Whenever the omod file in the target directory is updated, the OMOD reloader will reload the OpenMRS context

Running from Command Line

• Set recommended memory for jetty with (in bash): export MAVEN_OPTS="-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512m -XX:NewSize=128m"
• Run mvn jetty:run from <openmrs-dir>/webapp
  • Jetty port can be changed with -Djetty.port=8000
• Optional: attach a debugger with: export MAVEN_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=4000,server=y,suspend=y" (ref http://docs.codehaus.org/display/JETTY/Debugging+with+the+Maven+Jetty+Plugin+inside+Eclipse)

Ant task for copying build artifact

Notes:

• Do a mvn clean after the build number changes so as not to copy older omods across
• For some reason the ant task wasn't executing from within Eclipse so for now I'm running on the command line
• When packaging the module speed up the cycle, skip the tests with mvn -DskipTests=true package

Below is the ant task that I've added to the module's omod/pom.xml (it must be added to omd/pom.xml!)

Add the following to <dependencies>

<dependency>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-antrun-plugin</artifactId>
  <version>1.7</version>
  <type>maven-plugin</type>
</dependency>

Add the following to <build><pluginManagement><plugins>. (added by Michael Lee, because my Ant target didn't fire without this)

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-antrun-plugin</artifactId>
  <version>1.7</version>
</plugin>

Add the following to <build><plugins> and update with the openmrs dir.

<plugin>
  <artifactId>maven-antrun-plugin</artifactId>
  <executions>
    <execution>
      <phase>package</phase>
      <configuration>
        <target>
          <delete>
            <fileset dir="openmrs-dir/webapp/src/main/webapp/WEB-INF/bundledModules">
              <include name="cpm*.omod"/>
            </fileset>
          </delete>
          <copy todir="openmrs-dir/webapp/src/main/webapp/WEB-INF/bundledModules">
            <fileset dir="target">
              <include name="*.omod"/>
            </fileset>
          </copy>
        </target>
      </configuration>
      <goals>
        <goal>run</goal>
      </goals>
    </execution>
  </executions>
</plugin>

How to auto login

• Not sure how to get FF or Chrome to differentiate between urls in a domain but LastPass does and auto logs in