Installing MOTECH for Developers (“Official” Method)

Installing on Ubuntu

The versions below may change, most likely the latest stable release will work for your purposes. If they do not, please feel free to send in feedback.

  1. Install Ubuntu Desktop 12.04.2 LTS 64bit

    Installation instructions


    64-bit is required for Motech’s installation

  2. Install Maven, Git, Curl, Activemq, and mysql

    1. In terminal, type

      sudo apt-get install curl git maven activemq mysql-server
    2. On a fresh Ubuntu installation, you may need to run the following first

      sudo apt-get update
  3. Configure ActiveMQ

    Run the following

    sudo ln -s /etc/activemq/instances-available/main /etc/activemq/instances-enabled/main


    For ActiveMQ scheduled delivery to work, you must set the attribute: schedulerSupport=”true” for the broker element in your activemq.xml config file. This file should be located at (active-mq-folder)/conf/activemq.xml.See ActiveMQ docs.

  4. Install JDK 7

    1. Go to The Java JDK Download Page

    2. Accept License Agreement

    3. Click on jdk-7u51-linux-x64.tar.gz (or latest stable version)

    4. Extract the file into your home directory, ie: /home/*<user>*/jdk1.7.0_51

    5. Set the proper Java environment and change maven options:

      1. Start a new terminal session

      2. Edit your .profile file

        nano ~/.profile
      3. append the following at the end of the file:

        export PATH="$HOME/jdk1.7.0_21/bin:$PATH"
        export JAVA_HOME=$HOME/jdk1.7.0_21
        export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m"
      4. Save the changes (Ctrl+X) and quit

      5. Confirm the settings are right

      6. Log out & log back in & start a new terminal

      7. Type

        java -version && env | grep MAVEN_OPTS

      You should see something like:

      java version "1.7.0_51"
      Java(TM) SE Runtime Environment (build 1.7.0_51-b11)
      Java HotSpot(TM) 64-Bit Server VM (build 23.21-b01, mixed mode)
      MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=128m
  5. Install Tomcat7

    1. Go to Tomcat’s download page

    2. Under 7.0.52 (or the latest stable version) - Binary Distributions - Core, click on tar.gz

    3. Once downloaded, expand the file to your home directory, i.e.: /home/*<user>*/apache-tomcat-7.0.52

    4. Edit the tomcat-users.xml file (located under \etc\tomcat7\conf\) to add an admin user:

    5. In the terminal type

      nano ~/apache-tomcat-7.0.52/conf/tomcat-users.xml
    6. Insert a line similar to the following before the closing </tomcat-users> tag:

      <user username="*<username>*" password="*<password>*" roles="manager-gui"/>
    7. Save the changes (Ctrl+X) then quit

    8. Now edit ~/.bashrc to setup tomcat’s environment variable

      nano ~/.bashrc
    9. Append the following line:

      export CATALINA_HOME=$HOME/apache-tomcat-7.0.52
    10. Save the changes (Ctrl+X) then quit

    11. Start a new terminal session or type

      source ~/.bashrc
  6. Install CouchDB

    1. Download the latest stable sources from and then follow the instructions in the INSTALL.Unix file.

      For Ubuntu 13.10, just run:

      sudo apt-get install couchdb
    2. Once this is done, navigate to http://localhost:5984 to verify that the installation completed successfully.

      {"couchdb":"Welcome","uuid":"52068def93b82a2653dcf352a4f9273a","version":"1.4.0","vendor":{"version":"1.4.0","name":"The Apache Software Foundation"}}
  7. Install CouchDB-Lucene

    1. Follow these instructions also be sure to follow the proxy handler instructions

    2. Once the proxy has been configured, restart couchdb with:

      sudo service couchdb restart
    3. After restarting couchdb, navigate to http://localhost:5984/_fti and you should see something like this:

  8. Setup MySQL

    1. In your motech source root directory, type in the terminal:

      $ mysql -u root -p
    2. then type:

      sql> create database motechquartz;
      sql> create database motech_data_services;
      sql> create user 'quartz'@'localhost' identified by 'quartz2123';
      sql> grant all privileges on motechquartz.* to 'quartz'@'localhost';
      sql> exit;
    3. then type:

      mysql -u root -p motechquartz < modules/scheduler/scheduler/sql/create_db_schema_quartz_v2.1.sql
  9. Start Tomcat
    1. In terminal, type:

      ~/apache-tomcat-7.0.52/bin/ jpda start
    2. You should see messages similar to:

      Using CATALINA_BASE:   /home/*<user>*/apache-tomcat-7.0.52
      Using CATALINA_HOME:   /home/*<user>*/apache-tomcat-7.0.52
      Using CATALINA_TMPDIR: /home/*<user>*/apache-tomcat-7.0.52/temp
      Using JRE_HOME:        /home/*<user>*/jdk1.7.0_51
      Using CLASSPATH:       /home/*<user>*/apache-tomcat-7.0.52/bin/bootstrap.jar:/home/*<user>*/...
    3. You can also confirm tomcat was started by going to http://localhost:8080 in a browser

  10. Jump to the Building and Installing MOTECH section to install MOTECH

Installing on a Macintosh

  1. Installing Prerequisites for MOTECH

    1. Installing HomeBrew

      To install Homebrew, run the following in the terminal

      ruby -e "$(curl -fsSL"
    2. Use Homebrew to install git, erlang, ActiveMQ, and Apache Tomcat:
      brew install git
      brew install activemq
      brew install tomcat
      brew install maven
    3. Homebrew installations are located in /usr/local/Cellar` with symlinks in ``/usr/local/bin, which should already be part of your $PATH environment variable.


      Homebrew provides instructions about how to run these applications, as well as how to have launchd start them automatically on system startup.

    4. Configuring Tomcat:

      Edit the tomcat-users.xml file to add an admin user. Insert a line similar to the following before the closing </tomcat-users> tag:

      <user username="motech" password="motech" roles="manager-gui"/>
    5. Installing JDK 7:

      Mac OS includes JDK6 by default, however JDK 7 is required for MOTECH. Use these instructions to install the latest version of the JDK.

    6. Installing MySQL:

      1. Before installing MySQL, you will need Xcode from the App Store. This can take a while; it’s a big download.

      2. Next start Xcode from the Launchpad (rocketship icon in the dock) and select Install. Then you can quit Xcode; you don’t need to keep it running.


        (Command Line Tools using Xcode are included in OS X Mavericks, but not previous OS versions. If you are running Mountain Lion, you can follow these instructions:

      3. Go to and download the appropriate DMG archive. Open it, double-click on the installer, and follow directions.

      4. Once mysql has finished installing, double-click the MySQL preferences pane in the DMG and follow instructions. For more details see ‘these instructions’_ .


      Homebrew can be used to install MySQL, however Homebrew will not install the Mysql System Preferences control panel.

  2. Setting up Symbolic Link and Environment Variables

    1. Create a symbolic link from the Tomcat directory (Homebrew installs into /usr/local/Cellar/tomcat/<version number>/libexec) to /usr/local/tomcat:

      ln -s /usr/local/Cellar/tomcat/`brew info tomcat | grep stable | awk '{print $3}' | sed 's/,//'`/libexec /usr/local/tomcat
    2. Edit your ~/.bash_profile to set environment variables (catalina is Tomcat):

      export JAVA_HOME="/Library/Java/Home"
      export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m"
      export CATALINA_HOME="/usr/local/tomcat"
      export CATALINA_OPTS="-Xms1024m -Xmx2048m -XX:MaxPermSize=1024m"
      export PATH=/usr/local/mysql/bin:$PATH
    3. When you’re done editing:
      source ~/.bash_profile
  3. Jump to the Building and Installing MOTECH section to install MOTECH

Building and Installing MOTECH

  1. Getting the MOTECH code

  2. Building MOTECH

    1. Assuming you issued the git clone command in your home directory root, in the terminal

      $ cd ~/motech
      $ mvn install

    b.) It takes some time to build MOTECH, but eventually you should see:

    [INFO] ------------------------------------------------------------------------
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 29:19.284s
    [INFO] Finished at: Fri Jun 07 12:12:43 PDT 2013
    [INFO] Final Memory: 152M/378M
    [INFO] ------------------------------------------------------------------------


    Should you get a java.lang.OutOfMemoryError exception, it may be because you forgot to set MAVEN_OPT as described in [3.5]. But you may need to increase -Xmx. So something like -Xmx1024m might work.

  3. Install MOTECH

    1. In a browser, go to http://localhost:8080

      Tomcat server home page
    2. Click on Manager App

    3. Type the user/password you used in tomcat-users.xml

      temporary hack you need to remove ~/.motech/config/motech-settings.conf to allow the create initial user wizard.

    4. In the Tomcat Web Application Manager, scroll down to the Deploy section and the WAR file to deploy subsection, click on Browseand select or navigate to ~/motech/platform/server/target/motech-platform-server.war then click on Deploy

      Tomcat web application page
    5. Depending on your machine it could take a while for motech-platform-server to deploy

    6. In the Tomcat Web Application Manager page, click on /motech-platform-server, you get the MOTECH initial user screen

      Motech initial user page

Installing the IDE, Intellij IDEA Community Edition & open MOTECH project

  1. Go to the Jetbrains home page and click on Download Now in the Community Edition box, then expand the file to your home directory.

  2. From a terminal, assuming you extracted IntelliJ to ~/idea-IC-129.713, start IntelliJ

    $ ~/idea-IC-129.713/bin/
  3. Select Import Project

Import project view
  1. Select ~/motech/pom.xml, a dialog box will appear. Set the options as shown:

  2. Click Next

  3. In Select Profiles, do not select any profile, click Next

  4. In Select Maven projects to Import, there should only be one project: org.motechproject:motech:0.20-SNAPSHOT, click Next

  5. In Please select project SDK, if the 1.7.0_21 is present, select it, otherwise add it:

  6. Click +

  7. Select JDK

  8. Select /home/frank/jdk1.7.0_21, then click OK

  9. Click Next

  10. Click Finish

  11. Background processes will take a long time

  12. You can also create a menu launcher, so you can start IntelliJ from the gui:

    1. From the Tools menu select Create Desktop Entry

    2. A IntelliJ menu item will be created in the Development application group

    3. Debug demo module in IntelliJ

    4. Start IntelliJ (from the command line, or from launcher icon if you created one)

    5. It’ll automatically open the motech project (if it was the last project you worked on)

    6. From the Run menu select Edit Configurations

    7. Click on the green +

    8. Select Remote

    9. Give a name to your Run/Debug configuration and change the port to 8000 as:

      ide configuration
    10. Hit OK

    11. Set a breakpoint somewhere in the demo module code, i.e.:

    12. From the Run menu, select Debug ‘Tomcat’ where Tomcat is the name of your configuration.

    13. In the browser go to the place that will hit the breakpoint, i.e.: if you setup a breakpoint as in the previous screen, then in the Demo module, click the Decision Trees tab, and you should hit the breakpoint!

      ide configuration