Wiki Spaces
Mantle Business Artifacts
Moqui Applications
Moqui Ecosystem
Moqui Framework
Page Tree
Moqui Framework


All Pages

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 Moqui Configuration XML 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 and Other Configuration
      1. Environment Variables
      2. Moqui Conf XML File
    8. 8. Production Recommendations
      1. Docker and Docker Compose
      2. AWS Elastic Beanstalk and RDS
    9. 9. 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:

  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 Moqui Configuration XML 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.

All configuration for Moqui Framework lives in the Moqui Conf XML file. The actual configuration XML file used at runtime is built by merging various XML files in this order:

  1. MoquiDefaultConf.xml that ships with the framework as is included in the built WAR file
  2. MoquiConf.xml from each component
  3. specified runtime Moqui Conf XML file such as MoquiDevConf.xml or MoquiProductionConf.xml

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 may 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 and for most deployments with add-on applications everything in moqui-runtime you will commonly want to override or extend can be done within your add-on components.

Specify these two properties:

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

There are two ways to specify these two properties:

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

  • moqui.runtime = runtime
  • moqui.conf = conf/MoquiDevConf.xml (relative to runtime)

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}/ 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 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 and Other 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, locale, time zone, etc:

Env Var or Property Example Description
instance_purpose production A purpose for the instance, 'production' has special meaning as do 'test' and 'dev'
webapp_http_host 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.
default_locale en_US The Java default Locale
default_time_zone US/Pacific The Java default TimeZone
database_time_zone US/Pacific The time zone to use in the database, defaults to default_time_zone

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 [email protected] attribute matches against [email protected] 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"/>

The database-conf-name attribute points to a database configuration and matches against a [email protected] 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="" port="3306" databaseName="moqui" autoReconnectForPools="true"
                useUnicode="true" encoding="UTF-8"/>

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:

8. Production Recommendations

Docker and Docker Compose

The default Dockerfile and a script to build a Docker image based on the moqui-plus-runtime.war file are in the moqui/docker/simple directory which you can see on GitHub here:

For example after adding all components, JDBC drivers, and anything else you want in your runtime directory do something like:

$ gradle addRuntime Build then create the moqui-plus-runtime.war file
$ cd docker/simple
$ ./ ../.. mygroup/myrepo Build Docker image using Dockerfile, tagged latest by default
$ docker tag mygroup/myrepo:latest mygroup/myrepo:1.0.0 Add a tag for the version of the image
$ docker login -u <username> -p <password> Login to Docker Hub (or other image repo) if not already logged in
$ docker push mygroup/myrepo Push to Docker Hub (or elsewhere)

On the server where the image will run make sure Docker (docker-ce) and Docker Compose (docker-compose) are installed and then pull the image created above. There are various Docker Compose examples in the moqui/docker directory:

You'll need to create a custom compose YAML file based on one of these. This is where you put database, host, and other settings and is where you specify the image to use (like mygroup/myrepo above). To pull your image and start it up along with other Docker images for other needed applications (nginx, mysql or postgres, etc) do something like:

$ docker login -u <username> -p <password> Login to Docker Hub (or other image repo) if not already logged in
$ docker pull mygroup/myrepo Pull image from Docker Hub (or elsewhere)
$ ./ my-compose.yml Bring up containers as defined in the Docker Compose YAML file

There is also a script to bring down an instance. For updates after running docker pull you can run without running first and Docker Compose will simply update the containers with new images versions.

You may want to modify the script and others to fit your specific deployment, including configuration and other Moqui runtime files you want to live on the Docker host instead of in a container (to survive updates, use configuration, etc). Generally when setting up a new Docker server it is recommended to create a private git repository to use as a shell for your Docker deployment. This would contain your compose up/down scripts, your compose YML file(s), and a runtime directory with any additional configuration files, components, JDBC jars, etc.

AWS Elastic Beanstalk and RDS

The recommended approach for deployment with AWS ElasticBeanstalk is to use a 'Java SE' environment. A Tomcat environment can be used by simply uploading a moqui-plus-runtime.war file but there are issues with this approach in that it is less flexible, Tomcat settings need to be adjusted for capacity, various changes are needed to support websocket, and so on. Using a Java SE environment with the embedded Jetty web server generally runs better and has various defaults already in place that are recommended for Moqui, plus full control of the command line to start the server to adjust servlet threads, port, Moqui XML Conf file to use, etc.

In a AWS EB Java SE environment you'll have a nginx proxy already in place that by default expects the application to be running on port 5000. The Java SE environment is used by uploading an application archive containing files for the application(s) and to tell the Java SE environment what to do. Since Moqui Framework 2.1.1 there is a Procfile included that will be added to the moqui-plus-runtime.war file. By default it contains:

web: java -cp . MoquiStart port=5000 conf=conf/MoquiProductionConf.xml

Note that it does not contain memory options so that they may be set with the JAVA_TOOL_OPTIONS environment variable. For example set it to "-Xmx1024m -Xms1024m" for a 1024 MB Java heap. The heap size on a dedicated instance should be about 1/2 the total system memory (leaving room for off-heap Java memory usage and operating system memory usage).

The WAR file should also be renamed from .war to .zip so that the AWS Java SE environment treats it like a plain archive and not an executable jar. Basically to build a file to upload to AWS ElasticBeanstalk do something like:

$ gradle addRuntime Build then create the moqui-plus-runtime.war file
$ mv moqui-plus-runtime.war ../ Rename the WAR file and move to parent directory to keep separate

Then upload the ZIP file in the Elastic Beanstalk section of the AWS Console when you create your Java SE environment.

You'll also need to set various environment variables in your Elastic Beanstalk settings (under Configuration => Software Configuration) for database, host, and other settings. See the Environment Variables section above for a list of which to set.

Typically these settings will include host and other database information for a RDS instance running MySQL, Postgres, or other. Make sure the VPC Security Group for the RDS instance (automatically created when you create the DB instance) has an inbound rule with a VPC Security Group that your Elastic Beanstalk configuration is in (specified in Configuration => Instance). This is done in the VPC section of the AWS Console under Security Groups.

The smallest recommended servers to use are t2.small for the EC2 instance and t2.micro for the RDS instance for a total cost generally under $40/mo depending whether a reserved instance is used, how much disk space is used, etc. Note that for larger EC2 instances make sure to adjust the Procfile so that the maximum heap size is higher, usually roughly half of total memory for the instance if there is nothing else running on it.

9. Project Directory Structure

- moqui (from
  - 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.