Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CCAFS/MARLO/llms.txt

Use this file to discover all available pages before exploring further.

This page walks you through everything you need to run MARLO on your own machine: installing prerequisites, copying the properties template, choosing the right run script for your branch’s Java version, and verifying the build with the mandatory quality gates.

​
Prerequisites

ToolRequired versionNotes
Java (JDK)8 (default) or 17Java 17 only on branches containing java17 or java_17 in the name
Maven3.8.xUsed for the multi-module build and for launching the embedded server
MySQL8.xLocal instance; shared CIAT test data requires VPN (see below)
Connecting to the shared CIAT test environment requires a VPN:
  • Test (CIAT Palmira): FortiClient VPN
  • Staging / Production (AWS): GlobalProtect VPN
Without the appropriate VPN, database connections to shared environments will time out. A local MySQL instance works offline.

​
Setup steps

1

Clone the repository

git clone https://github.com/CCAFS/MARLO.git
cd MARLO
2

Check out the right branch

New feature work branches from aiccra-staging. Check it out before creating your own branch.
git checkout aiccra-staging
To work on a feature, branch off here:
git checkout -b aiccra-<your-slug>
If you are assigned to a java17-named branch (for example aiccra-staging-java17), you must use the Java 17 run scripts throughout this guide.
3

Create your local properties file

Credential files are gitignored and must be created locally. Bootstrap from the committed template:
cp marlo-web/src/main/resources/config/marlo-test.properties \
   marlo-web/src/main/resources/config/marlo-dev.properties
Then open marlo-dev.properties and fill in your local database host, username, and password — see Configuring MARLO for the full property reference.
Never commit marlo-dev.properties or any other credential file. All marlo-${profile}.properties files are listed in the config directory’s .gitignore. Committing credentials is a hard rule violation.
4

Set the active Spring profile

The active profile controls which properties file the application loads:
marlo-${spring.profiles.active}.properties
Available profiles: dev, api, pro, test. For local development you will almost always use dev. The run scripts set this automatically — no manual configuration is needed when you use them.
5

Run MARLO

Choose the script that matches your branch’s Java version. The script stops any existing server, cleans the marlo-web/target directory, builds the project with mvn clean install -DskipTests -pl marlo-web -am, patches the base URL in marlo-dev.properties, and then starts the embedded server.
What the script does:
  • Kills any process matching tomcat7:run
  • Detects or uses JAVA_HOME pointing to JDK 8
  • Builds with Maven
  • Calls scripts/update-marlo-dev-java8.sh to rewrite base URLs to https://localhost:8443
  • Starts Tomcat via mvn -pl marlo-web tomcat7:run -P java8
./scripts/run-marlo-java8.sh
The app is available at:
  • HTTPS: https://localhost:8443/marlo-web/
  • HTTP: http://localhost:8080/marlo-web/
If JDK 8 is installed but not the default, set JAVA_HOME first:
# macOS (Homebrew)
export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)
./scripts/run-marlo-java8.sh

# Linux
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk
./scripts/run-marlo-java8.sh

REM Windows
set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_xxx
scripts\run-marlo-java8.bat
6

Verify startup

The script opens the browser automatically once the server responds. You can also watch the Maven output for Flyway migration logs and Tomcat startup messages.Flyway applies all pending SQL migrations from marlo-web/src/main/resources/database/migrations/ automatically on every startup — you do not need to run migrations manually.

​
Quality gates

Run these before committing or opening a PR. Both are mandatory. 
# Code style check — must pass before commit
mvn checkstyle:check

# Unit tests
mvn test
Checkstyle is configured at configuration/marlo-checkstyle.xml and enforces a 120-character line limit, 2-space indentation, and mandatory braces. SonarCloud and Snyk run automatically on push via GitHub Actions and do not need to be run locally.

​
About the update-marlo-dev-* scripts

The run scripts call a helper that patches marlo-dev.properties to use the correct base URL for the current Java version:
Java versionSchemePortScript called
Java 8HTTPS8443scripts/update-marlo-dev-java8.sh (or .bat)
Java 17HTTP8080scripts/update-marlo-dev-java17.sh (or .bat)
If you switch branches between Java 8 and Java 17 variants, re-run the appropriate script (or just run the full run-marlo-*.sh again) so the base URL stays in sync.
You can pass a custom properties file path to the update scripts:
./scripts/update-marlo-dev-java17.sh /path/to/custom/marlo-dev.properties

Build docs developers (and LLMs) love

Get started for freeTalk to us