Docker Workflow

Docker Build & Run Skill

This skill guides you through building, running, and testing a Mendix application using Docker inside a devcontainer.

When to Use This Skill

Use this when:

• The user wants to run their Mendix app locally in Docker
• The user wants to build a deployable container image
• The user asks about testing or validating their app
• The user needs to set up the Docker workflow for the first time

Prerequisites

The devcontainer created by mxcli init includes:

• JDK 21 (Adoptium temurin-21-jdk) — required by MxBuild
• Docker-in-Docker (or Podman-in-Podman) — container runtime inside the devcontainer
• Port forwarding — ports 8080 (app) and 8090 (admin) auto-forwarded

Podman Support

mxcli auto-detects Docker or Podman. To force Podman:

export MXCLI_CONTAINER_CLI=podman

When using mxcli init, pass --container-runtime podman to generate a devcontainer with Podman-in-Podman instead of Docker-in-Docker. Requires Podman 4.7+ (ships podman compose natively).

Architecture

host machine (browser at localhost:8080)
  └── Docker or Podman (host daemon)
      └── Devcontainer (VS Code)
          ├── mxcli, JDK 21, project files
          └── Docker/Podman daemon (docker-in-docker or podman-in-podman)
              └── docker/podman compose stack
                  ├── mendix container (8080, 8090)
                  │     └── /mendix ← volume mount from .docker/build/
                  └── postgres container (5432)

The Mendix container uses a volume mount (not COPY) — .docker/build/ is mounted directly into the container at /mendix. This means after rebuilding the PAD, you only need to restart the container (no Docker image rebuild). The generated Dockerfile is kept in the build output for production image builds.

Quick Start: One Command

The easiest way to get a Mendix app running in Docker:

# Setup, build, and start in one command
mxcli docker run -p app.mpr

# with startup confirmation (waits for "runtime successfully started")
mxcli docker run -p app.mpr --wait

# Fresh start (removes database volumes first)
mxcli docker run -p app.mpr --fresh --wait

docker run handles everything: downloads MxBuild and runtime (if not cached), initializes the Docker stack (if needed), builds the PAD package, starts the containers, and optionally waits for the runtime to report successful startup.

Creating an Empty Mendix App

Recommended: Use mxcli new to create a project with all tooling in one step:

mxcli new MyApp --version 11.8.0

This downloads MxBuild, creates a blank project, sets up AI tooling and Dev Container, and installs the correct Linux mxcli binary. Open the resulting folder in VS Code and reopen in Dev Container.

Manual approach (if you need more control):

# Download mxbuild if not already cached
mxcli setup mxbuild --version 11.6.4

# create a blank project
mkdir -p /path/to/my-app
~/.mxcli/mxbuild/{version}/modeler/mx create-project --app-name MyApp --output-dir /path/to/my-app

# Initialize AI tooling
mxcli init /path/to/my-app

The mx create-project command creates an MPR v2 project with the standard Mendix module structure. You can then use the Docker workflow to build and run it.

Caveat: Blank projects have no demo users — login will fail until you configure security via MDL or Studio Pro. See manage-security for setting up demo users.

Step-by-Step Workflow

If you prefer more control, use the individual commands:

1. Setup MxBuild and Runtime (first time only)

MxBuild and the Mendix runtime are auto-downloaded when needed, but you can pre-download:

# Download MxBuild matching the project version
mxcli setup mxbuild -p app.mpr

# Download Mendix runtime matching the project version
mxcli setup mxruntime -p app.mpr

# or specify version explicitly (without a project)
mxcli setup mxbuild --version 11.6.4
mxcli setup mxruntime --version 11.6.4

# or preview what would be downloaded
mxcli setup mxbuild -p app.mpr --dry-run
mxcli setup mxruntime -p app.mpr --dry-run

MxBuild is cached at ~/.mxcli/mxbuild/{version}/ and the runtime at ~/.mxcli/runtime/{version}/. Both are reused across builds.

Runtime-to-MxBuild Copying (PAD Build Prerequisite)

MxBuild 11.6.3+ expects runtime files (pad/, lib/, launcher/, agents/) inside its own runtime/ directory, but mxcli setup mxbuild only downloads the build tools (not the full runtime). If the PAD build fails with StudioPro.conf.hbs does not exist or ClassNotFoundException, copy the runtime directories into mxbuild:

version=11.6.4  # replace with your version

# after downloading both mxbuild and mxruntime:
cp -r ~/.mxcli/runtime/$version/runtime/pad ~/.mxcli/mxbuild/$version/runtime/pad
cp -r ~/.mxcli/runtime/$version/runtime/lib ~/.mxcli/mxbuild/$version/runtime/lib
cp -r ~/.mxcli/runtime/$version/runtime/launcher ~/.mxcli/mxbuild/$version/runtime/launcher
cp -r ~/.mxcli/runtime/$version/runtime/agents ~/.mxcli/mxbuild/$version/runtime/agents

Important: The PAD build output may only include partial runtime bundles (5 jars instead of 354). If the runtime fails to start with ClassNotFoundException: com.mendix.container.support.EventProcessor, copy the full runtime into the PAD build output:

rm -rf /path/to/project/.docker/build/lib/runtime
cp -r ~/.mxcli/runtime/$version/runtime /path/to/project/.docker/build/lib/runtime

2. Initialize Docker stack (first time only)

# generate docker-compose.yml, .env, Dockerfile in .docker/
mxcli docker init -p app.mpr

This creates a .docker/ directory with Docker Compose configuration for the Mendix app + PostgreSQL.

Port conflicts: If default ports (8080/8090/5432) are already in use, check with ss -tlnp | grep -E '808|809|543' and use --port-offset N to shift all ports:

# check which ports are occupied
ss -tlnp | grep -E '808[0-9]|809[0-9]|543[0-9]'

# use offset to avoid conflicts (e.g., offset 5 → 8085/8095/5437)
mxcli docker init -p app.mpr --port-offset 5

3. Check project for errors

# Quick validation using mx check
mxcli docker check -p app.mpr

4. Build the Portable App Distribution (PAD) package

# build (auto-downloads MxBuild if not cached)
mxcli docker build -p app.mpr

# Preview what would happen
mxcli docker build -p app.mpr --dry-run

# Skip pre-build check
mxcli docker build -p app.mpr --skip-check

This:

1. Detects the Mendix version (requires >= 11.6.1)
2. Locates or downloads MxBuild and JDK 21
3. Runs MxBuild to produce a PAD package (ZIP)
4. Extracts the PAD ZIP (cleans up old ZIPs after extraction)
5. Generates a Dockerfile if MxBuild didn't produce one (11.6.3+)
6. Downloads and injects the Mendix runtime if not in PAD output
7. Applies version-aware patches (CMD fix, base image, healthcheck, etc.)

5. Start the application

# Start in foreground (see logs directly)
mxcli docker up -p app.mpr

# Start in background
mxcli docker up -p app.mpr --detach

# Start in background and wait for runtime startup confirmation
mxcli docker up -p app.mpr --detach --wait

# Fresh start (removes database volumes)
mxcli docker up -p app.mpr --fresh

# Custom wait timeout (default: 300 seconds)
mxcli docker up -p app.mpr --detach --wait --wait-timeout 600

The --wait flag (requires --detach) tails the container logs and waits until the Mendix runtime reports "Runtime successfully started" or a timeout/failure is detected.

The app is available at:

• http://localhost:8080 — application
• http://localhost:8090 — admin console (password in .docker/.env)

6. Query data with OQL

# run OQL queries against the live runtime (read-only preview mode)
mxcli oql -p app.mpr "select Name, Email from MyModule.Customer"

# json output for piping
mxcli oql -p app.mpr --json "SELECT count(c.ID) FROM MyModule.Order AS c" | jq '.[0]'

# Test a view entity query before embedding it in MDL
mxcli oql -p app.mpr "select datepart(YEAR, o.Date) as Year, sum(o.Total) as Revenue from Sales.Order as o GROUP by datepart(YEAR, o.Date)"

7. Monitor and manage

# view container status
mxcli docker status -p app.mpr

# view logs
mxcli docker logs -p app.mpr
mxcli docker logs -p app.mpr --follow
mxcli docker logs -p app.mpr --tail 50

# open a shell in the container
mxcli docker shell -p app.mpr
mxcli docker shell -p app.mpr --exec "ls -la /mendix"

8. Stop the application

# Stop containers
mxcli docker down -p app.mpr

# Stop and remove database volumes
mxcli docker down -p app.mpr --volumes

Common Workflow: Edit, Rebuild, Test

After making MDL changes:

# 1. apply MDL changes
mxcli exec changes.mdl -p app.mpr

# 2. Rebuild and restart (one command)
mxcli docker run -p app.mpr --fresh --wait

Or step by step:

# 1. apply MDL changes
mxcli exec changes.mdl -p app.mpr

# 2. Validate
mxcli docker check -p app.mpr

# 3. Rebuild
mxcli docker build -p app.mpr

# 4. restart with fresh database and wait for startup
mxcli docker up -p app.mpr --fresh --detach --wait

# 5. check it's running
mxcli docker status -p app.mpr

Hot Reload

The Mendix runtime supports hot reloading via the M2EE admin API. Because mxcli's Docker setup uses a bind mount (.docker/build/ → /mendix/), rebuilt PAD output is immediately visible to the running runtime — no Docker image rebuild or container restart needed.

How It Works

1. mxcli docker build compiles the project into .docker/build/ (the bind-mounted directory)
2. mxcli docker reload rebuilds the PAD (same as docker build) then calls the M2EE reload_model action on port 8090
3. The runtime re-reads the model from disk in ~100ms
4. Connected browsers auto-refresh via the /mxdevtools/ WebSocket

Note: By default, docker reload includes a full build step (~55s). Use --model-only to skip the build when you've already run docker build separately:

Typical hot reload cycle (with separate build):

mxcli exec script.mdl -p app.mpr                   # ~1s   — update model
mxcli docker build -p app.mpr                       # ~55s  — compile PAD
mxcli docker reload -p app.mpr --model-only         # ~100ms — reload only
# Total: ~56s (vs ~75s with full container restart)

One-step reload (build + reload combined):

mxcli exec script.mdl -p app.mpr                    # ~1s   — update model
mxcli docker reload -p app.mpr                      # ~56s  — build + reload

Model Reload

For logic changes (microflows, nanoflows, pages, security):

# 1. apply changes
mxcli exec changes.mdl -p app.mpr

# 2. Rebuild PAD (skip pre-check for speed)
mxcli docker build -p app.mpr --skip-check

# 3. Hot reload the runtime (--model-only skips redundant rebuild)
mxcli docker reload -p app.mpr --model-only

Or combine build + reload in one command (no --model-only):

# 1. apply changes
mxcli exec changes.mdl -p app.mpr

# 2. build and reload in one step
mxcli docker reload -p app.mpr --skip-check

The --direct flag connects to the admin API via HTTP instead of routing through docker compose exec (faster, requires the admin.addresses = ["*"] build patch which is applied automatically):

mxcli docker reload -p app.mpr --direct

CSS-Only Reload

For theme/styling changes, SCSS must first be compiled by MxBuild into the PAD output. The --css flag skips the model reload step — it only pushes already-compiled CSS to browsers via WebSocket.

# Correct workflow for SCSS/theme changes:
mxcli docker build -p app.mpr            # compile SCSS into PAD (~55s)
mxcli docker reload -p app.mpr --css     # push compiled CSS to browsers (~instant)

Note: --css does NOT compile SCSS. If you skip the build step, the browser will not reflect your SCSS changes. The "instant" refers to the browser update via WebSocket, not end-to-end time.

This calls the M2EE update_styling action, which pushes CSS changes to all connected browsers via the /mxdevtools/ WebSocket. Browsers update their stylesheets without a full page reload.