Ctrlk
DownloadTrySourceSupportAI SDK
For the complete documentation index, see llms.txt. This page is also available as Markdown.

MiniServer

The BoxLang MiniServer runtime is a lightweight, lightning-fast web server powered by Undertow!

The BoxLang MiniServer runtime is a lightweight, lightning-fast web server powered by Undertow. It's ideal for fast applications, desktop apps (Electron/JavaFX), embedded web servers, and development. For those who want a more robust, feature-rich servlet server implementation, we offer our open-source, FREE CommandBox server and CommandBox PRO with a BoxLang Subscription.

Tip: Please note that the BoxLang MiniServer is NOT a servlet server. There is no servlet container; the web server is just a simple, fast, and pure-Java Undertow server.

CommandBox is our open-source servlet server implementation. However, with a Boxlang +/++ subscription, it becomes a powerhouse for mission-critical applications. Check out all that you get with CommandBox Pro: https://www.ortussolutions.com/products/commandbox-pro

📋 Table of Contents

▶️ Start a Server

The BoxLang core OS runtime doesn't know about a web application. Our web support runtime provides this functionality, a crucial part of the MiniServer and the Servlet (JEE, Jakarta, CommandBox) runtime. This runtime enhances the core boxlang runtime, making it multi-runtime and web deployable.

If you use our Windows installer or our Quick Installer, you will have the boxlang-miniserver binary installed in your operating system. You will use this to start servers. Just navigate to any folder that you want to start a server in and run boxlang-miniserver.

Please note that our VSCode BoxLang Extension can also assist you in managing and starting/stopping servers.

Once you run the command, the following output will appear in your console:

As you can see from the output, this is the result of the command:

  • Use the current working directory as the web root.

  • Bind to 0.0.0.0:8080 by default (accessible from any network interface)

  • Automatic .env file loading - Environment variables from .env files in the webroot are loaded into the system properties

  • Built-in security protection - Blocks access to hidden files and directories (starting with .) for security

  • WebSocket support is enabled by default at /ws endpoint

  • This configures the web server to serve default welcome files and to perform no rewrites.

  • BoxLang will process any BoxLang or CFML files (bx,bxs,bxm,cfc,cfm)

  • Uses the user's BoxLang home as the default for configuration and modules: ~/.boxlang

ALERT: The BoxLang Core knows nothing of web or HTTP, so the form, url, cookie, and cgi scopes will only exist when running the BoxLang web server (but not in the REPL, etc).

That's practically it. This is a very lightweight server that can get the job done. You can also start up servers using our VSCode IDE by opening the command palette and clicking Start a BoxLang web server.

Command Palette
Manage your Servers

📋 JSON Configuration

The BoxLang MiniServer supports loading configuration from a JSON file. This allows you to store all server settings in one place rather than passing them as command-line arguments each time.

Automatic Loading

If you run boxlang-miniserver with no arguments, it will automatically look for a miniserver.json file in the current directory:

Explicit Path

You can also specify the path to a JSON configuration file:

Override with CLI

Command-line arguments always override JSON configuration:

Configuration Options

All the following options are supported in the JSON configuration file:

Option
Type
Default
Description

aliases

object

{}

URL-prefix to filesystem-path mappings (struct or array form)

configPath

string

null

Path to BoxLang configuration file

debug

boolean

false

Enable debug mode

envFile

string

null

Path to custom environment file (relative or absolute)

healthCheck

boolean

false

Enable health check endpoints

healthCheckSecure

boolean

false

Restrict detailed health info to localhost only

host

string

"0.0.0.0"

The host to bind to

passPredicate

string

(see below)

Undertow predicate expression that determines which requests are routed to BoxLang

port

number

8080

The port to listen on

rewriteFileName

string

"index.bxm"

Rewrite target file

rewrites

boolean

false

Enable URL rewrites

serverHome

string

null

BoxLang server home directory

socketOptions

object

{}

XNIO socket-level options keyed by Options constant names

undertowOptions

object

(see below)

Undertow server-level options keyed by UndertowOptions constant names

warmupUrl

string

null

Single URL path to request on server startup (shorthand for one URL)

warmupUrls

array

[]

Array of URL paths to request on server startup for application initialization

webRoot

string

current directory

Path to the webroot directory

workerOptions

object

{}

XNIO worker-level options keyed by Options constant names

.boxlang.json Project Convention

When the MiniServer starts, it automatically looks for a .boxlang.json file in the current working directory. If found, it is merged with the base BoxLang configuration (boxlang.json) — providing a portable, project-level configuration override without touching the global runtime settings.

This is ideal for:

  • Containerized deployments — bundle a project-specific config without baking it into the image

  • Team environments — commit .boxlang.json to source control for consistent per-project settings

  • Multiple projects — each project can override runtime settings independently

The .boxlang.json file is merged on top of the global boxlang.json. Any settings not specified in .boxlang.json fall back to the global config.

Undertow, Worker & Socket Options

For fine-grained control over the underlying Undertow HTTP server, XNIO worker, and TCP socket layers, you can specify undertowOptions, workerOptions, and/or socketOptions objects in your miniserver.json. Keys must match the constant names used in Undertow and XNIO (upper-case, e.g. MAX_ENTITY_SIZE). Keys are case-insensitive in the JSON — they are normalized to UPPER_CASE automatically.

undertowOptions — applied via builder.setServerOption(). Keys match io.undertow.UndertowOptions constants.

The following defaults replace Undertow's built-in 2 MB limits:

Key
Default
Description

MAX_ENTITY_SIZE

25 MB

Maximum HTTP entity body size (JSON, form posts, etc.)

MULTIPART_MAX_ENTITY_SIZE

100 MB

Maximum multipart/form-data upload size

Other commonly useful options:

Key
Type
Description

MAX_HEADER_SIZE

int

Max HTTP request header size in bytes (default: 1 MB)

IDLE_TIMEOUT

int

Idle connection timeout in milliseconds

REQUEST_PARSE_TIMEOUT

int

Max time to parse a request in milliseconds

MAX_PARAMETERS

int

Max query/POST parameters (default: 1000)

MAX_HEADERS

int

Max request headers (default: 200)

ENABLE_HTTP2

boolean

Enable HTTP/2 for HTTPS connections

workerOptions — applied via builder.setWorkerOption(). Keys match org.xnio.Options constants.

Key
Type
Description

WORKER_IO_THREADS

int

Number of I/O threads

WORKER_TASK_CORE_THREADS

int

Core worker thread pool size

WORKER_TASK_MAX_THREADS

int

Maximum worker thread pool size

WORKER_TASK_KEEPALIVE

int

Milliseconds to keep idle threads alive

socketOptions — applied via builder.setSocketOption(). Keys match org.xnio.Options constants.

Key
Type
Description

TCP_NODELAY

boolean

Disable Nagle's algorithm for lower latency

RECEIVE_BUFFER

int

TCP receive buffer size in bytes

SEND_BUFFER

int

TCP send buffer size in bytes

KEEP_ALIVE

boolean

Enable TCP keep-alive

BACKLOG

int

Accept backlog (max queued connections)

REUSE_ADDRESSES

boolean

Reuse addresses in TIME_WAIT state

These are advanced tuning options. In most cases the defaults are appropriate. Only change these if you understand the implications for concurrency, memory, and throughput.

Example Configuration Files

Example Configuration Files

Basic Configuration

Development Configuration

Production Configuration

Complete Configuration

Configuration Priority

Configuration values are loaded in the following order (later sources override earlier ones):

  1. Default values - Built-in defaults

  2. Environment variables - BOXLANG_* environment variables

  3. JSON configuration - Values from the JSON file

  4. Command-line arguments - Explicit CLI flags

For example, if you have:

  • Environment variable: BOXLANG_PORT=3000

  • JSON file: "port": 8080

  • CLI argument: --port 9090

The server will start on port 9090 (CLI overrides all).

Configuration Notes

  • The JSON file must be valid JSON (no comments allowed in the actual file)

  • All fields are optional - you only need to specify the ones you want to change

  • Null values in the JSON file will be treated as "not set."

  • Boolean values must be lowercase (true or false)

  • String paths can be relative or absolute

Environment File Loading

The envFile option allows you to specify a custom environment file to load instead of the default .env file in the webroot:

  • If envFile is not specified, the server looks for .env in the webroot directory (default behavior)

  • If envFile is specified, it loads that file instead

  • The path can be relative (resolved from the current directory) or absolute

  • Environment variables are loaded as system properties and can be used throughout the application

Example:

or

🔧 Arguments

These are the supported arguments you can pass into the binary to configure the server.

Argument
Value

--configPath path/boxlang.json -c path/boxlang.json

Relative/Absolute location of the boxlang.json to use. By default it uses the ~/.boxlang/boxlang.json

--debug -d

Put the runtime into debug mode. This will also render detailed error messages in the browser. By default we use false

--help -h

Display comprehensive help information and exit

--host ip|domain

Bind the hostname to the mini server. By default we use 0.0.0.0 (all network interfaces)

--port 8080 -p 8080

The port to bind the mini server to. By default we use port 8080

--rewrites [index.bxm] -r [index.bxm]

Enable rewrites for applications using index.bxm as the file to use. You can also pass the name of the file to use: --rewrites myfile.bxm

--health-check

Enable health check endpoints at /health, /health/ready, and /health/live. These provide detailed server status, readiness, and liveness information in JSON format.

--health-check-secure

Restrict detailed health check information to localhost only. When enabled, non-localhost requests receive basic status only, while localhost gets full system details including JVM metrics and memory usage.

--serverHome path/ -s path/

The location of the BoxLang home for the miniserver. This is where it will look for the boxlang.json, place to put the log files, the compiled classes, load modules, and much more. By default, we use the OS home via the BOXLANG_HOME environment variable which usually points to the user's home: ~/.boxlang/

--version -v

Display version information and exit

--webroot path/ -w path/

The webserver root. By default, we use the directory from where you started the command.

🛡️Environment Variables

The boxlang-miniserver binary will also scan for several environment variables as overrides to the execution process.

Env Variable
Purpose

BOXLANG_CONFIG = PATH

Override the boxlang.json

BOXLANG_DEBUG = boolean

Enable or disable debug mode

BOXLANG_HOME = directory

Override the server HOME directory

BOXLANG_HOST = ip or domain

Override the 0.0.0.0 default to whatever IP or domain you like.

BOXLANG_PORT = 8080

Override the default port

BOXLANG_REWRITES = boolean

Enable or disable URL rewrites

BOXLANG_REWRITE_FILE = file.bxm

Choose the rewrite file to use. By default, it uses index.bxm

BOXLANG_WEBROOT = path

Override the location of the web root

BOXLANG_HEALTH_CHECK = boolean

Enable or disable health check endpoints

BOXLANG_HEALTH_CHECK_SECURE = boolean

Enable secure health checks (detailed info only on localhost)

BOXLANG_MINISERVER_OPTS = jvmOptions

A list of Java options to pass to the startup command

Environment variables are scanned first, then the command arguments. Thus, the command arguments take precedence.

🔒 Security Features

The BoxLang MiniServer includes built-in security features to protect your applications:

Hidden File Protection

The server automatically blocks access to hidden files and directories (those starting with a dot .). This security feature protects sensitive files such as:

  • .env files containing environment variables

  • .git directories and configuration

  • .htaccess and other web server configuration files

  • Any custom hidden files or directories

When a request is made for a hidden file, the server returns a 404 Not Found response for security reasons, without revealing whether the file actually exists.

Security Note: This protection is enabled by default and cannot be disabled. It's a fundamental security feature designed to prevent accidental exposure of sensitive configuration files.

🩺 Health Check Endpoints

The MiniServer provides comprehensive health monitoring capabilities through dedicated endpoints:

Basic Health Checks

Enable health checks with the --health-check flag:

This enables three endpoints:

  • /health - Complete health information including system metrics, JVM details, and runtime status

  • /health/ready - Readiness probe for load balancers (simple UP/DOWN status)

  • /health/live - Liveness probe for container orchestration (simple UP/DOWN status)

Secure Health Checks

For production environments, use the --health-check-secure flag:

When secure mode is enabled:

  • Localhost requests receive full detailed health information

  • Remote requests receive only basic status information

  • This prevents sensitive system information from being exposed to external networks

Health Check Response Format

BoxLang v1.14+ — The /health endpoint now includes Undertow worker pool statistics, listener metrics, request timing data, and WebSocket session counts.

The /health endpoint returns comprehensive JSON information:

The health check provides:

Core Metrics

Field
Description

status

Current server status (UP / DOWN)

timestamp

Current server time in ISO 8601 format

uptime

Human-readable server uptime

uptimeMs

Server uptime in milliseconds

version

BoxLang version information

buildDate

When BoxLang was built

javaVersion

JVM version information

memoryUsed

Current JVM memory usage in bytes

memoryMax

Maximum available JVM memory in bytes

activeRequests

Number of requests currently being processed

Worker Pool (workerPool)

Undertow XNIO worker thread pool statistics:

Field
Description

core

Core thread pool size

max

Maximum thread pool size

current

Current number of threads in the pool

busy

Number of busy threads (-1 if unavailable)

ioThreadCount

Number of I/O threads handling network operations

queueSize

Number of tasks waiting in the worker queue

Listeners (listeners)

Per-listener Undertow statistics (array — one entry per configured listener):

Field
Description

name

Listener name (e.g., "http", "https")

requestCount

Total number of requests handled by this listener

errorCount

Total number of errors returned by this listener

bytesSent

Total bytes sent to clients

bytesReceived

Total bytes received from clients

activeConnections

Currently open TCP connections

activeRequests

Requests currently being processed on this listener

Request Metrics (requestMetrics)

Aggregate request timing statistics:

Field
Description

totalRequests

Total number of requests processed since startup

totalErrors

Total number of error responses returned

totalRequestTime

Cumulative request processing time (ms)

maxRequestTime

Slowest single request time (ms)

minRequestTime

Fastest single request time (ms)

WebSocket (websocket)

WebSocket session counts:

Field
Description

activeConnections

Currently active WebSocket connections

openConnections

Total open WebSocket sessions

🌍 Environment Files

The MiniServer automatically loads environment variables from .env files located in your webroot directory:

Automatic .env Loading

When you start the server, it will automatically look for and load a .env file in the webroot:

.env File Format

Your .env file should contain key-value pairs:

Accessing Loaded Variables

Environment variables loaded from .env files are:

  1. Added to Java System Properties - Accessible via System.getProperty("key")

  2. Available in BoxLang - Accessible through the server.system.properties struct

  3. Available to your applications - Can be used in BoxLang code for configuration

Note that these variables will not be available as "proper" environment variables because BoxLang's runtime loads them differently. The structure, server.system.environment, contains system-level environment variables and will not reflect the values set in your .env file.

Using server.system.properties would work locally, but not in production, as the value would most likely instead be in the environment structure. Luckily, BoxLang provides a simple BIF that can work with either getSystemSetting(). Given the example .env file above, using getSystemSetting("API_KEY") would work both locally, using the value loaded from the file, and in production, using a value loaded as an environment variable.

Privacy Note: Environment variables are NOT exposed through health check endpoints. Health checks return server metrics (JVM, Undertow worker pool, listener stats, request timing, WebSocket sessions) but never application data, secrets, or environment variables. Use --health-check-secure in production to restrict detailed metrics to localhost only.

🌩 Warmup URLs

The MiniServer supports warmup URLs, which automatically request specific URLs when the server starts up. This is useful for pre-loading applications, initializing caches, or warming up services before accepting production traffic.

Why Use Warmup URLs?

Warmup URLs help with:

  • Faster first requests - Pre-load application code and dependencies before users arrive

  • Cache initialization - Populate caches with frequently accessed data

  • Service initialization - Initialize database connections, external API clients, etc.

  • Application preloading - Load and compile BoxLang templates ahead of time

  • Reduce cold start latency - Ensure the application is fully ready before serving traffic

Configuring Warmup URLs

Add the warmupURLs array to your JSON configuration file:

How Warmup Works

When the server starts:

  1. Server initialization completes first

  2. Warmup requests are sent to each URL in the array (in order)

  3. Sequential execution - each URL completes before the next starts

  4. Error handling - failures are logged, but don't stop server startup

  5. Server ready - after all warmup URLs are complete, the server is fully ready

Warmup URL Examples

Basic Application Preload

Multiple Initialization Endpoints

Production Warmup Strategy

Creating Warmup Endpoints

Create dedicated warmup endpoints in your BoxLang application:

Warmup Best Practices

  1. Keep warmup URLs lightweight - Focus on initialization, not heavy processing

  2. Use dedicated endpoints - Create specific /warmup/* endpoints for initialization

  3. Sequential dependencies - Order URLs so dependencies load first (e.g., database before cache)

  4. Error handling - Ensure warmup endpoints handle errors gracefully

  5. Return quickly - Warmup should complete in seconds, not minutes

  6. Health checks - Include a health check endpoint as the final warmup URL to verify readiness

Console Output

When warmup URLs are configured, you'll see output during server startup:

Error Handling

If a warmup URL fails, the error is logged, but server startup continues:

Tip: Use warmup URLs in production deployments to ensure your application is fully initialized before accepting user traffic. This is especially important in containerized environments or auto-scaling scenarios where new instances are frequently created.

Performance Note: Warmup URLs are executed sequentially during server startup. Keep individual warmup operations fast to minimize total startup time. For complex initialization, consider using asynchronous initialization within your warmup endpoints.

🔌 WebSocket Support

WebSocket Support / SocketBox

The BoxLang MiniServer includes built-in WebSocket support for real-time communication:

WebSocket Endpoint

WebSocket connections are available at the /ws endpoint:

New in 1.6.0: The MiniServer now properly returns STOMP heartbeat responses, ensuring reliable WebSocket connections with STOMP protocol support.

SocketBox - BoxLang WebSocket Library

For enhanced WebSocket functionality in your BoxLang applications, we recommend using SocketBox - our companion library specifically designed for BoxLang WebSocket development:

SocketBox is available on ForgeBox: https://forgebox.io/view/socketbox

SocketBox provides:

  • Core WebSocket lifecycle hooks (onConnect, onMessage, onClose)

  • Low-level channel messaging with sendMessage() and broadcastMessage()

  • Connection inspection via getAllConnections()

  • Optional STOMP broker mode for subscriptions, routing, auth, and heartbeats

  • Integration with BoxLang and CFML runtimes

SocketBox core keeps the API intentionally simple: handle lifecycle events with a channel, send targeted replies with sendMessage(), broadcast with broadcastMessage(), and inspect active connections with getAllConnections().

Installing SocketBox

SocketBox Example

If you need topic subscriptions, destination routing, and protocol-level auth/authorization, use SocketBox's STOMP mode by extending WebSocketSTOMP instead of core WebSocketCore.

WebSocket Features

  • Real-time bidirectional communication between client and server

  • Automatic connection management with built-in error handling

  • STOMP protocol support with proper heartbeat responses for connection reliability

  • Integration with BoxLang runtime for server-side message processing

  • Low latency communication for interactive applications

  • Enhanced functionality with SocketBox library for production applications

The WebSocket server is automatically started when the MiniServer launches, as indicated by the console message:

WebSocket Note: The WebSocket endpoint is always enabled and cannot be disabled. This provides a consistent real-time communication channel for all BoxLang applications. For production applications, consider using SocketBox for enhanced features and easier development.

🏠 Default Welcome Files

The BoxLang MiniServer automatically serves welcome files when a request is made to a directory. The server looks for these files in the following order:

  1. index.bxm - BoxLang Markup (preferred)

  2. index.bxs - BoxLang Script

  3. index.cfm - CFML Markup (legacy compatibility)

  4. index.cfs - CFML Script (legacy compatibility)

  5. index.htm - HTML

  6. index.html - HTML

Welcome File Behavior

When a request is made to a directory (e.g., http://localhost:8080/), the server will:

  1. Check for welcome files in the order listed above

  2. Serve the first match found in the directory

  3. Enable directory listing if no welcome file is found (showing folder contents)

  4. Process BoxLang/CFML files through the runtime before serving

  5. Serve static files (HTML) directly without processing

Example Directory Structure

Tip: Use index.bxm for your main pages to take advantage of BoxLang's modern syntax and features while maintaining compatibility with legacy CFML files.

🔀 URL Rewrites

URL Rewrites

The BoxLang MiniServer supports URL rewrites for creating clean, SEO-friendly URLs and building single-page applications (SPAs):

Enabling URL Rewrites

Enable URL rewrites with the --rewrites flag:

How URL Rewrites Work

When URL rewrites are enabled:

  1. Any request that does not match an asset will route through your specified rewrite file (default: index.bxm)

  2. This includes requests to JavaScript, CSS, images and BXM, BXS, or BX files.

URL Rewrite Examples

Use Cases for URL Rewrites

  • Single Page Applications (SPAs) - Route all requests to your main app file

  • Clean URLs - /products/123 instead of /product.bxm?id=123

  • Custom routing - Implement your own URL routing logic

  • Framework applications - Perfect for ColdBox, FW/1, or custom frameworks

Console Output

When rewrites are enabled, you'll see:

Rewrite Note: URL rewrites work best for dynamic applications and frameworks. Static websites typically don't need URL rewriting enabled.

🗂️ Folder Aliases

Folder aliases map URL path prefixes to arbitrary directories on disk, letting the MiniServer serve static and executable BoxLang/CFML content from locations outside the webroot.

Configuration

Aliases are defined under the aliases key in miniserver.json. Both a struct and an array form are supported — pick whichever is more readable for your config.

Struct form (concise):

Array form (explicit):

Matching Behavior

  • Longest prefix wins — with both /api and /api/v2 configured, a request for /api/v2/spec.json resolves through /api/v2.

  • Segment-boundary aware — /docs matches /docs and /docs/... but never /documentation.

  • Path resolution — absolute to paths are used as-is; relative paths resolve against the webRoot.

Example

Given the struct config above, requests are served from disk like so:

Request URL
Served from

/docs/index.bxm

/var/www/documentation/index.bxm

/shared/css/site.css

<webRoot>/../shared-assets/css/site.css

/api/v1/users.bxm

/srv/api/v1/users.bxm

/about.bxm

<webRoot>/about.bxm (no alias match — falls back to webroot)

Validation: Alias targets are checked at startup. Entries pointing at a non-existent path or a regular file are logged as a warning and skipped — the server still starts with the remaining valid aliases.

🛑 Server Management

Graceful Shutdown

The BoxLang MiniServer supports graceful shutdown for safe server termination:

When you stop the server, you'll see:

The graceful shutdown process:

  1. Stops accepting new requests immediately

  2. Completes active requests before shutting down

  3. Closes the BoxLang runtime properly

  4. Releases all resources (ports, file handles, etc.)

Background Execution

For production deployments, you can run the server in the background:

Production Note: For production deployments, consider using process managers like systemd, supervisor, or Docker containers for better service management and automatic restarts.

⚡ Performance Features

Performance Features

The BoxLang MiniServer includes several built-in performance optimizations:

Automatic GZIP Compression

The server automatically compresses responses using GZIP compression for better performance:

  • Automatic compression for responses larger than 1.5KB

  • Smart content detection - only compresses suitable content types

  • Client support detection - only compresses when client supports it

  • Bandwidth savings - typically 60-80% reduction in transfer size

Performance Characteristics

  • Fast startup times - typically under 1 second

  • Low memory footprint - minimal overhead beyond your application

  • High concurrency - built on Undertow's high-performance architecture

  • Zero-copy static file serving - optimized static asset delivery

  • Keep-alive connections - reduces connection overhead

Performance Tips

Performance Tip: The MiniServer is optimized for development and light production workloads. For high-traffic applications, consider using CommandBox with load balancing and clustering capabilities.

Using 3rd Party Jars

You can load up custom third-party JARs into the runtime in two ways

  1. BOXLANG_HOME/lib - You can place all the jars that the runtime will load in this location

    1. Remember, you can use the --serverHome to choose the location of the server's home

  2. Add via the classpath to your runner.

Please note that if you use the -cp approach, then you need to use a full java -cp syntax or you can customize the boxlang-miniserver shell scripts to do your bidding.

If you want to test 3rd part libs with the web server, you’ll need to use a different syntax that uses the -cp (classpath) JVM arg and specifies both the boxlang jar AND a semicolon-delimited list of the jars you want to use. It’s a little annoying, but this is how Java works.

Modules

The MiniServer can use any module you install into the OS home via the install-bx-module binary. However, if you choose your own server home using the server-home argument or the environment variable. Then, place the modules inside a modules directory inside the server's home.

JVM Options

You can use the BOXLANG_MINISERVER_OPTS env variable to seed the Java arguments the miniserver will start with.

Runtime Source Code

The runtime source code can be found here: https://github.com/ortus-boxlang/boxlang-miniserver

We welcome any pull requests, testing, docs, etc.

🌐 Reverse Proxy Setup

Reverse Proxy Setup

For production deployments, it's recommended to place a reverse proxy in front of the BoxLang MiniServer. This provides additional security, SSL termination, load balancing, and better static file serving capabilities.

🔧 Nginx Configuration

Nginx is a popular choice for reverse proxying BoxLang applications:

Basic Nginx Configuration

Load Balancing with Multiple MiniServers

🔥 Apache Configuration

Apache HTTP Server with mod_proxy for reverse proxying:

Basic Apache Configuration

Required Apache Modules

🪟 IIS Configuration

Internet Information Services (IIS) configuration using Application Request Routing (ARR):

Prerequisites

  1. Install Application Request Routing (ARR) module

  2. Install URL Rewrite module

IIS Configuration Steps

  1. Create a new website in IIS Manager

  2. Configure ARR at the server level:

Site-Level web.config

🚀 Production Setup Recommendations

Production Setup Recommendations
1

Configure MiniServer for Production

2

System Service Setup

Create a systemd service for automatic startup:

3

Security Considerations

  • Bind to localhost only when behind a reverse proxy

  • Enable health check security to restrict detailed information

  • Use HTTPS at the reverse proxy level

  • Configure proper security headers in your reverse proxy

  • Restrict health check endpoints to internal networks if needed

  • Regular security updates for your reverse proxy software

4

Monitoring and Logging

  • Access logs at the reverse proxy level

  • Health check monitoring using /health/ready and /health/live

  • Performance monitoring through reverse proxy metrics

  • Log aggregation for centralized monitoring

Production Tip: Using a reverse proxy provides additional benefits like SSL termination, static file serving, request compression, security headers, and load balancing capabilities that complement the BoxLang MiniServer's performance.

WebSocket Note: All reverse proxy configurations include WebSocket support. Make sure your reverse proxy properly handles WebSocket upgrade requests for real-time features to work correctly.

PreviousJSR-223 ScriptingNextSpring Boot

Last updated

Was this helpful?