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. We upgraded from Java 7 to Java 8 in MOTECH version 0.28. The instructions are annotated with this change. If you have any trouble, please feel free to send feedback to our developer list.

  1. Install Ubuntu Desktop 14.04 LTS 64bit

    Installation instructions

  2. Install Maven, Git, Curl, ActiveMQ, NodeJS, NPM, Bower, Gulp and a database of your choice

    1. In terminal, type

      sudo apt-get install curl git maven activemq npm
      curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
      sudo apt-get install -y nodejs
      sudo npm install -g bower gulp
      
    2. The two datastores officially supported by MOTECH are MySQL and PostgreSQL. It is not required to install both of them to run MOTECH, but provided you intend to introduce some changes to the code, it may be required that you test the outcome on both databases.

      sudo apt-get install mysql-server
      sudo apt-get install postgresql
      
    3. 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
    

    Note

    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 8 (For Developing MOTECH v.0.28 and greater)

    1. Go to The Java JDK Download Page

    2. Accept License Agreement

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

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

    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.8.0_73/bin:$PATH"
        export JAVA_HOME=$HOME/jdk1.8.0_73
        export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m"
        export CATALINA_OPTS="-Xms1024m -Xmx2048m -XX:MaxPermSize=1024m"
        
      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\|CATALINA_OPTS\)"
        

      You should see something like:

      java version "1.8.0_73"
      Java(TM) SE Runtime Environment (build 1.8.0_73-b02)
      Java HotSpot(TM) 64-Bit Server VM (build 25.73-b02, mixed mode)
      MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=128m
      CATALINA_OPTS=-Xms1024m -Xmx2048m -XX:MaxPermSize=1024m
      
  5. Install Tomcat7

    1. Go to Tomcat’s download page

    2. Under 7.0.68 (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.68

    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.68/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. Edit the web.xml of the manager application(located under \webapps\manager\WEB-INF\web.xml):

      nano ~/apache-tomcat-7.0.68/webapps/manager/WEB-INF/web.xml
      
    9. Edit the lines in multipart-config defining the max upload value. Change it from 50MB to a bit more, 100MB should suffice:

      <!-- Before changes -->
      
      <multipart-config>
        <!-- 50MB max -->
        <max-file-size>52428800</max-file-size>
        <max-request-size>52428800</max-request-size>
        <file-size-threshold>0</file-size-threshold>
      </multipart-config>
      
      <!-- After changes -->
      
      <multipart-config>
        <!-- 100MB max -->
        <max-file-size>100000000</max-file-size>
        <max-request-size>100000000</max-request-size>
        <file-size-threshold>0</file-size-threshold>
      </multipart-config>
      
    10. Save the changes by hitting Ctrl+X then quit

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

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

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

    14. Start a new terminal session or type

      source ~/.bashrc
      
  6. Setup MySQL (skip if you did not install MySQL server)

    1. Access your database, by typing in the terminal:

      $ mysql -u root -p
      
    2. Create required databases (note: when you’re using account with privilages for DB connection, MOTECH will create necessary DBs and fill them with data; otherwise you have to create them yourself)

      sql> create database motechquartz;
      sql> create database motechschema;
      sql> create database motechdata;
      sql> exit;
      
    3. (Optional) Create user for the motechquartz database. MOTECH will use the user and password from the bootstrap configuration by default, but you can adjust that in the Scheduler settings and provide different credentials.

      sql> create user 'quartz'@'localhost' identified by 'quartz2123';
      sql> grant all privileges on motechquartz.* to 'quartz'@'localhost';
      

    Note

    Sometimes it is needed to set the proper database character encoding. For example, to create motechdata database and motechschema database with UTF-8 character encoding, change your sql query to:

    sql> create database motechdata default character set utf8 collate utf8_general_ci;
    sql> create database motechschema default character set utf8 collate utf8_general_ci;
    
  7. Setup PostgreSQL (skip if you did not install PostgreSQL server)

    1. Access your database, by typing in the terminal:

      $ sudo -u postgres psql postgres
      
    2. Set a password for the “postgres” database role

      postgres=# \password postgres
      

      and give your password when prompted.

    3. Create required databases (note: when you’re using account with privilages for DB connection, MOTECH will create necessary DBs and fill them with data; otherwise you have to create them yourself)

      postgres=# create database motechquartz;
      postgres=# create database motechschema;
      postgres=# create database motechdata;
      postgres=# (ctrl + D)
      
    4. (Optional) Create user for the motechquartz database. MOTECH will use the user and password from the bootstrap configuration by default, but you can adjust that in the Scheduler settings and provide different credentials.

      postgres=# create user quartz with password 'quartz2123';
      postgres=# grant all privileges on database motechquartz to quartz;
      

    Note

    MD5 authentication is required and should be enabled by default in latest versions of PostgreSQL. If it’s not the case, you might need to enable this by hand. For more information refer to: http://www.postgresql.org/docs/9.3/static/auth-methods.html

  8. Start Tomcat
    1. In terminal, type:

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

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

  9. 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 https://raw.githubusercontent.com/Homebrew/install/master/install)"
      
    2. Use Homebrew to install git, erlang, ActiveMQ, NodeJS and Apache Tomcat:
      brew install git
      brew install activemq
      brew install tomcat
      brew install maven
      brew install node
      
    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.

      Note

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

    4. Use NPM (installed with NodeJS) to install Bower and Gulp.

      npm install -g bower gulp

    5. Configuring Tomcat

      1. 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"/>
        
      2. Edit the web.xml of the manager application(located under \webapps\manager\WEB-INF\web.xml) and change the lines in multipart-config defining the max upload value. Change it from 50MB to a bit more, 70MB should suffice:

        <!-- Before changes -->
        
        <multipart-config>
          <!-- 50MB max -->
          <max-file-size>52428800</max-file-size>
          <max-request-size>52428800</max-request-size>
          <file-size-threshold>0</file-size-threshold>
        </multipart-config>
        
        <!-- After changes -->
        
        <multipart-config>
          <!-- 70MB max -->
          <max-file-size>71680000</max-file-size>
          <max-request-size>71680000</max-request-size>
          <file-size-threshold>0</file-size-threshold>
        </multipart-config>
        
    6. Installing JDK 8:

      Mac OS includes JDK6 by default, however JDK 8 is required for MOTECH. Use these instructions to install the latest version of the JDK or these instructions to install JDK 7 for development on MOTECH v.0.27 and prior.

    7. 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.

        Note

        (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 http://dev.mysql.com/downloads/mysql/ and download the appropriate DMG archive. Open it, double-click on the installer, and follow directions.

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

      Note

      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] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 29:19.284s
    [INFO] Finished at: Fri Jun 07 12:12:43 PDT 2013
    [INFO] Final Memory: 152M/378M
    [INFO] ------------------------------------------------------------------------
    

    Note

    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 (if you installed via docker the default username/password is motech/s3cret).

      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 Browse and 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. If you get an error of the form: “the request was rejected because its size (68032892) exceeds the configured maximum (52428800)” follow these instructions to

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

      Motech initial user page

    Note

    The war file contains all modules required for starting and managing MOTECH. You can either use the Admin UI to install additional modules at runtime or place them in the ~/.motech/bundles directory and restart MOTECH. Note that doing a mvn clean install on any of our modules will place that module in the ~/.motech/bundles directory automatically. Modules from that directory always override the ones contained in the war if their Bundle-Version and Bundle-SymbolicName are the same.

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-143.2287.1, start IntelliJ

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

  4. Select ~/motech/pom.xml, a dialog box will appear. Set the options as shown:

    Import project view
  5. Click Next

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

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

  8. In Please select project SDK, if the 1.8.0_73 is present, select it, otherwise add it:

  9. Click +

  10. Select JDK

  11. Select /home/YOURUSERNAME/jdk1.8.0_73, then click OK

  12. Click Next

  13. Click Finish

  14. Background processes will take a long time

  15. 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.:

      ide configuration
    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