A new coldbox app with commandbox: A walk in the park?

I want to share some recent experience with you, when I created a new coldbox app. Disclaimer: Actually I would like to improve the first impression when generating a new coldbox app, but I may sound a bit biased. As some of you might know I am not always happy with commandbox, especially with the way it handles lucee in production environments.
We had some issues recently with pinning lucee versions so we didn’t get unwanted updates, and the way it handles updates combined with some licensing issues. Our cases were probably very specific, but one of my major points with commandbox/lucee setups is that our sysadmins need additional training, because the setup is very non-standard. For a sysadmin who has to master multiple environments the locations of configuration files and log files is very non-standard, and release notes are not easy to find in the documentation. If you are well known in the commandbox and lucee environments it is not too hard to master, but for these sysadmins it is just one of the many tricks they have to master. They love uniformity, especially at 2 am with some failing websites after an update.

But let me stop. I think commandbox is a wonderful tool for development. Plenty ways to automate things, and starting multiple Lucee and ACF versions simultaneously is so easy that I wonder why there are still people around who are not using commandbox in their development environment. We just have to realize developers are not sysadmins and docker setups are quite different from traditional lucee installs.

But as said, for cfml development commandbox is wonderful. Still there is room for improvement, so let me share a recent story with my experiences for you. It helps if you can imagine you are new to coldbox, commandbox and lucee, like one of my coworkers with 20+ years of PHP development. I even taught him CFML 20 years ago, but he didn’t use it for a while..

Most of the time, we are working on some long term projects, but recently I had to setup something new, just some proof of concept. So I created a project, ran some of these box coldbox create app wizards and became the proud owner of a brandnew cfml advancedscript template setup. I started my Lucee server with a simpel box start command and I was ready to roll. At least that was what I thought. I started my lucee administrator just to realize I didn’t have a password for lucee yet. I tried to find it in the commandbox manual and this is what I found:

ColdFusion Admin settings

While Lucee asks for a password the first time running the admin, ColdFusion requires a username and password when CommandBox sets it up. The default username and password for the Adobe ColdFusion servers used are:

Username: admin

Password: commandbox

Well, I don’t know about Adobe Coldfusion, but for Lucee it is incorrect nowadays. But googling on lucee set password gave me a very simple blog post thanks to Pete Freitag, but hey , so easy to find and so useful. Just install commandbox-cfconfig and set your admin password.

install commandbox-cfconfig
cfconfig set adminPassword=Password123!

Don’t forget to restart and now you are ready. (my newcomer asks me now what is this cfconfig stuff). Ok, now I can configure my long wanted datasources and I am again ready for the real work. I quit my work, and restart commandbox and lucee sometime later to continue.

Although I am 200% sure my datasources were correct for some reason my app fails when I try to connect to a datasource. I have 14 years of coldbox experience, so I really know there’s nothing wrong with my code. So I opened my Lucee admin, and my datasources where ALL GONE. So I had to do it again.

But on restart my config would be zapped again. I already remembered, I wasted an hour on this some time ago. When I applied my advancedscript template a .cfconfig.json file was added. (My coworker is asking what this file does, he can not find it in the manual. There is some example, but it doesn’t tell him what .cfconfig.json does). I tell hem there is also some cfconfig manual and after some searching we find this reference buried somewhere in the cfconfig docs, which tells me every setting in my lucee server is replaced by values in a .cfconfig file. So we investigate what’s there, and see some weird names like {DB_DATABASE} (My coworker asks me what these variables mean, and I tell him this are environmental variables) He should use the dotenv module, but he can’t find a trace of it in both the commandbox or the cfconfig manual. Finally we install dotenv and we see a .env.example file. We fill in the correct values and finally we have a working datasource setup. We are smart enough to create some more environmental variables so we can create multiple datasources. ( My coworker is quite smart and tries to find out where all these environmental variables are used. He suggest we don’t need DB_CONNECTIONSTRING because it is not used in the code)

So we comment out this connection_string but surprise again: lucee will not start, it fails with this error:

The [.env] file is missing keys from the .env.example. You can populate your .env with the new settings using `dotenv populate --new`

Missing keys: [ DB_CONNECTIONSTRING ]

We decide to include the connectionstring again and our server starts again. But we are reading the error message. Our server doesn’t want to start because an EXAMPLE FILE has some more settings? So we decide to include a very useful DUMMY_SETTING=xyz in our .env.example file, and yes indeed.

 × | Starting Server
   |------------------------------
ERROR (5.3.0+00349)

The [.env] file is missing keys from the .env.example. You can populate your .env with the new settings using `dotenv populate --new`

Missing keys: [ DUMMY_SETTING ]

So my server does not want to start, because I included something extra in an .example file? ( my co-worker is asking me since when a sample file is part of the configuration of a server. He has 25 years of sysadmin experience ) I am just afraid my sysadmins will touch these sample files, because they assume that should be harmless.

Ok, I have to admit, I am exaggerating a bit. But my coworker and I have tons of dev and sysadmin experience. We could solve all issues, but it took some time. I am just wondering how starters could start a new project without any guidance. My point: commandbox is very much tailored to a deployment process with lots of automation for environmental variables, configuration settings and a docker way of doing things. This is nice, but you have to know what you are doing. Many of these handy features are known for the Ortus team, sometimes explained in workshops, but you can’t assume newcomers will understand, especially if they are poorly documented or not documented at all. I started with commandbox years ago, when it was new, and didn’t have al these so-called handy features. If you don’t start new projects everyday, you might miss some of them, especially if they are not documented in some manual.

So let me be clear. I don’t want to start flame wars, and I love all the help I get from Ortus people in the slack channels. But please, take into account some of the tools (like cfconfig and dotEnv) are not well known the every developer who wants to try commandbox. So maybe we could use a Getting Started Guide which is a bit better than the current funny Ikea-style nonsense?

And yes, I promise. I will not write anything bad about commandbox for a while 🙂