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
      1. Environment Variables
      2. Moqui Conf XML File
    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 8. Unless you are using OpenJDK 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.war load
  3. Run the framework (with embedded Servlet Container, Transaction Manager, Databases):
    • $ java -jar moqui.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 MoquiDemo-<version>.war file (or similar HiveMind/PopCommerce war files)
  2. Drop the WAR file into Java Servlet Container (Jetty, Apache Tomcat, 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.war load
Run embedded web server: $ java -jar moqui.war
Deploy as WAR, for Tomcat: $ cp moqui.war ../tomcat/webapps/ROOT.war

You can also display settings and help information with:

java -jar moqui.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.war load
Run Server $ java -jar moqui.war

Common Alternate - Specify a Configuration File on Command Line

Load Data $ java -jar moqui.war load conf=conf/MoquiProductionConf.xml
Run Server $ java -jar moqui.war conf=conf/MoquiProductionConf.xml

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

Environment Variables

Support for single database configuration was added for easier Docker, etc deployment and can be used in any environment. This is an alternative to adding database configuration in the runtime Moqui Conf XML file as described in the next section.

Each of these can be system environment variables (with underscores) or Java properties (with underscores or dots) using the -D command-line argument.

The JDBC driver for the desired database must be on the classpath. The jar file can be added to the runtime/lib directory (within the moqui-plus-runtime.war file if used) or on the command line. In Docker images the runtime/lib directory within the container can be mapped to a directory on the host for convenience (along with runtime/conf and many other directories).

Note that the 'mysql' database configuration also works with MariaDB and Percona.

Env Var or Property MySQL Example Description
entity_ds_db_conf mysql Database configuration from MoquiDefaultConf.xml or one you add
entity_ds_host localhost Host name of database server
entity_ds_port 3306 Port the database is running on
entity_ds_database moqui Name of the database on the server
entity_ds_schema Schema within the database to use (note: leave empty by default for MySQL)
entity_ds_user moqui Database user
entity_ds_password CHANGEME Password for database user
entity_ds_crypt_pass CHANGEME The key used for encrypted fields, should be protected just like a password

Environment variables are a convenient way to configure the database when using pre-built WAR files with runtime included or Docker images.

Another set of common environment variables to use is for URL writing:

Env Var or Property Example Description
webapp_http_host moqui.org The hostname to use, defaults to host name or IP address used for the request
webapp_http_port 80 The port for insecure URLs
webapp_https_port 443 The port for secure URLs
webapp_https_enabled true Set to true to enable secure URLs. Defaults to false with all URLs generated for insecure port.

Moqui Conf XML File

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 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="CHANGEME" pinGlobalTxToPhysicalConnection="true"
                serverName="127.0.0.1" port="3306" databaseName="moqui" 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
      - tools        : System 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.