BoxLang with CommandBox

BoxLang is the AI-native software productivity platform for building, modernizing and running applications, with developers and AI agents working together.

Overview

CommandBox is the enterprise Java servlet deployment option for BoxLang. Unlike the MiniServer (Undertow, no-servlet), CommandBox runs BoxLang inside a full Java EE servlet container (Undertow with servlet API), enabling enterprise features like multi-site hosting, SSL management, OS service integration, and JDK management.

Installation

Install CommandBox

# macOS
brew install commandbox

# Linux (Debian/Ubuntu)
curl -fsSl https://downloads.ortussolutions.com/KEYS | sudo apt-key add -
sudo apt-get install commandbox

# All platforms
curl -fsSl https://downloads.ortussolutions.com/commandbox-cli-install | bash

Install the BoxLang Module (CommandBox < 6.1)

install commandbox-boxlang

On CommandBox 6.1+, BoxLang support is built-in — no module installation required.

Starting a BoxLang Server

# One-liner
server start cfengine=boxlang javaVersion=openjdk21_jdk

# With explicit port and webroot
server start cfengine=boxlang port=8080 webroot=/var/www/myapp

# Foreground (don't open browser)
server start cfengine=boxlang openBrowser=false

server.json Configuration

Place server.json in your project root for repeatable server configuration:

Minimal

{
    "name": "MyBoxLangApp",
    "app": {
        "cfengine": "boxlang",
        "serverHomeDirectory": ".engine/boxlang"
    },
    "openBrowser": false
}

With Rewrites + Modules + SSL

{
    "name": "MyBoxLangApp",
    "app": {
        "cfengine": "boxlang",
        "serverHomeDirectory": ".engine/boxlang"
    },
    "openBrowser": false,
    "web": {
        "rewrites": {
            "enable": true
        },
        "ssl": {
            "enable": true,
            "port": 443,
            "certFile": "/path/to/cert.pem",
            "keyFile": "/path/to/key.pem"
        }
    },
    "JVM": {
        "heapSize": "512m",
        "args": "-XX:+UseG1GC"
    },
    "env": {
        "BOXLANG_ENVIRONMENT": "production",
        "BOXLANG_DEBUG": false
    },
    "scripts": {
        "onServerInitialInstall": "install bx-mail,bx-mysql,bx-redis",
        "onServerStart": "echo 'Server starting...'",
        "onServerStop": "echo 'Server stopping...'"
    }
}

With Custom boxlang.json

{
    "app": {
        "cfengine": "boxlang",
        "serverHomeDirectory": ".engine/boxlang",
        "engineConfigFile": ".boxlang.json"
    },
    "web": {
        "rewrites": { "enable": true }
    },
    "scripts": {
        "onServerInitialInstall": "install bx-mail,bx-mysql,bx-compat-cfml"
    }
}

Installing BoxLang Modules

Modules are installed from CommandBox and are available after onServerInitialInstall runs:

# Install in running server
install bx-mysql
install bx-mail
install bx-redis
install bx-elasticsearch
install bx-compat-cfml

# Multiple at once
install bx-mysql,bx-mail,bx-redis

Or in server.json:

"scripts": {
    "onServerInitialInstall": "install bx-mysql,bx-mail,bx-redis"
}

Debug Mode

Enable debug mode via any of these methods:

# CLI flag
server start --debug

# server.json env variable
{
    "env": { "BOXLANG_DEBUG": true }
}

Or via .cfconfig.json:

{
    "debuggingEnabled": true
}

Docker with CommandBox

# Pull the official image
docker pull ortussolutions/commandbox

# Run BoxLang on CommandBox
docker run -p 8080:8080 \
    -e cfengine=boxlang \
    -v /path/to/myapp:/app \
    ortussolutions/commandbox

Dockerfile

FROM ortussolutions/commandbox:latest

ENV cfengine=boxlang
ENV PORT=8080

COPY ./ /app
WORKDIR /app

EXPOSE 8080
CMD ["box", "server", "start", "--console"]

BoxLang+/++ Subscriptions (CommandBox PRO Features)

A BoxLang+ or BoxLang++ subscription unlocks CommandBox PRO enterprise features:

Activate via CommandBox:

server activate --subscription=YOUR_KEY

Environment Variables

The servlet/CommandBox runtime honors the same environment variables as the core OS runtime:

Server Management Commands

server start         # Start the server
server stop          # Stop the server
server restart       # Restart the server
server status        # View server status
server log           # Tail the server log
server open          # Open in browser
server list          # List all servers
server forget        # Remove server config

Checklist

• [ ] Use server.json for repeatable, version-controlled server config
• [ ] Set serverHomeDirectory to keep engine files out of source tree
• [ ] Use scripts.onServerInitialInstall to auto-install required modules
• [ ] Provide a custom engineConfigFile (.boxlang.json) for project-level BoxLang config
• [ ] Use JVM.heapSize to set appropriate memory limits for production
• [ ] Enable web.rewrites.enable: true for front-controller or SPA routing
• [ ] Prefer env vars in server.json over hard-coded values for environment-specific settings
• [ ] For Docker, use ortussolutions/commandbox with cfengine=boxlang env var