Just Run It: Understanding and Using the “justfile”

Working with a large codebase like dotCMS often involves remembering and typing numerous Maven commands. While you can certainly continue using the traditional approach, we've added a helpful tool that makes life easier: the justfile. This simple text file at the root of our repository provides easy-to-remember command aliases that can speed up your development process. Let's explore how this optional but recommended tool can benefit your workflow.

The Challenge: Developer Convenience

We all know the scenario — you need to build the project, but was it mvnw clean install -DskipTests or something else? Did you need any special profiles for your particular use case?

While Maven is powerful and flexible, it can sometimes require consulting documentation or asking colleagues to remember the exact command syntax you need. This is where the justfile comes in — it's completely optional, but can save you time and energy.

What is the justfile?

At its core, the justfile is simply a file at the root of your GitHub repository that provides aliases for common commands. Even without installing anything, you can use it as reference documentation. Each entry looks something like this:

# Builds the project without running tests, useful for quick iterations
build:
   ./mvnw -DskipTests clean install

This means instead of remembering the longer Maven command, you can remember "just build" — which is much easier!

Using justfile: Two Approaches

Option 1: Use it as documentation

You don't need to install anything new. Simply refer to the justfile to see the underlying Maven or other cli commands for common operations. This works great if you prefer sticking with your current workflow but occasionally need a reminder of the right command syntax.

Option 2: Install the just command runner (recommended)

To get the full benefit, you can install the just command runner:

On macOS

brew install just

For other systems, check: https://github.com/casey/just

Once installed, you can run commands like:

just build
just dev-run
just test-integration

The best part? Running just by itself shows all available commands with descriptions:

Available recipes:
    default                  # Lists all available commands in this justfile
    build                    # Builds the project without running tests
    dev-run                  # Starts the dotCMS application in Docker
    # ... and many more

Justfile Features

Commands Accept Parameters

Some commands let you customize their behavior:

# Run on default port (8082)
just dev-start-on-port

# Run on custom port
just dev-start-on-port 8090

Run Multiple Versions Side by Side

Need to test different versions? No problem:

just docker-ext-run 22.03.15_lts_cc51d80

This starts that specific version in a separate context, so multiple versions can run simultaneously without conflicts.

Commands Work From Any Folder

No need to cd back to the project root; just commands work from any subfolder in the project.

Organized by Category

The justfile includes commands for:

• Building: Standard, quick, and production builds

• Development: Running locally with various debug options

• Testing: Integration, Postman, Karate, and E2E tests

• Docker: Managing containers and versions

• Maven Helpers: Dependency management tools

• Environment Setup: Checking and installing dependencies

IDE Integration

For even more convenience, install plugins for your integrated development environment (IDE):

• JetBrains IDEs: just plugin

• VS Code: just syntax plugin

Everyday Examples

Here are some common tasks made easier:

Benefits Without Obligation

The beauty of the justfile is that it's completely optional. You can:

• Ignore it completely and use Maven directly

• Use it occasionally as reference documentation

• Install just and use it for some commands

• Fully adopt it for your daily workflow

There's no right or wrong approach — use whatever makes you most productive!

Give it a Try!

Take a look at the justfile in the dotCMS repository. You might discover useful commands you didn't know existed. Since it's tied to your current branch, the commands automatically stay in sync with the codebase you're working on.

We welcome feedback on which commands you find most helpful and what other shortcuts you'd like to see added. The justfile evolves alongside our codebase to make development smoother.

Ready to simplify your workflow? Just run it!

Further Resources

• just GitHub Repository

• just Documentation

• just Cheatsheet

• dotCMS Core Repository