From 609ed30b7b4cc442dbf87f0b0ba9a3b8196b2536 Mon Sep 17 00:00:00 2001 From: Hardy Jonck Date: Thu, 18 Jun 2026 22:21:02 +0200 Subject: [PATCH 1/2] docs: Running Mendix 7 in Docker guide + CONTRIBUTING Add a version-specific walkthrough for booting a legacy Mendix 7.23 app via the mendix-7 crate (the model-default-constants gotcha, m2ee boot, cf-buildpack comparison) and link it from the README. Add a top-level CONTRIBUTING.md restating the no-Mendix-binary rule + the new-version recipe so GitHub surfaces it in the PR/issue UI. --- CONTRIBUTING.md | 30 +++++++++ README.md | 10 +++ docs/running-mendix-7-in-docker.md | 104 +++++++++++++++++++++++++++++ 3 files changed, 144 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 docs/running-mendix-7-in-docker.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..588a502 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,30 @@ +# Contributing + +Thanks for helping improve Mendix Runtime Crates! + +## The one hard rule: no Mendix binaries + +This repository ships **recipes only** — `Dockerfile`, `start.sh`, YAML, docs. It +must **never** contain a Mendix binary (`*.tar.gz`, `*.mda`, `*.mpr`, `*.jar`, +`*.war`, …). The Mendix runtime is pulled from `cdn.mendix.com` at build time, on +the build machine — never committed. + +A CI guard (`guard.sh`, run by `.github/workflows/no-mendix-binaries.yml`) fails +any change that adds a forbidden file pattern or any file over 256 KB. `main` is +protected: this check must pass before a PR can merge. Run it locally first: + +```sh +./guard.sh +``` + +## Adding a new Mendix version + +See **[Contributing a new version](README.md#contributing-a-new-version)**. In +short: copy the closest crate, set the `FROM` JDK base for that major (MX7/8 → 8, +MX9 → 11, MX10/11 → 21), set `ARG MENDIX_VERSION`, build, smoke-test against a real +app, and record the result in `versions.yaml` + `provenance.yaml`. + +## Pull requests + +Keep changes focused — one version or one doc per PR where practical. Be kind in +reviews and issues. diff --git a/README.md b/README.md index 337b01c..99609ed 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,16 @@ build time — these recipes publish no registry image, so name it whatever suit your pipeline. See each crate's `README.md` for the full env-var contract, bind-mount layout, and a `docker compose` smoke example. +## Guides + +Version-specific, step-by-step walkthroughs: + +- **[Running Mendix 7 in Docker](docs/running-mendix-7-in-docker.md)** — boot a + legacy Mendix 7.23 app (Java 8) with no Studio Pro, covering the + model-default-constants gotcha and the m2ee boot path. + +Per-version guides for Mendix 8 / 9 / 10 / 11 are on the way. + ## How distribution works (and the Mendix IP line) These recipes are distributed **recipe-only**: diff --git a/docs/running-mendix-7-in-docker.md b/docs/running-mendix-7-in-docker.md new file mode 100644 index 0000000..00bcf8f --- /dev/null +++ b/docs/running-mendix-7-in-docker.md @@ -0,0 +1,104 @@ +# Running Mendix 7 in Docker + +**Mendix 7.23** shipped in 2017 and runs on **Java 8**. It is long out of mainstream support, but plenty of organisations still maintain production Mendix 7 apps — and getting one to *run locally* for testing, debugging, CI, or a migration spike is painful: the official tooling assumes Studio Pro on Windows, the cloud buildpack bakes your model into a throwaway image, and the modern Mendix Docker guidance simply doesn't cover a runtime this old. + +The **`mendix-7` runtime crate** solves this. It is a model-agnostic, version-pinned Docker image that boots *any* Mendix 7.x application you bind-mount into it — no Studio Pro, no model baked into the image, no Mendix binaries committed to source control. + +> **TL;DR** +> ```bash +> cd crates/mendix-7 +> docker build --platform linux/amd64 --build-arg MENDIX_VERSION=7.23.8.58888 \ +> -t ontologylabs/mendix-runtime:7 . +> unzip your-mx7-app.mda -d ./tests/mda +> docker compose -f tests/docker-compose.smoke.yml up # → http://localhost:8080 +> ``` + +## What you get + +* **Java 8 + the Mendix 7.23 runtime**, pulled from `cdn.mendix.com` at build time (never committed). +* **Your model bind-mounted**, not baked — `docker compose restart` to reload, with zero dangling images. +* A **PostgreSQL-backed** runtime driven entirely through the **m2ee admin protocol** — the same protocol Mendix Cloud and `m2ee-tools` use against production Mendix 7 servers. +* Verified: this crate boots **MoneyWorksPortal 7.23.8** to a healthy **HTTP 200**. + +## Prerequisites + +* Docker (Docker Desktop on macOS/Windows, or any engine on Linux). +* An **unzipped MDA** of your Mendix 7 app — a directory containing `model/metadata.json`. (An `.mda` is just a zip; `unzip your.mda -d ./app/`.) +* That's it. No Studio Pro, no Windows, no Mendix account. + +## Step 1 — build the runtime image + +```bash +cd crates/mendix-7 +docker build \ + --platform linux/amd64 \ + --build-arg MENDIX_VERSION=7.23.8.58888 \ + -t ontologylabs/mendix-runtime:7.23.8.58888 \ + -t ontologylabs/mendix-runtime:7 \ + . +``` + +The Dockerfile `curl`s `https://cdn.mendix.com/runtime/mendix-7.23.8.58888.tar.gz` (~341 MB) and asserts the expected `runtimelauncher.jar` is present — so a CDN or layout change fails the build loudly rather than at runtime. The image is **reusable across every Mendix 7.23 app**; build it once. + +> **Apple Silicon / arm64:** the image is `linux/amd64` and runs under emulation. The pure-Java runtime works fine; expect a slower first boot (JVM container-start alone can take ~60 s under emulation). + +## Step 2 — run it against your app + +```yaml +# docker-compose.yml +services: + postgres: + image: postgres:14-alpine + environment: { POSTGRES_USER: mendix, POSTGRES_PASSWORD: mendix, POSTGRES_DB: mendix } + mendix: + image: ontologylabs/mendix-runtime:7.23.8.58888 + depends_on: [postgres] + environment: + ADMIN_PASSWORD: "ChangeMe2026!" # the runtime rejects weak passwords + DATABASE_ENDPOINT: "postgres://mendix:mendix@postgres:5432/mendix" + DEVELOPMENT_MODE: "true" + ports: ["8080:8080", "8090:8090"] + volumes: + - ./app:/opt/mendix/app # your unzipped MDA + - mendix-data:/opt/mendix/data +volumes: { mendix-data: {} } +``` + +```bash +docker compose up +curl -fsSI http://localhost:8080/ # 200 OK once the runtime is up +``` + +On first boot the crate creates the schema (DDL sync) and starts the runtime; subsequent boots are fast. Port `8080` is the app; `8090` is the m2ee admin protocol. + +## Mendix-7-specific gotchas (the things that actually trip people up) + +* **Java 8, not 11/21.** Mendix 7.x targets Java 8 — the crate's base image is `eclipse-temurin:8-jre-jammy`. Newer JDKs are not a drop-in for the MX7 runtime/toolchain. +* **Model-default constants must be supplied.** The Mendix runtime does **not** auto-apply a constant's *model default* when the deployment config omits it — that's normally the buildpack's job. Omit them and startup fails with `Could not find value for constant ''` during microflow-engine reload. The crate handles this automatically: `start.sh` reads the constants and their defaults from your model's `metadata.json` and supplies them. Override any value with the `MICROFLOW_CONSTANTS` env var (`{"Module.Constant":"value"}`). +* **`HttpHeaders` is not a recognised config key on MX7.** The runtime logs `Unknown configuration setting 'HttpHeaders'` and ignores it — harmless; leave `MXRUNTIME_HttpHeaders` empty. +* **Weak admin passwords are rejected.** `ADMIN_PASSWORD=1` throws inside `PasswordStrengthVerifier`. Use a real password. +* **The boot path is stable.** Mendix 7.23's `runtimelauncher.jar` + m2ee admin protocol are the *same* mechanism as Mendix 8/9/10/11 — so the identical `start.sh` drives every major. (We assert the launcher's presence at build time.) + +## How it differs from the cloud buildpack + +| | `cf-mendix-buildpack` image | `mendix-7` crate | +|---|---|---| +| Application model | **baked into the image** | **bind-mounted** | +| Reload | `docker build --no-cache` (~minutes) | `docker compose restart` (~seconds) | +| Disk per reload | ~785 MB dangling | 0 | +| Image per app/commit | many | one per Mendix version | +| Mendix binary in your repo | n/a | **never** (pulled from CDN at build) | + +## Troubleshooting + +* **`Could not find value for constant …`** — a no-default constant wasn't supplied. The crate auto-supplies model defaults; if you overrode `MICROFLOW_CONSTANTS`, make sure your JSON includes every required constant. +* **Hangs on first boot under emulation** — large apps doing DDL on amd64 emulation are slow; give it time (the bundled smoke test's poll timeout is configurable via `SMOKE_TIMEOUT`). +* **`runtimelauncher.jar not found` at build** — the CDN tarball layout changed or the version string is wrong; check `MENDIX_VERSION` matches your model's `RuntimeVersion` in `metadata.json`. + +## Provenance & licence + +The crate scaffolding (Dockerfile, `start.sh`, docs) is **Apache-2.0**. The Mendix runtime it downloads is Mendix's IP and is **never committed here** — it is `curl`ed from the official CDN at build time on your machine, and remains subject to [Mendix's terms of use](https://www.mendix.com/terms-of-use/). + +--- + +*Part of [mendix-runtime-crates](https://github.com/ontologylabs/mendix-runtime-crates) — the runtime layer of the **mxto** Mendix toolchain. Maintaining a Mendix 8, 9, or 10 app? The same pattern works for every version — see the the [README](../README.md) page.* From 355a3e88e9bce69148abe828402c00ddf5e93eea Mon Sep 17 00:00:00 2001 From: Hardy Jonck Date: Thu, 18 Jun 2026 22:21:43 +0200 Subject: [PATCH 2/2] docs: fix footer typo in Mendix 7 guide --- docs/running-mendix-7-in-docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/running-mendix-7-in-docker.md b/docs/running-mendix-7-in-docker.md index 00bcf8f..fbb50a5 100644 --- a/docs/running-mendix-7-in-docker.md +++ b/docs/running-mendix-7-in-docker.md @@ -101,4 +101,4 @@ The crate scaffolding (Dockerfile, `start.sh`, docs) is **Apache-2.0**. The Mend --- -*Part of [mendix-runtime-crates](https://github.com/ontologylabs/mendix-runtime-crates) — the runtime layer of the **mxto** Mendix toolchain. Maintaining a Mendix 8, 9, or 10 app? The same pattern works for every version — see the the [README](../README.md) page.* +*Part of [mendix-runtime-crates](https://github.com/ontologylabs/mendix-runtime-crates) — the runtime layer of the **mxto** Mendix toolchain. Maintaining a Mendix 8, 9, or 10 app? The same pattern works for every version — see the [README](../README.md).*