Installing the Open Source Middleware - aceoperator/mw GitHub Wiki

The Open-Source Middleware is a source distribution only. That is, you have to download/checkout the source and build the binaries. The idea is that the Middleware is a starter for your project and you will add more stuff to it based on your application requirement. The bundle can be installed on Windows, Linux, Mac OS or any other systems as long as Java is supported on it.

Prerequisites

The following software must be installed before you can build and run the project.

  1. Java 1.7 SDK. We have not tested with Java 1.8 or earlier versions. Set the JAVA_HOME environment variable to point to the root of the Java installation.
  2. Maven 3.x.
  3. MySQL 5.x Community Edition.
  4. Apache Tomcat 7.x. You can install other Servlet Containers if you want but the instructions here explain how to run the middleware on Tomcat only.

In addition, we recommend that you install the following:

  1. A git client.
  2. Eclipse Kepler, Java Enterprise Edition bundle. The Eclipse project files are already included with the distribution. So, setting the project should be a snap. We installed additional plugins (a) Spring Tools Suite (STS), (b) Jasper Report Designer (only required if you plan report development) and (c) Apache Activiti plugin (only required if you want to use the Business Process Management engine).

Downloading the Software

The software is available from https://github.com/aceoperator/mw. If you want to download the bundle without using a git client, use the Download Zip button after selecting the master branch. We recommend that you use a git client to clone the repository and checkout a local copy. The repository URL is - https://github.com/acepoperator/mw.git. If you are using github for your project, we suggest that you fork the repository. The advantage of forking is that you will be able periodically pull the latest changes made to the Open-Source Middleware into your forked project. The repository contains two branches - master and develop. The develop branch may contain unstable code that has not been tested. With the master branch, you are sure to get a stable version. You can also use the tags to start from a stable version.

To clone the repository or a forked repository, use the Linux/Unix commands:

mkdir git # creates a directory called git under the current directory.

cd git

git clone https://github.com/aceoperator/mw # if you forked the repository, specify the forked URL

cd mw # the mw directory the root of the project. It was created by the above command.

git checkout master # Make a working copy of the master branch.

Creating a Binary Distribution

Make sure that the Maven and MySQL bin directories is in the PATH environment variable. Make sure that the MySQL server is running and the Tomcat server is NOT running.

  1. cd mw # go to the root of the project
  2. cp -R mw-assembly/src/main/assembly/.mw ${HOME} # Copy the .mw directory to your home directory.
  3. Using an text editor of your choice, modify the files ${HOME}/.mw/db/activiti.mysql.create.data.sql and ${HOME}/.mw/db/mw.mysql.create.db.sql and ${HOME}/.mw/db/mw.mysql.create.data.sql. Search and replace the passwords 'a1b2c3d4' with more secure passwords. Ideally, you should have a different password for each of them but just to make it simple, you can replace all of them with a common but a complex password.
  4. Using an text editor, open the file ${HOME}/.mw/conf/properties/mw.properties. Configure the database, email and other parameters. Other than the email properties, for the rest, you just need to modify the passwords to match the passwords you created above.
  5. mysql -u root -p < ${HOME}/.mw/db/mw.mysql.create.db.sql # Creates a database called mw.
  6. mysql -u root -p < ${HOME}/.mw/db/mw.mysql.create.core.sql
  7. mysql -u root -p < ${HOME}/.mw/db/mw.mysql.create.data.sql
  8. mvn clean install # Downloads dependency, builds, runs tests and deploys the artifacts on the local repository. The build should complete successfully.

If everything works fine, you will find a zip and a tar.gz file in the mw-assembly/target directory. If you run the build multiple times, two new files are created every time with the timestamp in the file names.

Running the Middleware

The Middleware runs on the Tomcat server as a web application. To run the application, follow the instructions below.

  1. With an unzip tool, open the tar.gz or the zip file.
  2. Navigate to the mw-bin/war directory.
  3. Copy the file mw-service.war to the webapps directory under the Tomcat home directory.
  4. mv $TOMCAT_HOME/webapps/mw-service.war $TOMCAT_HOME/webapps/mw.war # Rename the file to mw.war.
  5. Make sure that the .mw directory (that you created earlier) is in the home directory of the user who is going to run Tomcat.
  6. Start Tomcat.

To test if things are working, open a browser and navigate to the URL - http://localhost:8080/mw/rest/client/DEFAULT/activiti. You should be prompted for a user name and password. Enter "activiti" as the user name and the password that you selected in the installation step above. You should see an XML segment appear. This proves that the REST service is working along with the rest of the framework.

Note that the Business Process Engine is not running yet. If you need the engine for your application, follow the steps outlined in the TODO section.

Now you are ready to get started with your own application at the top of the Open-Source Middleware. Read the Getting Started to learn more.