fix(build): make wheels-starter-app installable and bootable from ForgeBox (#3199)

The published ForgeBox starter app was unusable end-to-end:

(a) `box install wheels-starter-app` FAILED. box.json declared a dependency
    on slug "wheels-authenticateThis" which does not exist on ForgeBox
    ("entry slug invalid or does not exist"), aborting the whole install.
    The authenticateThis() mechanism the app uses is the plugin already
    vendored under plugins/authenticateThis/ — the ForgeBox dependency was
    redundant. Drop the bogus dependency + installPath; keep wheels-core so
    the framework still lands in vendor/wheels/.

(b) Even when installed, the app booted HTTP 500 "key [DB_CLASS] doesn't
    exist" at config/app.cfm:14 — the datasource read this.env.DB_CLASS but
    no .env shipped or scaffolded (only .env.example). Replace the
    env-driven MySQL datasource with a zero-config H2 embedded database
    (org.h2.Driver, bundled with Lucee). The H2 Lucee extension is declared
    in server.json so `box server start` auto-installs it — no manual
    LUCEE_EXTENSIONS or .env needed. Add a starterApp_test datasource for the
    app test suite and a db/h2/ data directory.

.env is now optional and documented as such (server-based DB instructions
preserved in .env.example comments + README). README Quick Start rewritten
to the real flow: box install -> box server start -> wheels migrate latest.

Verified in CommandBox docker (ortussolutions/commandbox:latest) against the
prepare-starterApp.sh build output: box install succeeds (wheels-core only),
the server boots and the H2 datasource loads, `migrate latest` creates the
schema + seeds, and GET / returns HTTP 200 with the seeded site title.

Fixes #3181

Signed-off-by: Peter Amiri <petera@pai.com>
Co-authored-by: Peter Amiri <petera@pai.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

examples/starter-app/.env.example

@@ -1,18 +1,35 @@
-LUCEE_EXTENSIONS=465E1E35-2425-4F4E-8B3FAB638BD7280A;name=H2;version=1.3.172
-cfconfig_adminPassword=commandbox
+# .env is OPTIONAL for the starter app.
+#
+# Out of the box the app uses an H2 embedded database configured directly in
+# config/app.cfm, so it boots with NO .env file and NO external database
+# server. Copy this file to .env only when you want to:
+#   - set a reload password (WHEELS_RELOAD_PASSWORD), or
+#   - point the app at a server-based database (MySQL/PostgreSQL/etc.).
+#
+# The H2 Lucee extension is declared in server.json and installed
+# automatically by `box server start` — you do NOT need to set
+# LUCEE_EXTENSIONS yourself.
+
 environment=development
-# Reload password for ?reload=true and `wheels reload`. Blank disables URL-based reload.
+
+# Reload password for ?reload=true and `wheels reload`. Blank disables
+# URL-based reload (and the state-changing CLI bridge commands).
 WHEELS_RELOAD_PASSWORD=
 
-DB_HOST=localhost
-DB_PORT=3306
-DB_NAME=wheelsStarterApp
-DB_USER=root
-DB_PASSWORD=2a26eae88f2d1144bde37c5aef530354ee689c2ec7c6306877a4b34b41ae6999
-DB_CLASS=com.mysql.cj.jdbc.Driver
-DB_BUNDLENAME=com.mysql.cj
-DB_BUNDLEVERSION=9.3.0
-DB_CONNECTIONLIMIT=-1
-DB_LIVETIMEOUT=15
-DB_ALWAYSSETTIMEOUT=true
-DB_VALIDATE=false
+# ---------------------------------------------------------------------------
+# Server-based database (OPTIONAL — only if you swap the datasource in
+# config/app.cfm to read these this.env.DB_* values instead of H2). Example
+# below is for MySQL; the password value is the Lucee-encrypted form.
+# ---------------------------------------------------------------------------
+# DB_HOST=localhost
+# DB_PORT=3306
+# DB_NAME=wheelsStarterApp
+# DB_USER=root
+# DB_PASSWORD=2a26eae88f2d1144bde37c5aef530354ee689c2ec7c6306877a4b34b41ae6999
+# DB_CLASS=com.mysql.cj.jdbc.Driver
+# DB_BUNDLENAME=com.mysql.cj
+# DB_BUNDLEVERSION=9.3.0
+# DB_CONNECTIONLIMIT=-1
+# DB_LIVETIMEOUT=15
+# DB_ALWAYSSETTIMEOUT=true
+# DB_VALIDATE=false

examples/starter-app/.gitignore

@@ -17,3 +17,8 @@ settings.json
 /plugins/**/
 .env
 /vendor
+
+# H2 embedded database data files (created at runtime; keep the directory)
+/db/h2/*.db
+/db/h2/*.trace.db
+!/db/h2/.keep

examples/starter-app/README.md

@@ -147,18 +147,41 @@ plugins/            # Third-party plugins
   - Adobe ColdFusion 2018/2021/2023/2025
   - Lucee 5, Lucee 6, Lucee 7
   - Boxlang
-- **Database Engine**: Choose one of the following:
-  - MySQL
-  - PostgreSQL
-  - Microsoft SQL Server
-  - Oracle Database
-  - SQLite Database
-  - H2 Database (for development/testing)
 
-### Environment Configuration
+### Install and Run (zero-config)
+
+The starter app boots out of the box with no database server and no `.env` file.
+It ships with an **H2 embedded database** (the H2 Lucee extension is declared in
+`server.json`, so CommandBox installs it automatically on first start) and the
+`authenticateThis` plugin is bundled under `plugins/`.
+
+```bash
+# 1. Install the framework (lands in vendor/wheels/)
+box install
+
+# 2. Start the server (auto-installs the H2 extension, boots the app)
+box server start
+
+# 3. Create the schema and seed the default data
+wheels migrate latest
+
+# 4. Reload the application so the seeded settings load
+#    (or just restart the server). Then open the site:
+box server open
+```
+
+Default sign-in credentials are seeded by the migrations — see
+`app/migrator/migrations/20180519105944_Adds_Default_UserAccounts.cfc`.
+
+### Using a server-based database instead
+
+To point the app at MySQL, PostgreSQL, SQL Server, or Oracle:
 
 1. Copy `.env.example` to `.env`
-2. Configure database settings based on your chosen database:
+2. Configure database settings based on your chosen database (see below)
+3. Replace the H2 datasource block in `config/app.cfm` with one that reads the
+   `this.env.DB_*` values (the original env-driven MySQL example is preserved in
+   the comments of `.env.example`)
 
 #### MySQL Configuration
 

examples/starter-app/box.json

@@ -28,12 +28,10 @@
         ".env.example"
     ],
     "dependencies": {
-        "wheels-core": "^4.0.0",
-        "wheels-authenticateThis":"^1"
+        "wheels-core": "^4.0.0"
     },
     "installPaths": {
-        "wheels-core": "vendor/wheels/",
-        "wheels-authenticateThis":"plugins/authenticateThis/"
+        "wheels-core": "vendor/wheels/"
     },
     "private":false,
     "license":[

examples/starter-app/config/app.cfm

@@ -10,20 +10,27 @@
 	// Added via Wheels CLI
 	this.name = "starterApp";
 
+	// H2 embedded database — boots out of the box with no .env or external
+	// database server. The H2 driver (org.h2.Driver) is bundled with Lucee, so
+	// it works on a plain `box install` / CommandBox install without any extra
+	// JDBC driver. MODE=MySQL gives MySQL-compatible SQL. Data files live under
+	// db/h2/. Run `wheels migrate latest` after install to create the schema.
+	//
+	// To use a server-based database (MySQL/PostgreSQL/etc.) instead, copy
+	// .env.example to .env, fill in your credentials, and swap the datasource
+	// definition below for one that reads this.env.DB_* (see .env.example for
+	// the full set of keys).
 	this.datasources["starterApp"] = {
-		class: this.env.DB_CLASS, 
-		bundleName: this.env.DB_BUNDLENAME, 
-		bundleVersion: this.env.DB_BUNDLEVERSION,
-		connectionString: "jdbc:mysql://#this.env.DB_HOST#:#this.env.DB_PORT#/#this.env.DB_NAME#?characterEncoding=UTF-8&serverTimezone=UTC&maxReconnects=3",
-		username: this.env.DB_USER,
-		password: "encrypted:#this.env.DB_PASSWORD#",
-		
-		// optional settings
-		connectionLimit: val(this.env.DB_CONNECTIONLIMIT), // default:-1
-		liveTimeout: val(this.env.DB_LIVETIMEOUT), // default: -1; unit: minutes
-		alwaysSetTimeout: this.env.DB_ALWAYSSETTIMEOUT EQ "true", // default: false
-		validate: this.env.DB_VALIDATE EQ "true" // default: false
-		
+		class: "org.h2.Driver",
+		connectionString: "jdbc:h2:file:" & expandPath("../db/h2/starterApp") & ";MODE=MySQL",
+		username: "sa"
+	};
+
+	// Test database datasource (used by the app test suite).
+	this.datasources["starterApp_test"] = {
+		class: "org.h2.Driver",
+		connectionString: "jdbc:h2:file:" & expandPath("../db/h2/starterApp_test") & ";MODE=MySQL",
+		username: "sa"
 	};
 
 	// buffer the output of a tag/function body to output in case of a exception

examples/starter-app/db/h2/.keep

@@ -14,5 +14,8 @@
     },
     "app":{
         "cfengine":"lucee"
+    },
+    "env":{
+        "LUCEE_EXTENSIONS":"465E1E35-2425-4F4E-8B3FAB638BD7280A;name=H2;version=1.3.172"
     }
 }