1. Install Java JDK

Modality is developed entirely in the Java language, and requires at least JDK 17+. Check whether this is installed:

java --version

If it is not installed, or is an older version, please refer to this guide.

2. Install WebFX CLI

We use the WebFX CLI to compile Modality for the web. Please follow this guide to install it.

3. Install IntelliJ IDEA

We develop Modality using the free, community edition of IntelliJ IDEA, and recommend you install this if you do not already have an IDE. IntelliJ allows you to easily compile and run the Modality server and clients, for the purpose of local development and testing.

All subsequent IDE-based examples given in this documentation will be based on IntelliJ.

4. Install Git

A git client is needed to retrieve the Modality codebase from GitHub. Check if git is installed:

git --version

If it is not installed, you may wish to refer to this guide.

5. Create the Modality root

mkdir -vp modality
export MODALITY_ROOT=${PWD}/modality

6. Clone the codebase

Git clone the Modality codebase via the terminal (or IntelliJ etc):

git clone .

7. Install Postgres database

You may choose to install this natively, or you can use the modality-local-services repository, which contains a Docker-based solution to easily stand up Postgres on your machine.

8. Configure Postgres database

Modality expects a database and set of tables, and when running in local development mode expects to connect to them using default values. The database setup scripts and default configuration values are described in the modality-local-services repository README.

9. Point Modality to the database

To point Modality to the database, do the following on your local machine:

mkdir -vp $MODALITY_ROOT/conf
cp $MODALITY_ROOT/modality-base/modality-base-server-datasource/src/main/resources/one/modality/base/server/services/datasource/ModalityDatabase.default.json $MODALITY_ROOT/conf/ModalityDatabase.conf
# Modify variables in the file if necessary

Configure Modality for Development

Resolve all Modality Dependencies

Open Modality in IntelliJ and wait for all dependencies to be automatically resolved: