Getting started
JCM is a case-management framework: you describe case types, workflows, queues and roles in files, and it serves the screens, and checks every file when the application starts. It runs on Jmix, Vaadin and Spring Boot with Java 21.
This page takes you from nothing to a running application. The jcm command does its work in a tools image that holds
the JDK, Gradle and a browser for tests. Once JCM is released, Docker will be the only thing to install.
Install
You need Docker running Linux containers. Install lists what is supported.
JCM is not released yet, so neither the launcher nor the tools image is published. Until they are, you need access to the JCM repository, Git and bash, as well as Docker. Clone the repository, using the address that came with your access, and build the image once:
git clone https://example.invalid/jcm.git
cd jcm
bash cli/build-image.sh
The build compiles JCM inside Docker and takes about six minutes on a four-core machine with nothing cached; later builds
reuse most of it. Give Docker at least 8 GB of memory and 10 GB of free disk: jcm check alone uses more than 4 GB.
Leave the checkout, since your applications do not belong inside it, and put the launcher on your path so that jcm is
a command wherever you are. On macOS and Linux:
cd ..
export PATH="$PWD/jcm/cli:$PATH"
That lasts for this terminal. To keep it, add the same line to your shell's profile (~/.zshrc or ~/.bashrc), with
the folder written out in full. On Windows, use jcm\cli\jcm.cmd from this folder.
Create an application
jcm new my-app
cd my-app
You should see Created my-app.
The blank template gives you a working application with one case type, Request. There are others:
Commands describes them.
Check it
jcm check
You should see passed.
The command builds and starts the application on an in-memory database, runs its tests, and checks its use of the
extension API and Jmix. All four stages should say passed. A refused configuration names the file and problem;
fix it before running the application interactively. This check does not leave a running application or a database
of sample cases. Add --browser when you also want the generated browser tests.
The first build downloads dependencies; later builds reuse them. A successful check proves the tested application at this revision, not every setting or a production deployment.
Open it in an IDE
For an IDE or a direct ./gradlew build, install a JDK 21 on your machine. The Docker-based jcm commands
include their own JDK and do not require a host installation.
In IntelliJ IDEA, open the generated application folder and select JDK 21 as the Project SDK. Under Settings → Build, Execution, Deployment → Build Tools → Gradle, use the project's Gradle wrapper and select JDK 21 for Gradle JVM. Reload the Gradle project after changing these settings.
Generated applications include gradle/gradle-daemon-jvm.properties with toolchainVersion=21, so the wrapper
selects an installed JDK 21 even when the shell's JAVA_HOME points to Java 17. The build also selects Java 21
for compilation. Keep this file in version control; it contains no machine-specific paths. It does not download
a missing JDK: install JDK 21 before importing the project.
Find the model and configuration folders
These are separate folders under src/main/. The model folder is not inside resources/jcm/.
- Data model —
src/main/jcm/model/: Data-model YAML, such asRequest.ymlorPermit.yml. The build generates entity classes from it.jcm changeloggenerates database changes and records the model and migration state inschema.jsonhere. - Runtime configuration —
src/main/resources/jcm/: Configuration grouped by kind:case-types/,workflows/,queues/,roles/,calendars/and other configured features.
Keep the model files, schema.json and generated database changelogs together in version control.
Run it
jcm run
You should see http://localhost:8080.
The first build downloads Gradle, Node and the application's dependencies, about 1 GB, which takes several minutes. If you ran the check above, this run reuses those cached dependencies. The command prints the address once the application is ready, with PostgreSQL and a mail catcher running beside it. The mail catcher is at http://localhost:8025.
Sign in
Open http://localhost:8080 and sign in as admin with the password admin. This is the template's local
administrator, for your own machine only; production refuses it. You land on an empty Inbox that says no queues are
set up for you, which is right for a new application. The menu on the left lists Requests, the template's case type.
When you have looked around, stop it. The database is kept for next time.
jcm run --stop
If something goes wrong, see Troubleshooting.
What is not available yet
Hosted environments are not available. jcm publish, jcm promote and the commands around them exist, but there is no
hosted service for them to reach yet. Hosted environments says what is planned.
What to read next
- Your first case type builds a small application step by step.
- The reference lists every configuration file, the extension API and every setting.