Boxlang Runtime Miniserver

BoxLang MiniServer

Overview

BoxLang MiniServer is the official lightweight web server for BoxLang applications. It is built on Undertow and is NOT a servlet container — it is a purpose-built, fast web runtime for BoxLang. Use it for development servers and production deployments where a full Java EE container is not needed.

Binary: boxlang-miniserver (Windows: boxlang-miniserver.bat) Default behavior: binds 0.0.0.0:8080, uses current working directory as webroot.

Quick Start

# Start in current directory on default port 8080
boxlang-miniserver

# Custom port and webroot
boxlang-miniserver --port 9000 --webroot ./public

# Enable URL rewrites (SPA or front-controller pattern)
boxlang-miniserver --rewrites

# Production with health checks
boxlang-miniserver --port 8080 --health-check --health-check-secure

CLI Flags

Environment Variables

Environment variables are scanned before CLI arguments; CLI args take precedence.

JSON Configuration (miniserver.json)

Create a miniserver.json file and pass it with --configPath (or use .boxlang.json project convention):

{
    "port": 8080,
    "host": "0.0.0.0",
    "webRoot": "./www",
    "debug": false,
    "configPath": "./.boxlang.json",
    "serverHome": "./.engine/boxlang",
    "rewrites": true,
    "rewriteFileName": "index.bxm",
    "healthCheck": true,
    "healthCheckSecure": true,
    "envFile": "./.env",
    "warmupURLs": ["/api/warmup", "/health/ready"],
    "undertow": {
        "ioThreads": 4,
        "workerThreads": 32,
        "bufferSize": 16384
    },
    "socket": {
        "tcpNoDelay": true,
        "reuseAddress": true
    },
    "websocket": {
        "maxFrameSize": 65536,
        "maxTextMessageSize": 65536
    }
}

Config Priority (high → low)

1. CLI arguments
2. JSON config file
3. Environment variables
4. Defaults

.boxlang.json Project Convention

Place a .boxlang.json in your webroot for project-level BoxLang configuration. It is automatically merged with the global boxlang.json at startup — commit it to source control for portable config.

{
    "modules": {
        "bx-mysql": { "enabled": true },
        "bx-mail":  { "enabled": true }
    },
    "debugMode": false,
    "timezone": "UTC"
}

Pair with a miniserver.json that points to it:

{
    "port": 8080,
    "webRoot": "./www",
    "configPath": "./.boxlang.json"
}

Example Configurations

Development

{
    "port": 8080,
    "webRoot": "./public",
    "debug": true,
    "rewrites": true
}

Production

{
    "port": 8080,
    "host": "0.0.0.0",
    "webRoot": "/var/www/myapp",
    "rewrites": true,
    "healthCheck": true,
    "healthCheckSecure": true,
    "warmupURLs": ["/api/warmup/database", "/health/ready"],
    "undertow": {
        "ioThreads": 8,
        "workerThreads": 64
    }
}

Full Options

{
    "port": 8080,
    "host": "0.0.0.0",
    "webRoot": "./www",
    "debug": false,
    "rewrites": true,
    "rewriteFileName": "index.bxm",
    "serverHome": "./.engine/boxlang",
    "configPath": "./.boxlang.json",
    "envFile": ".env",
    "healthCheck": true,
    "healthCheckSecure": true,
    "warmupURLs": ["/api/warmup"],
    "undertow": { "ioThreads": 4, "workerThreads": 32, "bufferSize": 16384 },
    "socket": { "tcpNoDelay": true, "reuseAddress": true },
    "websocket": { "maxFrameSize": 65536, "maxTextMessageSize": 65536 }
}

Health Check Endpoints

Enable with --health-check. With --health-check-secure, remote callers get minimal info only.

{
    "status": "UP",
    "timestamp": "2025-08-01T17:05:47Z",
    "uptime": "1m 47s",
    "uptimeMs": 107245,
    "version": "1.4.0",
    "javaVersion": "17.0.2",
    "memoryUsed": 152093696,
    "memoryMax": 4294967296
}

Environment Files (.env)

The MiniServer auto-loads .env from the webroot at startup. Variables are added to Java System Properties and accessible via getSystemSetting():

# .env
DATABASE_URL=jdbc:mysql://localhost:3306/mydb
API_KEY=secret
DEBUG_MODE=true

// Works in both local (.env) and production (real env var)
var apiKey = getSystemSetting( "API_KEY" )
var dbUrl  = getSystemSetting( "DATABASE_URL" )

Note: Use getSystemSetting() rather than server.system.environment — it works for both .env (system properties) and real environment variables.

Warmup URLs

Pre-request URLs on startup to warm caches and connections before serving traffic:

{
    "warmupURLs": [
        "/api/warmup/database",
        "/api/warmup/cache",
        "/health/ready"
    ]
}

Warmup runs sequentially after server init. Failures are logged but do not abort startup.

Security Features

• Hidden file protection — any file or directory starting with . returns 404 automatically and cannot be disabled
• .env files are blocked from HTTP access even when healthCheck is enabled
• Health check endpoints never expose environment values

Undertow Tuning

Checklist

• Use .boxlang.json in webroot for portable project-level config
• Enable --rewrites for SPA or front-controller apps (routes to index.bxm)
• Use getSystemSetting() to read env vars (works with both .env and real env vars)
• Enable --health-check --health-check-secure for container/load-balancer readiness probes
• Add warmupURLs for production to pre-load DB connections and caches
• Tune undertow.workerThreads based on expected concurrency
• Never rely on direct env var access for .env-sourced values