Running Wheels 4 in a subfolder - And figuring out tests (broken)

[mikegrogan]

Hi. Our local environment uses Commandbox using a single site architecture. On our production server it's ACF with IIS in front of it. We have 6 or so separate Wheels instances running under subfolders.

Directory Structure

├── config/
│   ├── coldfusion/
│   │   └── cfconfig.json
│   └── urlrewriting/
│       └── rules.txt
├── server.json   <--- everything setup for commandbox
└── wwwroot/
    ├── wheelsproject1/
    ├── wheelsproject2/
    ├── wheelsproject3/
    └── wheelsproject4/
        ├── app/
        ├── config/
        │   ├── settings.cfm
        ├── public/
        ├── tests/
        │   ├── runner.cfm
        │   └── TestRunner.cfc
        └── box.json

Wheels obviously wasn't completely intended to be used under a subfolder, but it's worked well for years. In trying to move to wheels 3 and then 4 quickly i had to rewrite the URL rules.

Commandbox URL rewriting in wheels 4 (rules.txt) (when setup as a subfolder)

# 1. Skip standard ColdFusion/Lucee engine paths completely
regex( pattern='^/(wheelsproject1|wheelsproject2|wheelsproject3)/(flex2gateway|jrunscripts|cfide|cf_scripts|cfformgateway|cffileservlet|lucee)', case-sensitive=false ) -> done;

# 2. MATCH PHYSICAL ASSETS: Route asset folders straight into the /public folder and stop processing cleanly
regex( pattern='^/(wheelsproject1|wheelsproject2|wheelsproject3)/(?:public/)?(files|images|javascripts|miscellaneous|stylesheets|robots.txt|favicon.ico|sitemap.xml)(.*)$', case-sensitive=false ) -> { rewrite('/${1}/public/${2}${3}'); done; }

# 3a. ALLOW FORM POSTS WITH /PUBLIC/: Rewrite silently so POST payload data isn't lost.
method(POST) and regex( pattern='^/(wheelsproject1|wheelsproject2|wheelsproject3)/public/(?!index\.cfm)(.*)$', case-sensitive=false ) -> { rewrite('/${1}/public/index.cfm/${2}%q'); done; }

# 3b. STRIP PUBLIC FROM URL BAR (GET requests only): Hard-redirect to the clean path and PRESERVE THE QUERY STRING
method(GET) and regex( pattern='^/(wheelsproject1|wheelsproject2|wheelsproject3)/public/(?!index\.cfm|files|images|javascripts|miscellaneous|stylesheets|robots.txt|favicon.ico|sitemap.xml)(.*)$', case-sensitive=false ) -> redirect('/${1}/${2}%q');

# 4. STANDARD ROUTING: Map clean MVC URLs invisibly to the nested index.cfm front controller (Excluding tests)
regex( pattern='^/(wheelsproject1|wheelsproject2|wheelsproject3)/(?!public/|tests/)(.*)$', case-sensitive=false ) -> rewrite('/${1}/public/index.cfm/${2}%q');

For IIS in wheels4 I'm setting up web.config files under each application.

config/settings.cfm Tweak to hide public in urls

if (StructKeyExists(application, "$wheels") AND StructKeyExists(application.$wheels, "webPath")) {
    if (Right(application.$wheels.webPath, 8) EQ "/public/") {
        application.$wheels.webPath = ReplaceNoCase(application.$wheels.webPath, "public/", "");
        // Keep rootPath and rootcomponentPath synchronized with the clean webPath
        application.$wheels.rootPath = "/" & ListChangeDelims(application.$wheels.webPath, "/", "/");
        application.$wheels.rootcomponentPath = ListChangeDelims(application.$wheels.webPath, ".", "/");
        application.$wheels.wheelsComponentPath = ListAppend(application.$wheels.rootcomponentPath, "wheels", ".");
    }
}	

Everything just loads up like: https://hostname:443/wheelsproject1, https://hostname:443/wheelsproject2, https://hostname:443/wheelsproject3, etc.

Again, this has worked fine for years under 2.5. However the wheels-core pages and testing always kind of break slightly. Navigation links don't work as they are hard coded. Minor things that I can tweak.

But now with the new vendor architecture and the possibility of overwriting any core tweaks with an update using Box install I'm wondering if any consideration could be made to allow wheels to run under a sub folder? To be clear, the only thing really not working from what I can see is the tests folder. Have the code not assume it's always running under the root?

Tests Review so far (running under a subfolder)

I'm not really at the point to understand it enough to create a PR, but I did finally get it working in a hacked sort of way through the web interface. The CLI is still broken, but haven't reviewed.

Using the wheels bottom nav I can finally load up https://localhost/wheelsproject1/wheels/app/tests and have a successful page load and tests passing. It's not perfect though. The application scope hacks break the main application, which a reload=true fixes. They seem to fight each other and haven't figured it out.

1. Part of the issue is under public/application.cfc. It sets the this.wheels.rootPath = getDirectoryFromPath(getBaseTemplatePath());. I had to tweak it to something like
   local.currentDirectory = getDirectoryFromPath(getCurrentTemplatePath());
   this.wheels.rootPath = getCanonicalPath(local.currentDirectory & "../");
2. The application setup still wasn't getting into the /tests folder properly. I was trying to setup a /tests/application.cfc and inherit some of the information from public/application.cfc. Again it kind of works, but is too hacky to really share.
3. Worked through some Oracle database syntax issues, one that I did a PR.

That's about as far as I got. I'm trying to run a test wheels4 app under the root and compare, but again not perfect yet. Thanks for any review of running wheels as as subfolder!

[bpamiri]

Hi @mikegrogan — this is a genuinely great write-up, thank you. The level of detail (rewrite rules, the webPath tweak, the test bootstrap notes) is exactly what makes this actionable rather than hypothetical, and the fact that you've run six instances this way since 2.5 is strong evidence the core idea is sound. We'd like to support subfolder deployment more deliberately. A few things we dug into that I want to share, partly to confirm your findings and partly to ask for your steer before we scope it.

The runtime layer is in better shape than it looks — and that's by design. webPath is derived from cgi.script_name (in onapplicationstart.cfc) by stripping the filename, so the subfolder prefix is captured automatically — which is why your links, asset tags, and redirects have "just worked" for years. Route matching keys off path_info (front-controller-relative), so the test routes like /wheels/app/tests still match under a subfolder — consistent with you being able to load the test page in the browser. (The 4.x vite asset paths use the same webPath mechanism, so they fall out for free too.) So we don't think the runtime needs much: mostly documenting your CommandBox rules.txt + an IIS web.config template + the config/settings.cfm "hide /public/" snippet as an official deployment recipe, so you never have to patch core and box install can't clobber you. The this.wheels.rootPath = getDirectoryFromPath(getBaseTemplatePath()) anchor you flagged is a real edge and worth hardening.

The tests folder is the real work, and you've put your finger on exactly why. The web test runner mutates the live application.wheels / application.wo in place, backs the original up to application.$$$wheels, and restores at end-of-response. That's a process-global side effect, which is precisely your "the application scope hacks break the main application, reload=true fixes it, they fight each other" symptom. (Tell-tale: there's already a $restoreTestRunnerApplicationScope() recovery hook wired into onAbort — so this fragility predates subfolder use; subfolder deployment just exposes it more often.) Doing this right means isolating test config into a request-scoped overlay instead of touching the global — which is worth doing for everyone, but it's a cross-engine-sensitive refactor we'd want to treat as its own effort. The CLI breakage you mentioned is smaller: wheels test builds an absolute /wheels/app/tests URL with no subfolder segment, so a --base-path-style prefix should unblock it.

Our rough thinking is to phase it: (1) docs/templates + the CLI base-path fix + the rootPath hardening (low risk, closes most of your day-to-day pain), then (2) the test-isolation refactor as a separate tracked issue.

Before we commit, a few questions where your real-world setup is the deciding factor:

• One CF instance, multiple apps, or one Application.cfc per subfolder? Your tree suggests per-app Application.cfc, which would mean the /wheels mapping resolves cleanly per app — but if any prod app shares a CF context we'd need to audit the absolute /wheels/tests/... includes more carefully.
• What's fronting IIS in prod — the URL Rewrite module, or something else? The discussion shows your CommandBox rules; a matching battle-tested web.config would be the other half of the recipe.
• Recipe vs. mode: would you rather subfolder support be a documented deployment recipe (lower risk, you assemble the pieces), or a first-class framework knob like set(basePath="/wheelsproject1") that's more discoverable but more invasive? Your preference here genuinely shapes the design.
• CLI shape: would wheels test --base-path=/wheelsproject1 (explicit) work for you, or would you expect it auto-derived from server.json/box.json?

If you're up for it, sharing your IIS web.config and confirming the one-Application.cfc-per-subfolder assumption would let us turn this into a concrete plan quickly. Really appreciate you pushing on this — it's the kind of deployment story we want Wheels 4 to handle cleanly.

[mikegrogan]

I know I'm talking to AI, but I'm here for it. Realize it's hard to respond to everything! Hopefully a human can review at some point as needed.

Web.config that is in the root of each wheels instance, under the root. So far it seems to work with Wheels 4 on our DEV server. None of this is in production yet. This uses the URL Rewrite module for IIS.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
	<system.webServer>
		<rewrite>
			<rules>
				<rule name="CFWheels Static Assets Pass" stopProcessing="true">
					<match url="^(?:public/)?(files|images|javascripts|miscellaneous|stylesheets|robots.txt|favicon.ico|sitemap.xml)(.*)$" ignoreCase="true" />
					<action type="Rewrite" url="public/{R:1}{R:2}" />
				</rule>
				<rule name="CFWheels Public Form POST Pass" stopProcessing="true">
					<match url="^public/(?!index\.cfm)(.*)$" ignoreCase="true" />
					<conditions>
						<add input="{REQUEST_METHOD}" pattern="^POST$" />
					</conditions>
					<action type="Rewrite" url="public/index.cfm/{R:1}" />
				</rule>
				<rule name="CFWheels Strip Public GET Redirect" stopProcessing="true">
					<match url="^public/(?!index\.cfm|files|images|javascripts|miscellaneous|stylesheets|robots.txt|favicon.ico|sitemap.xml)(.*)$" ignoreCase="true" />
					<conditions>
						<add input="{REQUEST_METHOD}" pattern="^GET$" />
					</conditions>
					<action type="Redirect" url="wheelsproject1/{R:1}" redirectType="Found" />
				</rule>
				<rule name="CFWheels MVC Routing" stopProcessing="true">
					<match url="^(?!public/)(.*)$" ignoreCase="true" />
					<conditions logicalGrouping="MatchAll">
						<add input="{SCRIPT_NAME}" negate="true" pattern="^/wheelsproject1/(cf_script|flex2gateway|jrunscripts|cfide|cfformgateway|cffileservlet|lucee)" />
					</conditions>
					<action type="Rewrite" url="public/index.cfm/{R:1}" appendQueryString="true" />
				</rule>
			</rules>
		</rewrite>
	</system.webServer>
</configuration>

Yes on instance of Adobe Coldfusion, with complete wheels instances running in subfolders. Nothing shared really.

Wheels 4 mostly seems to know where it is with the URL rewriting tweaks, but Coldfusion might not completely understand it inside /tests. I'm honestly not sure know if the issues I'm seeing our because i'm in a sub folder or it's just a possible bug. I'm setting up our 3rd wheels application and it seemed to go a little better. I need to write more tests though to get a better sense for it.

It looks like this is still using Testbox under the hood? I see that in wheelstest/system/testbox.cfc. It's only on version 6.5 though? Assuming it might upgrade to 7 at some point. The streaming results will be nice.

I'm reading the test docs, but still somewhat confusing. Maybe a new version of https://github.com/wheels-dev/cfwheels-example-app, but for wheels 4 with some tests, etc. would be great. Just suggestions. Thanks.

[bpamiri]

Rest assured, it's just AI assisted. I review everything before he sends it out. ;-)

Really trying to nail down the write approach. We can do it but what I may have in mind may be different than what you need.

[bpamiri]

Thanks @mikegrogan. Let me look through what you have provided. I also have an old archived repo called wheels-big-rig which is an old attempt to get multiple wheels apps working in sub directories. To address your TestBox question, the built in WheelsTest is based on TestBox as you noticed and is vendor in so we can tweak it to work with Wheels better. Wheels 4.0 brings in Hotwire support which has streams support so adding streams to WheelsTest looking at the Rails model or TestBox model should be fairly easy.

[mikegrogan]

Thanks @bpamiri! When I said streaming results I was mostly talking about https://testbox.ortusbooks.com/readme/release-history/whats-new-with-7.0.0#real-time-streaming-test-tree.

Regarding sub folders if you have more questions I can try to help. Basically it's just having the wwwroot one level above the wheels folders.

Here's my stripped down server.json that sits in wwwroot and powers all the "subfolder" wheels instances. That's where I run server start in commandbox in our local environment. When it's on the server it's simpler.

root server.json

{
    "name":"Local Environment",
    "cfconfigfile":"../config/coldfusion/cfconfig.json",
    "app":{
        "cfengine":"adobe@2023",
        "libDirs":"../config/jars"
    },
    "web":{
        "host":"test.local",
        "webroot":"./",
        "http":{
            "port":"80"
        },
        "bindings":{
            "HTTP":{
                "listen":"0.0.0.0:80",
                "host":"test.local"
            },
            "SSL":{
                "listen":"0.0.0.0:443",
                "HTTP2Enable":true,
                "certFile":"../config/ssl/test.local.crt",
                "keyFile":"../config/ssl/test.local.key",
                "host":"test.local"
            }
        },       
        "rewrites":{
            "enable":true,
            "logEnable":false
        },
        "rulesFile":"../config/urlrewriting/rules.txt",
        "http2":{
            "enable":"true"
        }
    },
    "scripts":{
        "onServerInitialInstall":"cfpm install chart,caching,debugger,document,feed,ftp,htmltopdf,image,mail,oracle,pdf,print,scheduler,spreadsheet,zip"
    },
    "jvm":{
        "minHeapSize":"1024",
        "heapSize":"4096",
        "javaVersion":"openjdk17",
        "args":[
            "-Dcoldfusion.compiler.block.bytecode=false",
            "-Dcom.sun.management.jmxremote",
            "-Xlog:gc*:file=../config/logs/gc.log",
            "-XX:+HeapDumpOnOutOfMemoryError",
            "-XX:HeapDumpPath=./heapdump.hprof"
        ]
    },
    "runwar":{
        "options":{
            "ssl":{
                "eccdisable":false
            }
        }
    }
}

[bpamiri]

@mikegrogan — closing the loop on this with concrete news: the first-class knob shipped, and the test-runner work you identified is now formally tracked.

What's on develop now (PR #2985, merged 2026-06-11)

You asked whether we'd go "recipe" or "mode" — we went mode. There is now a subpath setting:

// config/settings.cfm (not the per-environment file — the mount point is the same everywhere)
set(subpath="/wheelsproject1");

or equivalently, from the environment (handy in your CommandBox server.json envVars or an IIS web.config environmentVariables block):

WHEELS_SUBPATH=/wheelsproject1

This drives the same derivation your config/settings.cfm tweak was doing by hand — webPath becomes /wheelsproject1/ (no /public/, matching your rewrite rules), and rootPath / rootcomponentPath / wheelsComponentPath stay synchronized automatically. Detection priority is set(subpath=...) → WHEELS_SUBPATH → the existing cgi.script_name derivation, so root-mounted apps are untouched and you can delete your hack entirely — nothing left for box install to clobber. Link, form, redirect, and asset helpers all pick the prefix up. It's documented in the production-config guide, and your rules.txt / web.config from this thread keep working unchanged on top of it.

What's now tracked (the part you called out as the real problem)

• test runner: web runner mutates live application.wheels — replace global swap with request-scoped overlay #3025 — web test runner application-scope isolation. Your "the application scope hacks break the main application, reload=true fixes it, they fight each other" diagnosis was exactly right: the runner backs up application.wheels and mutates the live struct in place, with a recovery hook that exists only because the swap can be left half-applied. The fix is a request-scoped overlay so test requests see test config while concurrent requests keep seeing live config — nothing global to restore. Your public/Application.cfc getBaseTemplatePath() anchor finding is folded into that issue too.
• cli: wheels test ignores the subpath setting — add base-path support for subfolder deployments #3026 — wheels test CLI under a subfolder. The CLI still hardcodes /wheels/app/tests with no prefix. Plan: --base-path=/wheelsproject1 plus auto-derivation from WHEELS_SUBPATH / set(subpath=...) when the flag is absent. This one is small now that the setting exists.

So the honest status for your six-instance setup: the day-to-day runtime story is now first-class on develop with zero core patches, and the tests story — web runner and CLI — is the named, scoped remainder. If you get a chance to point one of your dev instances at develop with set(subpath=...) in place of your hack, a confirmation (or a counterexample) on the runtime half would be genuinely useful input on both open issues.

[mikegrogan]

Amazing. Can't wait to try it!