How to get started with Wheels 3.0 without 'modern tooling'

[andoradmiraal]

After spending two entire days trying to run Wheels 3.0 for the first time, I finally figured out the secret souce. So to help others who might be in the same situation, this is my advise on how to install Wheels 3.0:

The hardest part is perhaps figuring out which files to download. I found you need to download 3 files:

• wheels-core
• wheels-base-template
• something called 'Wirebox'.

The first two you can download from the Wheels Github, the last one you can download from https://forgebox.io/view/wirebox (click Versions, then on the three dots behind the latest version, then Download).

1. Extract wheels-base-template to your deployment directory
2. In the directory vendor, which is created in step 1, extract wheels-core so that the directory wheels is directly in the root of vendors
3. In this same vendor directory, create a directory wirebox, and extract all files from the wirebox download here
4. Set your web root (in IIS, or whichever other webserver you're using) to the directory 'public' rather than the regular webroot
5. Now set URL rewriting - create a web.config (when using IIS) with the standard URL rewrite code.

You might need to reboot your website or even your server, but now the Wheels application should run the home page.

Hope this helps!

[bpamiri]

Are you using commandbox for your local environment? Just trying to figure out where the friction is?Can you provide more information on what you are doing and what the issues are.-Peter Amiri Sent from my iPhone (auto-typing mispell disclaimer in effect)On Jan 17, 2026, at 8:30 AM, andoradmiraal ***@***.***> wrote: After building Wheels 2.5 apps for years, I'm hopelessly frustrated that I haven't been able to deploy a first Wheels 3.0 testing application, even after two solid working days trying. Undoubtedly it's me being dumb, but I do hope there will soon be some information on how to (manually) deploy Wheels 3.0 applications. I see a lot that looks really promising, I just wish it wasn't so damn hard to get started. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[andoradmiraal]

Hi Peter,

Thanks for getting back—much appreciated, as is all your work on Wheels 3.

Our use case: Lean IIS/Lucee integration via our own app installers/Git repos. No "modern tooling", dependency injection, etc. We like to keep everything very deliberate and controlled in our repos.

Main friction (coming from pre-3.0 archive downloads):

• No step-by-step docs for minimal setup from repos (core, CLI, base templates, etc.)—which combos for bloat-free? Everything in documentation assumes a certain workflow which we just don't have. Finding the files required for deployment (e.g., skip TestBox, keep WireBox - but where to download and how to install?) requires plenty research/trial/error as not documented.
• Yes, did run installer and CommandBox to add additional webservers/Java/CF engines in order to download the set of Wheels files we hoped to eventually get running on IIS. The whole approach seems quite intrusive and impractical. "Export" didn't work for production, but also wouldn't fit our workflow to begin with, so couldn't find any added value of using CommandBox. Also, feels like loss of control when CommandBox just does stuff and we don't really understand what. Hard to then integrate in our own install scripts.
• Simply using 'core' sounded perfect for our workflow, but Core needs a lot of of manual file generation in order to run a clean, blank copy of wheels that could server as our starting point. Didn't find any guidance on which files we need and how to deploy. Spend a lot of time with AIs trying to figure it out, couldn't get it done. Eventually tried the below combination which hit the jackpot.

What worked: Layering base templates + core + WireBox ≈ Wheels 2.5 experience. A release note pointing to this option would save 2.5→3.0 upgraders grief. Hard to figure out by trial and error that this is what's required to run clean copy of Wheels.

Hope these notes help others. Even basic repo explanations on the GitHub download page would go far.

Wheels 3 now runs great on our production server—excited to upgrade apps! 🎉

[bpamiri]

I understand now. We probably lean too much into simplification and leaned into command box approach. It should be simple enough to download the wheels-base-template-3.0.0+XX.zip and the wheels-core-3.0.0+XX.zip from https://github.com/wheels-dev/wheels/releases  Wheels core is the old Wheels directory from the pre 3.0 day. Just expand it and drop it into the vendor folder. You’ll also need to download wirebox and testbox and drop them into the vendor folder as well.I’ll have to look at what else the install scripts do about variable replacement. Perhaps moving these to an initial setup phase might be better.Thanks for the feedback. It’s good to learn out people are using the framework. While building 3.0 we probably moved more toward new users’ experience with the framework and may have made it more difficult for existing users with existing workflows.-Peter Amiri Sent from my iPhone (auto-typing mispell disclaimer in effect)On Jan 19, 2026, at 6:53 AM, andoradmiraal ***@***.***> wrote: Hi Peter, Thanks for getting back—much appreciated, as is all your work on Wheels 3. Our use case: Lean IIS/Lucee integration via our own app installers/Git repos. Main friction (coming from pre-3.0 archive downloads): No step-by-step docs for minimal setup from repos (core, CLI, base templates, etc.)—which combos for bloat-free? Yes, did run installer and CommandBox to add additional webservers/Java/CF engines, though it feels intrusive for our workflow; extracting deployable files (e.g., skip TestBox, keep WireBox) requires trial/error and eventually poses the same problem as downloading repos directly: how to deploy? "Export" didn't work for production, but also wouldn't fit our workflow to begin with. Core needs a lot of of manual file generation, for which I didn't find any guidance. What worked: Layering base templates + core + WireBox ≈ Wheels 2.5 experience. A release note on this would save 2.5→3.0 upgraders grief. Hope these notes help others. Even basic repo explanations on the GitHub download page would go far. Wheels 3 now runs great on our production server—excited to upgrade apps! 🎉 —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: ***@***.***>

[andoradmiraal]

Yes, exactly—that's the approach I found worked nicely for us. Simply documenting this on the releases page in one or a few lines, or addding it as an option to the Downloads page, would help the likes of me a lot. I think there must be more people coming from 2.5 who are unfamiliar with (or adverse to) modern tooling; this would help to keep them on board. There really isn't any reason why we wouldn't use Wheels, CommandBox isn't actually required even if Wirebox (and Testbox?) now are. If you go through the normal download procedure, it feels like Wheels 3 no longer fits a deliberate workflow, when in reality, it works just fine.

[andoradmiraal]

To complete my little guide for people doing an install without ColdBox/CommandBox/WhateverBox...

We didn't run into any issues yet without 'Testbox' installed with Wheels, but officially it's required for Wheels. Finding the download link is quite tricky, so here it is:

1. Go to https://forgebox.io/view/testbox
2. Click on Versions
3. Click the three dots behind the version you wish to us, and select Download.

Hope this helps!😊

[zainforbjs]

@andoradmiraal If you want to install Wheels manually without using CommandBox or the CLI, here’s a clear breakdown of what’s required and how to get it running.

Core pieces you need:

1. wheels-core – the framework itself (routing, ORM, request lifecycle, etc.)
2. wheels-base-template – provides the standard app structure (controllers, models, views, config, events, etc.)
3. WireBox – required for dependency injection and object lifecycle management
4. TestBox – optional if you’re only running the app, but strongly recommended if you want to run or write tests

Step-by-step setup

Create your application directory

• Download the latest stable version of the required packages from forgebox: Wheels-base-template, Wheels-core, Wirebox, Testbox(optional).
• First extract the wheels-base-template in your application directory. It will look something like this:

/my-wheels-app
  /app
  /config
  /db
  /public
  /vendor
  /tests

• Extract wheels-core, wirebox and testbox inside the vendor folder and you are good to go.
• You might need to rename the extracted folder. So, rename the extracted wirebox folder to wirebox, the extracted testbox folder to testbox and the extracted wheels folder to wheels.
• After doing this, your vendor folder will look something like this:

/vendor
  /wheels
  /wirebox
  /testbox

The main entry point for a wheels 3.0 application is "/public/index.cfm". So you must configure that in IIS as the entry point to make sure that the wheels application works correctly.

[andoradmiraal]

Thanks, that's a lovely clear overview 👍 I did figure it out eventually, but adding this info to the download page (vs. assuming CommandBox) would help a lot. Or perhaps replace the part of the docs that literally states "manual install is too obvious to explain" with the above info, that would help us non-CommandBox folk keep our sanity :)

While I'm a tad bit saddened by the new non-optional depencies (especially WireBox, which feels like added weight to us not allowing dependency injection), I'm quite excited to try out Testbox, which seems very useful. And since I've ended up listing my personal pain points here: the name change makes searching harder: "CFWheels" was extremely specific and gave 100% relevant results in Google, the generic "Wheels" does, well, the opposite.

Now after sharing the negatives of my upgrade experience, hopefully constructively, let me note that once we had the files, upgrading 2.5 to 3.0 was remarkably smooth, more so than with previous upgrades, major win 🎉

[zainforbjs]

@andoradmiraal Thanks for valuable feedback, and the downloads page has been updated with required information. Hope you enjoying your upgrades with wheels 3.0, Let us know if you find any difficulty further. Thank you

[marshmob]

have you seen a similar set of instructions for getting the sample app installed. I have tried various combinations of downloads without much luck. I am trying to get it working on a cf2025 / iis installation but was having troubles with relative vs absolute resolution of modules. could get around this and another problem arose. I couldnt decide if installation error or an error in the sample app.

[marshmob]

Installed from wheels/example and all is now working

Thanks for your persistence and all the help.

It can get pretty frustrating doing something like a sample app and having a problem getting it going.

Now the fun can begin!!

[zainforbjs]

My bad. I didn't mention clearly in my first message. You have to use the stable version which is 1.0.0.

[zainforbjs]

Great that you got it working. If you have any more queries let me know.

[marshmob]

Oops I missed the tick and cross on the stable field. I just saw 3.0.0-rc-1 which looked like the same release level as the core. New glasses time.

[zainforbjs]

All good — easy detail to miss. Thanks for clarifying.

[michaeldiederich]

First of all, @andoradmiraal, let me kiss your eyes. I was I afraid, i was just too stupid to get this running (and I am still not sure, if I am).
I downloaded the same files. extracted like you said and I needed a "coldbox" directory, which I also downloaded. My vendor folder looks like:

➜  foobar ls vendor
Controller.cfc                      Public.cfc                          controllers                         public
Dispatch.cfc                        README.md                           databaseAdapters                    testbox
Global.cfc                          Test.cfc                            docs                                tests
Job.cfc                             Testbox.cfc                         events                              tests_testbox
Mapper.cfc                          Wirebox.cfc                         helpers                             vendor
Migrator.cfc                        box.json                            mapper                              view
Model.cfc                           coldbox                             migrator                            wheels-core-3.0.0+42-20260203131222
Plugins.cfc                         controller                          model                               wirebox

I changed the root folder to /public and now I get this error:

Message	invalid component definition, can't find component [wheels.Wirebox]

Stacktrace	The Error Occurred in
/home/foobar/vendor/wirebox/system/ioc/Injector.cfc: line 1708
1706:       // Check if just a plain CFC path and build it
1707:       if ( isSimpleValue( arguments.binder ) ) {
1708:          arguments.binder = createObject( "component", arguments.binder );
1709:       }
1710:

called from /home/foobar/vendor/wirebox/system/ioc/Injector.cfc: line 357
called from /home/foobar/vendor/wirebox/system/ioc/Injector.cfc: line 257
called from /home/foobar/public/Application.cfc: line 268

The documentation about the manual installation says nothing about all this stuff, the example application doesn't have this stuff.
So, what is missing? What did I wrong? Is there a "one zip fits all" to start?

Just in case, here are the other folders:

➜  foobar ls vendor/coldbox 
CONTRIBUTING.md             box.json                    license.txt                 server-adobe@2025.json      server-boxlang@1.json       system
ModuleConfig.bx             build                       readme.md                   server-boxlang-cfml@1.json  server-lucee@5.json         test-harness
apidocs                     changelog.md                server-adobe@2023.json      server-boxlang-cfml@be.json server-lucee@6.json         tests
➜  foobar ls vendor/wirebox
box.json         license.txt      readme.md        system           wirebox-8.0.5+33
➜  foobar ls vendor/testbox
CONTRIBUTING.md            cfml                       run                        server-boxlang-cfml@1.json system
box.json                   changelog.md               run.bat                    server-boxlang@1.json      test-visualizer
build                      license.txt                server-adobe@2021.json     server-lucee@5.json        tests
bx                         readme.md                  server-adobe@2023.json     server-lucee@6.json

[zainforbjs]

@michaeldiederich You don't need a coldbox folder to get wheels to work. It looks like the wheels folder got extracted directly inside vendor folder instead of being in "vendor/wheels". As I said above, you just need to follow these steps:

Core pieces you need:

1. wheels-core – the framework itself (routing, ORM, request lifecycle, etc.)
2. wheels-base-template – provides the standard app structure (controllers, models, views, config, events, etc.)
3. WireBox – required for dependency injection and object lifecycle management
4. TestBox – optional if you’re only running the app, but strongly recommended if you want to run or write tests

Step-by-step setup

Create your application directory

• Download the latest stable version of the required packages from forgebox: Wheels-base-template, Wheels-core, Wirebox, Testbox(optional).
• First extract the wheels-base-template in your application directory. It will look something like this:

/my-wheels-app
  /app
  /config
  /db
  /public
  /vendor
  /tests

• Extract wheels-core, wirebox and testbox inside the vendor folder and you are good to go.
• You might need to rename the extracted folders. So, rename the extracted wirebox-* folder to "wirebox", the extracted testbox-* folder to "testbox" and the extracted wheels-* folder to "wheels".
• After doing this, your vendor folder will look something like this:

/vendor
  /wheels
  /wirebox
  /testbox

The main entry point for a wheels 3.0 application is "/public/index.cfm". So you must configure that in IIS as the entry point to make sure that the wheels application works correctly.

[michaeldiederich]

Thanks, you are right, it now works. Except the tests:

Message	could not find component or class with name [testbox.system.modules.globber.models.PathPatternMatcher]

Stacktrace	The Error Occurred in
/home/foobar/vendor/testbox/system/TestBox.cfc: line 848
846:    private function getSpecPaths( required directory ){
847:       var results            = [];
848:       var pathPatternMatcher = new testbox.system.modules.globber.models.PathPatternMatcher();
849:
850:       // recurse default

called from /home/foobar/vendor/testbox/system/TestBox.cfc: line 280
called from /home/foobar/vendor/testbox/system/TestBox.cfc: line 95
called from /home/foobar/tests/runner.cfm: line 103
called from /home/foobar/vendor/wheels/Public.cfc: line 45
called from /home/foobar/vendor/wheels/Dispatch.cfc: line 237
called from /home/foobar/public/index.cfm: line 5
called from /home/foobar/public/Application.cfc: line 229

➜  foobar ls vendor 
testbox wheels  wirebox

➜  foobar ls vendor/testbox 
CONTRIBUTING.md            cfml                       run                        server-boxlang-cfml@1.json system
box.json                   changelog.md               run.bat                    server-boxlang@1.json      test-visualizer
build                      license.txt                server-adobe@2021.json     server-lucee@5.json        tests
bx                         readme.md                  server-adobe@2023.json     server-lucee@6.json

➜  foobar ls vendor/testbox/system 
Application.cfc           CollectionExpectation.cfc TestBox.cfc               coverage                  runners
Assertion.cfc             Expectation.cfc           TestResult.cfc            mockutils                 stubs
BaseSpec.cfc              MockBox.cfc               compat                    reports                   util

There is no modules folder?

The only change so far was set(urlRewriting="Off");.

Thanks for your help!

[zainforbjs]

TestBox has its own dependencies that are automatically downloaded when you install it via CommandBox. Since you’re not using CommandBox, you’ll need to place these dependencies manually. There are four required modules:

• Globber
• cbMockData
• CBStreams
• cbproxies

Each module must be extracted into a folder with the exact same name as the module (for example, Globber must be extracted into a Globber directory).

After extracting all four modules:

1. Move cbproxies into cbstreams/modules/
2. Move Globber, cbMockData, and CBStreams into vendor/testbox/system/modules/

If the modules directory does not exist, create it. Once this structure is in place, TestBox should run correctly.

[michaeldiederich]

Thank you very much!

[bpamiri]

Hi guys, I just wanted to pipe in and apologize in a way. As I eluted to above we made some assumptions and leaned too much into the modern workflows and reliance on CommandBox, WireBox, and TestBox. I realize now that for those whose normal workflows don't include these tools, using Wheels 3.0 becomes increasingly difficult. Having to manually download multiple packages and manually put them into the right order just to get the framework operational was not what we set out to achieve. By adopting a CommandBox native implementation mechanism we were trying to simplify adoption and use of the framework but now see that we may have had the opposite effect for some veteran users.

I now have some work in flight for the next revision of the framework dubbed 3.1. This revision reorganizes the directory slightly in order to make it completely runnable from a simple GitHub download or clone. It will have zero dependencies as well so you will not have to scramble to download multiple packages just to get the framework running.

The latest round should start to show up in the snapshots and I'll blog about it in a day or so once the dust settles.

[blastiko]

Yeah, good times when i was download the zip, extract it and i was already to go.
Anybody of expert can give me how to cofigure Nginx web server to obtain a work environment?
Because I'm a developer, not system administrator.
Thank bpamiri, I hope that the framework return to be easy to set-up like in the past.

[bpamiri]

I’ve reworked the directory structure on the develop branch so a single download is all you need. No dependencies just point an app server to the /public folder. I hope to have the work finished up in the next few days and be able to update the docs so you can test. It started out as a 3.1 target, but it is starting to look more and more like a 4.0 target. Not in time, most of it is done, but in the scope of what is included. I’ve been a little sidetracked with a side project that is starting to blow up right now. It's an AI agent orchestrator, I know, not another one of those, but needed it for all the work I'm doing in my day job and accross multiple GitHub Orgs. Read about it here: ***@***.***_9391/welcome-to-the-grove-6537759563ee Welcome to the Grove medium.com

…

-Peter

On Mar 23, 2026, at 8:31 AM, blastiko ***@***.***> wrote: Yeah, good times when i was download the zip, extract it and i was alredy to go. Anybody of expert can give me how to cofigure Nginx web server to obtain a work environment? Because I'm a developer, non system administrator. Thank bpamiri, I hope that the framework return to be easy to set-up like in the past. — Reply to this email directly, view it on GitHub <#1838?email_source=notifications&email_token=AABMCS2OJO2VD7BP54YEEZT4SFKGTA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCNRSG43TSOBYUZZGKYLTN5XKOY3PNVWWK3TUUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#discussioncomment-16277988>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABMCSYNFKHRYFYWZ7WAMR34SFKGTAVCNFSM6AAAAACSAORCNWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTMMRXG44TQOA>. You are receiving this because you commented.