Running Lucee on Kubernetes

Lucee is an open-source CFML application server/engine that is compatible with Adobe Coldfusion. The easiest way to run your Lucee application is to use CommandBox by Ortus Solutions. With CommandBox you can spin-up any Lucee version that you want and configure the settings using a JSON file.

More and more companies move their applications to use Docker. This has enormous benefits compared to virtual and physical servers. For instance a better use of host resources and an ability to add the stack configuration to the application deployment. No more pre-configuring servers to host your application. You put everything in the docker image and do all the environment-specific settings with environment variables and/or secrets.

When using CommandBox for your application, upgrading to the CommandBox Docker project is a logical step. Please have a look at the CommandBox GitHub documentation for more info.

 How can I deploy a CommandBox docker image? That is where Kubernetes comes into play.

What is Kubernetes?

Kubernetes (sometimes referred to as K8S), is a system for automating deployment, scaling, and management of containerized applications. Originally developed by Google and currently one of the most popular open-source projects.

Kubernetes helps you combine and manage all items needed for your project into one namespace (group). Your application consists of the source code, application server, database server, ingress, TLS, etc.

In this blog post, we will explain how to deploy the default CommandBox Docker image to Kubernetes and be able to access it over the internet. All the commands mentioned are tested on Google Kubernetes Engine but should also work on other Kubernetes implementations. Take a look at Kubernetes tutorials for more information.


  • Kube Control (kubectl) application installed on your machine
  • Authentication for your Kubernetes cluster setup
  • Basic knowledge of the CLI
  • Knowledge of your Kubernetes cluster

Running your workloads in Kubernetes can be accomplished by two methods:

  1. Use the (limited) create deployment option of kubectl
  2. Use the powerful YAML definition file

The first method is the easiest and that has the focus in this blog. The YAML method requires more knowledge of Kubernetes and the running parts.

Create the deployment

A deployment in Kubernetes 

Detailed information about Kubernetes deployment can be found on the Kubernetes documentation website

Execute the following command to create the deployment:

kubectl create deployment commandbox-hello-app --image=ortussolutions/commandbox:lucee5-alpine-3.1.0 --replicas=1 --port=8080

You should see the following in the console:

deployment.apps/commandbox-hello-app created

If not, check whether you made a typo in the command and that kubectl is working correctly and has a connection with your Kubernetes cluster.

By default, the pods in this deployment are labeled with the name of the deployment. In our case, the label that is added to all pods is: app=commandbox-hello-app

Expose deployment to the internet

To expose your CommandBox deployment to the outside world, you need to create a Kubernetes service. In our example we will create a service on port 80 that connects to port 8080 of Commandbox:

Kubectl expose deployment commandbox-hello-app --name=commandbox-hello-app-service --type=LoadBalancer --port 80 --target-port 8080

You should see the following in the console:

service/commandbox-hello-app-service exposed

Because we have used the LoadBalancer type for the deployment, the IP address to use is dependent on the node in the Kubernetes cluster where the pod has been scheduled.

Find IP address to connect to (column EXTERNAL-IP):

kubectl get service -l app=commandbox-hello-app

Go to your browser and type:


If all went according to plan, then you should see the welcome page of CommandBox. The Lucee administrator should also be accessible on http://<EXTERNAL-IP>/lucee/admin/server.cfm

 To see more details about the pod in the deployment, run the following command:

kubectl get pods -l app=commandbox-hello-app -o wide

Advanced YAML

In the previous section, we have talked about the powerful YAML definition that can also be used to create Kubernetes items. To give you an idea of what this looks like, run the following command:

kubectl get deployments -l app=commandbox-hello-app -o yaml

This will output something similar to:

apiVersion: v1
- apiVersion: extensions/v1beta1
  kind: Deployment
    annotations: "1"
      app: commandbox-hello-app
    name: commandbox-hello-app
    namespace: default
    progressDeadlineSeconds: 600
    replicas: 1
    revisionHistoryLimit: 10
        app: commandbox-hello-app
        maxSurge: 25%
        maxUnavailable: 25%
      type: RollingUpdate
        creationTimestamp: null
          app: commandbox-hello-app
        - image: ortussolutions/commandbox:lucee5-alpine-3.1.0
          imagePullPolicy: IfNotPresent
          name: commandbox
          - containerPort: 8080
            protocol: TCP
          resources: {}
        dnsPolicy: ClusterFirst
        restartPolicy: Always
        schedulerName: default-scheduler
        securityContext: {}
        terminationGracePeriodSeconds: 30

If you would have put the output in a file called commandbox-hello-app.yaml you can run:

kubectl apply -f commandbox-hello-app.yaml

The end result would have been the same as running kubectl create deployment commandbox-hello-app but with this method, you can configure everything in the deployment. Adding labels, ports, other containers, etc.


To clean up after ourselves….

kubectl delete deployment,services -l app=commandbox-hello-app

You should see the following in the console:

deployment.extensions "commandbox-hello-app" deleted

service "commandbox-hello-app-service" deleted

Cleaning up is another advantage of using Kubernetes and docker. Creating and removing deployments is easy and clean.
Next steps

Now that you have got your default CommandBox deployment up-and-running, it’s time to think about what is needed for your applications. For starters, you will need a custom docker image based on the CommandBox docker image hosted on Docker Hub or a custom Docker registry. This custom docker image needs to contain the codebase of your application and the Lucee configuration that matches the needs of your application. But probably also a database server, persistent storage (PV in Kubernetes), ingress for the FQDN, TLS certificates, etc.

We hope this blog has helped you to get started with Kubernetes and will inspire you to bring all your applications to Kubernetes. 

Further reading

You might find these articles interesting too