Running and Deployment Instructions

This document explains how to run Moqui through the executable war file, or by deploying a war file in an application server.

  1. Running and Deployment Instructions
    1. 1. Quick Start
      1. Really Quick Start
    2. 2. Runtime Directory and Configuration File
    3. 3. Executable WAR File
    4. 4. Examples and Common Approaches
      1. Easy Way - Default Settings
      2. Common Alternate - Specify a Configuration File on Command Line
      3. Create a Custom WAR File with Settings Inside
    5. 5. Component Management
    6. 6. Build and Run From Source
    7. 7. Database Configuration
    8. 8. Project Directory Structure

1. Quick Start

The only required software for the default configuration of Moqui Framework is the Java SE JDK version 7 or later (JDK 8 recommended). The Oracle Java SE downloads are generally the best option:

http://www.oracle.com/technetwork/java/javase/downloads

  1. Download and unzip a binary distribution
  2. Load the seed and demo data (will create H2 database and tables automatically):
    • $ java -jar moqui-<version>.war -load
  3. Run the framework (with embedded Servlet Container, Transaction Manager, Databases):
    • $ java -jar moqui-<version>.war
  4. In your browser (on the same machine) go to:
  5. With the example component in place and demo data loaded you can login with username "john.doe" and password "moqui"

For details and other approaches read on...

Really Quick Start

  1. Download the MoquiEcosystem-<version>.war file (or similar HiveMind/PopCommerce war files)
  2. Drop the WAR file into Java Servlet Container (Apache Tomcat, Jetty, AWS ElasticBeanstalk, etc)

2. Runtime Directory and Configuration File

Moqui Framework has two main parts to deploy:

  1. Executable WAR File (see below; from moqui-framework repository)
  2. Runtime Directory with Configuration File (from moqui-runtime repository, or your own)

However you use the executable WAR file, you must have a runtime directory and you may override default settings with a XML configuration file.

The runtime directory is the main place to put components you want to load, the root files (root screen, etc) for the web application, and configuration files. It is also where the framework will put log files, H2 database files (if you are using H2), JCR repo files, etc. You will eventually want to create your own runtime directory and keep it in your own source repository (fork the moqui-runtime repository) but you can use the default one to get started.

Specify these two properties:

moqui.runtime Runtime directory (defaults to "./runtime")
moqui.conf Conf XML file (URL or path relative to moqui.runtime)

There are two ways to specify these two properties:

  1. MoquiInit.properties file on the classpath
  2. System properties specified on the command line (with java -D arguments)

See below for examples.

3. Executable WAR File

Yep, that's right: an executable WAR file. There are 3 main things you can
do with this (with example commands to demonstrate, modify as needed):

Load Data: $ java -jar moqui-<version>.war -load
Run embedded web server: $ java -jar moqui-<version>.war
Deploy as WAR, for Tomcat: $ cp moqui-<version>.war ../tomcat/webapps/ROOT.war

You can also display settings and help information with:

java -jar moqui-<version>.war -help

For information about loading only certain files instead of all data files in all components, run that to see the help text.

4. Examples and Common Approaches

Easy Way - Default Settings

The easiest way to run is to have a moqui directory with the moqui.war file and the runtime directory in it. With the binary distribution of Moqui when you unzip the archive this is what you'll have.

To use the default settings:

Run these commands:

Load Data $ java -jar moqui-<version>.war -load
Run Server $ java -jar moqui-<version>.war

Common Alternate - Specify a Configuration File on Command Line

Load Data $ java -Dmoqui.conf=conf/MoquiStagingConf.xml -jar moqui-<version>.war -load
Run Server $ java -Dmoqui.conf=conf/MoquiStagingConf.xml -jar moqui-<version>.war

Create a Custom WAR File with Settings Inside

  1. Add components and other resources as needed to the runtime directory
  2. Change ${moqui.home}/MoquiInit.properties with desired settings
  3. Change Moqui conf file (runtime/conf/Moqui*Conf.xml) as needed
  4. Create a derived WAR file based on the moqui.war file and with your runtime directory contents and MoquiInit.properties file with: "./gradlew addRuntime" or "ant add-runtime"
  5. Copy the created WAR file (moqui-plus-runtime.war) to deployment target
  6. Run server (or restart to deploy live WAR)

5. Component Management

The best way to manage source repositories for components is to have one repository (on GitHub or elsewhere) per component that contains only the component directory.

Following this pattern the Gradle build scripts in Moqui have tasks to download components and their dependencies from a git repository, or from current or release archives.

Known open source components are already configured in the addons.xml file. To add private and other components or override settings for components in the addons.xml file, create a file called myaddons.xml and put it in the moqui directory.

Here is a summary of the Gradle tasks for component management (using the HiveMind component for example). All of the get tasks get the specified component plus all components it depends on (as specified in its component.xml file).

Get runtime directory $ ./gradlew getRuntime -PlocationType=(git,current,release) Called automatically if runtime directory does not exist. Location type defaults to git if .git directory exists, otherwise to current.
Get component $ ./gradlew getComponent -Pcomponent=HiveMind -PlocationType=(git,current,release) Location type defaults to git if .git directory exists, otherwise to current
Get from Git repository $ ./gradlew getGit -Pcomponent=HiveMind
Get current archive $ ./gradlew getCurrent -Pcomponent=HiveMind
Get release archive $ ./gradlew getRelease -Pcomponent=HiveMind
Get dependencies for all components $ ./gradlew getDepends -PlocationType=(git,current,release) Location type defaults to git if .git directory exists, otherwise to current

There are also Gradle tasks to help you manage your components from git. Each of these commands does git operations if a .git directory exists for the moqui (root) repository, the runtime repository, and all components.

Git pull all $ ./gradlew gitPullAll
Git status on all $ ./gradlew gitStatusAll
Git pull upstream on all $ ./gradlew gitUpstreamAll
Clean all, pull all, load data $ ./gradlew cleanPullLoad
Clean all, pull all, load data, all tests $ ./gradlew cleanPullTest
Clean all, pull all, load data, only component tests $ ./gradlew cleanPullCompTest

6. Build and Run From Source

Moqui Framework uses Gradle for building from source. There are various custom tasks to automate frequent things, but most work is done with the built-in tasks from Gradle.

There is also an Ant build file for a few common tasks, but not for building from source.

Get Component and Dependencies (for example: HiveMind) $ ./gradlew getComponent -Pcomponent=HiveMind
Build JAR, WAR $ ./gradlew build
Load All Data $ ./gradlew load $ ant load
Run Embedded Server $ ./gradlew run $ ant run
Create WAR with embedded runtime $ ./gradlew addRuntime $ ant add-runtime
Clean up JARs, WAR $ ./gradlew clean
Clean up ALL built and runtime files (logs, dbs, etc) $ ./gradlew cleanAll

The examples above use the Gradle Wrapper (gradlew) included with Moqui. You can also install Gradle (2.0 or later) The load and run tasks depend on the build task, so the easiest to get a new development system running with a populated database is:

Linux/Mac Gradle Wrapper $ ./gradlew load run
Windows Gradle Wrapper > gradlew.bat load run
Installed Gradle $ gradle load run

This will build the war file, run the data loader, then run the server. To stop it just press <ctrl-c> (or your preferred alternative).

7. Database Configuration

Database (or datasource) setup is done in the Moqui Conf XML file with moqui-conf.entity-facade.datasource elements. There is one element for each entity group and the datasource.@group-name attribute matches against entity.@group-name attribute in entity definitions. By default in Moqui there are 4 entity groups: transactional, nontransactional, configuration, and analytical. If you only configure a datasource for the transactional group it will also be used for the other groups.

Here is the default configuration for the Apache H2 database:


<datasource group-name="transactional" database-conf-name="h2" schema-name=""
        start-server-args="-tcpPort 9092 -ifExists -baseDir ${moqui.runtime}/db/h2">
    <!-- with this setup you can connect remotely using "jdbc:h2:tcp://localhost:9092/MoquiDEFAULT" -->
    <inline-jdbc pool-minsize="5" pool-maxsize="50">
        <xa-properties url="jdbc:h2:${moqui.runtime}/db/h2/MoquiDEFAULT" user="sa" password="sa"/>
    </inline-jdbc>
</datasource>

The database-conf-name attribute points to a database configuration and matches against a database-list.database.@name attribute to identify which. Database configurations specify things like SQL types to use, SQL syntax options, and JDBC driver details.

This example uses a xa-properties element to use the XA (transaction aware) interfaces in the JDBC driver. The attribute on the element are specific to each JDBC driver. Some examples for reference are included in the MoquiDefaultConf.xml file, but for a full list of options look at the documentation for the JDBC driver.

The JDBC driver must be in the Java classpath. The easiest way get it there, regardless of deployment approach, is to put it in the runtime/lib directory.

Here is an example of a XA configuration for MySQL:


<datasource group-name="transactional" database-conf-name="mysql" schema-name="">
    <inline-jdbc pool-minsize="5" pool-maxsize="50">
        <xa-properties user="moqui" password="moqui" pinGlobalTxToPhysicalConnection="true"
                serverName="127.0.0.1" port="3306" databaseName="MoquiDEFAULT" autoReconnectForPools="true"
                useUnicode="true" encoding="UTF-8"/>
    </inline-jdbc>
</datasource>

To use something like this put the datasource element under the entity-facade element in the runtime Moqui Conf XML file (like the MoquiProductionConf.xml file).

For more examples and details about recommended configuration for different databases see the comments in the MoquiDefaultConf.xml file:

https://github.com/moqui/moqui-framework/blob/master/framework/src/main/resources/MoquiDefaultConf.xml

8. Project Directory Structure

- moqui (from https://github.com/moqui/moqui)
  - framework
    - build          : Results of framework build go here (classes, jars, etc)
    - data           : Seed data
    - entity         : Framework entity definitions
    - lib            : Libraries (JAR files) used in Moqui
    - screen         : Framework screens
    - service        : Framework services
    - src            : Java API, standard entities, services, data, XSDs, etc
      - api          : Java source for the Moqui Framework API
      - main         : Main implement source
        - groovy     : Groovy source (bulk of the implementation)
        - java       : Java source (a few special classes)
        - resources  : Classpath resources, placed in JAR as-is
        - webapp     : Base webapp, mostly just a WEB-INF/web.xml file
      - start        : Java source for MoquiStart, used for executable WAR
    - template       : Framework templates (screen/form, xml-actions FTLs)
    - xsd            : Framework XML Schema files
  - runtime
    - base-component : Base/framework components to deploy
      - example      : An example application
      - tools        : Framework administration and maintenance tools
      - webroot      : Root Screen and supporting content
    - classes        : Resources to add to the runtime classpath
    - component      : Application/etc components to deploy
    - conf           : Configuration files separated by dev, staging, prod, etc
    - db             : Database files for H2, Derby, OrientDB, etc will go here
    - lib            : JAR files to add to the runtime classpath
    - log            : Log files will go here
    - template       : General Templates
    - tmp            : Temporary files
    - txlog          : Transaction log files will go here (Atomikos or Bitronix files)

The main place to put your components is in the runtime/component directory. When you use the Gradle get component tasks this is where they will go.

Components with declared dependencies (in a component.xml file in the component directory) will be loaded after the component(s) they depend on.