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
   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. Build and Run From Source
   6. 6. Project Directory Structure

1. Quick Start

1. Make sure you have a Java 6 JDK installed (the Sun/Oracle or Apple version is best, haven't tried on OpenJDK or Harmony yet)
2. Download and unzip the binary distribution, creating a moqui directory
3. Load the seed and demo data which will create Derby DB and tables:
   • $ java -jar moqui-<version>.war -load
4. Run the framework (with embedded Servlet, JTA/CP, DB):
   • $ java -jar moqui-<version>.war
5. In your browser (on the same machine) go to:
   • http://localhost:8080/

For details and other approaches read on...

2. Runtime Directory and Configuration File

The Moqui Framework has two main parts to deploy:

1. Executable WAR File (see below)
2. Runtime Directory with Configuration File

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) for the web application, and configuration files. It is also where the framework will put log files, Derby db files (if you are using Derby), JCR repo files, etc. You will eventually want to create your own runtime directory and keep it in your own source repository and you can use the default project one to get started.

Specify these two properties:

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):

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:

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

Run these commands:

Common Alternate - Specify a Configuration File on Command Line

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: "$ gradle 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. 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.

Note that the load and run tasks depend on the build task. The easiest to get a new development system running with a populated database is:

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

6. Project Directory Structure

- moqui (from https://github.com/jonesde/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
    - component : Components to deploy
      - example : An example application
      - tools   : Framework administration and maintenance tools
      - webroot : Root Screen and supporting content
    - conf      : Configuration files separated by dev, staging, prod, etc
    - db        : Database files for Derby, etc will go here
    - lib       : JAR files to add to classpath
    - log       : Log files will go here
    - mantle    : The Mantle root can go here, with components under it
    - template  : General Templates
    - tmp       : Temporary files