Why Kalabox V2 Matters to Project Owners

Project Owners?

By project owners, I am referring to individuals such as consultants, team leads, and technology directors. If you make the decision on what goes into the repo, you can spend a little time setting up a Kalabox profile, and your developers have the option to run your application stack as it is intended, with minimal effort, on their OS of choice.

Kalabox V2

The value of Kalabox is often discussed in the context of a local development tool, and for good reason. V2 however brings this and much more to the table by allowing your stack to be defined, configured, and maintained within a project's code repository. This is extremely powerful to the project owner and I wanted to take some time write about these points.

For the unfamiliar, Kalabox V2 provides a standard for defining your application stack and a tool to run one or more apps, each on their respective stack, on Windows, Mac, and Linux.

Kalabox V1 provided a local development by creating a VM with a single stack for running PHP/MySQL based applications. Files were editable over a shared volume and all applications were served from the same web server within the VM.

Kalabox V2 is an entirely different animal, allowing for precise server builds and service configurations to be defined by leveraging the use of Docker.

You as a tech lead could setup a Kalabox profile for your application which depends on nginx, php w/mcrypt enabled, mariadb, redis, varnish, and solr. This might take a little effort, but once that profile is in the project, a Jr. developer or perhaps a themer could have the application up and running with a few commands.

If you have other developers who prefer to set that all up manually or with a different toolset, no problem. They don't have to run the app via Kalabox and its configurations will not interfere with other tools.

Kalabox Profile

I'll be referring to the "Kalabox profile" a lot, so here's a short description.

A Kalabox profile is a directory named .kalabox, generally at the root of your repository, which contains configurations, plugins, and other dependencies required for Kalabox to initialize and run your app.

Early Integration and Usage Considerations

Much consideration was given to the Kalabox architecture early on which revolved around it being entirely unobtrusive to code repositories, as well as to a developer's local file system.

In other words, for Kalabox to be adoptable, application profiles needed to be able to be dropped into any project. An example of this in the context of a Drupal codebase is that the Kalabox profile could exist in a repository where the base directory is the web directory, or a repository where the web directory is a subdirectory, such as "public".

Early integration goals included:

  • Kalabox could not dictate the directory structure of a project.
  • Kalabox configurations would be the least intrusive to a code repository as possible.
  • Kalabox would support using Docker images from Dockerhub as well as custom Docker files defined in core, or in the project itself.
  • Apps would be able to be manageable by the command line, even after the GUI is developed.
  • A VM would not be required if running Kalabox on Linux.

Docker Images & Dockerfiles

Docker, among other technologies, is the powerhouse under the hood of Kalabox V2. With Docker, we can build many very custom servers configurations to run specific services, without allocating large amounts of unused resources for each instance as you would need if you ran multiple VMs.

Kalabox provides a VM to run Docker on Windows and Mac, but it uses Docker to run your application services.

Docker images represent a server which is to run a service in your application stack. Your Kalabox profile defines the images in your stack and creates containers based on them. (If you're unfamiliar, think of a container as an instance of an image)

Images can be pulled from Docker Hub or build from custom Dockerfiles defined in your Kalabox profile.

For many cases, pulling an image from Docker Hub may work fine, but there are certainly cases where you may want to maintain your own set of Dockerfiles:

  • You prefer defining your own Dockerfiles so you know exactly what is in them.
  • You would like to maintain a revision history of your Docker images via Dockerfiles.
  • You do not control the Docker Hub image and do not want to risk changes to it breaking your app.
  • You want to maintain the security of your Docker image builds yourself. (maybe not that big of a concern for local development)

Kalabox provides default images out of the box, but if you would like to learn more about defining your own, check out the Dockerfile documentation.

Kalabox Plugins

Kalabox plugins allow developers to write custom CLI commands and hook into the event system by listening for or triggering events for other plugins.

Plugins can referenced to externally maintained projects, or the plugin source can exist in the Kalabox profile itself. External referencing is accomplished by implementing plugins as nodejs modules and utilizing the npm ecosystem. Kalabox internals will handle fetching the plugins when externals are defined.

This allows you to maintain plugins shared throughout multiple projects within their own repository. Reference external plugins or maintain custom plugins along side the rest of your codebase within your Kalabox profile directory, the choice is yours!

... and yeah, since plugins are nodejs modules themselves, you have the power of nodejs core and npm modules available, as you would when writing any nodejs app.


There were many challenges that have been overcome or worked around, but are still many in place. I'm referring to things like requiring a VM to run on Win/Mac, and more challenges that come with that like file access between the host system and the guest. There's a file sync solution that Kalabox takes care of internally, but it would be great if the work-around wasn't required like when you run Docker on Linux. Docker with all it's adoption and support is a juggernaut though, and Kalabox will only benefit with each integration improvement in the future.

Deployments? (Future Speculation)

I'm not sure if this is even on the roadmap, but the Kalabox architecture certainly has a foundation that could be developed into more than just a local development tool. I imagine it would be a pretty handy tool that could eventually manage apps on a Docker host in a production environment. This is speculation, and perhaps a little hopefulness though.

My Role in the Kalabox V2 Project

I haven't worked on Kalabox V2 in a while, but I thought it would be important to articulate what this project means to me as a developer and project owner. I was heavily involved in early V2 R&D and much of the core architecture, (so you might say this article comes with some bias) but my startup began to demand more time than I could effectively provide to the project.

I appreciate the tremendous undertaking Mike Pirog and the rest of the guys at Kalamuna have taken to push Kalabox to this next level, as well as the generous contributions by Pantheon and every single Backer who supports the vision.