BoxLang with Docker

Overview

BoxLang ships three official Docker images for different use cases: a headless CLI image, a MiniServer web runtime, and a MiniServer + Nginx reverse-proxy image. All images are available in Debian (default) and Alpine (-alpine) flavors and as nightly snapshots (-snapshot).

Image Reference

Variants

CLI Image

Run a Script

docker run --rm \
  -v "$(pwd):/scripts" \
  ortussolutions/boxlang:cli \
  boxlang /scripts/myscript.bxs

Open an Interactive REPL

docker run --rm -it ortussolutions/boxlang:cli boxlang

Pass Variables via CLI

docker run --rm \
  -e MY_VAR=hello \
  -v "$(pwd):/scripts" \
  ortussolutions/boxlang:cli \
  boxlang /scripts/greet.bxs

MiniServer Image

The MiniServer image serves a BoxLang web application from /app on port 8080.

Basic Usage

docker run --rm \
  -p 8080:8080 \
  -v "$(pwd)/src:/app" \
  ortussolutions/boxlang:miniserver

Install Modules at Startup

docker run --rm \
  -p 8080:8080 \
  -e "BOXLANG_MODULES=bx-mail bx-pdf" \
  -v "$(pwd)/src:/app" \
  ortussolutions/boxlang:miniserver

Key Environment Variables

miniserver.json Configuration

Place miniserver.json in your /app directory (or point to it with MINISERVER_JSON) to customize the server:

{
  "port": 8080,
  "webroot": "/app",
  "host": "0.0.0.0",
  "debug": false,
  "ssl": false
}

Health Check

The MiniServer image includes a built-in health check endpoint. Default behavior:

Override the health check URI:

docker run -e HEALTHCHECK_URI=/status ortussolutions/boxlang:miniserver

MiniServer + Nginx Image

The miniserver-nginx image bundles BoxLang MiniServer behind Nginx for SSL termination, caching, and production deployments:

docker run --rm \
  -p 80:80 \
  -p 443:443 \
  -v "$(pwd)/src:/app" \
  -v "$(pwd)/nginx/conf.d:/etc/nginx/conf.d" \
  ortussolutions/boxlang:miniserver-nginx

Dockerfile Examples

Simple Web Application

FROM ortussolutions/boxlang:miniserver

# Set environment
ENV BOXLANG_MODULES="bx-mail bx-pdf"
ENV MAX_MEMORY=512m

# Copy application
COPY --chown=boxlang:boxlang src/ /app/

# Copy config
COPY --chown=boxlang:boxlang config/miniserver.json /app/miniserver.json

EXPOSE 8080

Multi-Stage Build (Alpine)

# Build stage
FROM ortussolutions/boxlang:cli-alpine AS builder

WORKDIR /build
COPY . .

# Run any build steps (compile, test, etc.)
RUN boxlang build.bxs

# Runtime stage
FROM ortussolutions/boxlang:miniserver-alpine

COPY --from=builder /build/dist /app
COPY --chown=boxlang:boxlang miniserver.json /app/miniserver.json

ENV MAX_MEMORY=256m
EXPOSE 8080

Docker Compose

version: "3.9"

services:
  app:
    image: ortussolutions/boxlang:miniserver
    ports:
      - "8080:8080"
    environment:
      BOXLANG_MODULES: "bx-mail"
      MAX_MEMORY: 512m
      BOXLANG_DEBUG: "false"
    volumes:
      - ./src:/app
      - boxlang-home:/root/.boxlang
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthcheck"]
      interval: 20s
      timeout: 10s
      retries: 5
      start_period: 30s
    restart: unless-stopped

  db:
    image: mariadb:11
    environment:
      MARIADB_ROOT_PASSWORD: secret
      MARIADB_DATABASE: myapp
    volumes:
      - db-data:/var/lib/mysql

volumes:
  boxlang-home:
  db-data:

Production Tips

• Use Alpine images in production (-alpine) — significantly smaller footprint
• Pin to a version tag (ortussolutions/boxlang:1.2.3-miniserver) rather than latest for reproducibility
• Set `MAX_MEMORY` — BoxLang/JVM defaults may be too low for containers
• Mount volumes read-only for application code: -v $(pwd)/src:/app:ro
• Use secrets via environment variables, not baked into images
• Enable health checks and connect to your orchestrator (Kubernetes, ECS, etc.)

Checklist

• [ ] Correct image chosen for use case (CLI / MiniServer / Nginx)
• [ ] BOXLANG_MODULES lists all runtime module dependencies
• [ ] JVM memory configured via MAX_MEMORY / MIN_MEMORY or JAVA_OPTS
• [ ] Health check endpoint configured and tested
• [ ] Application secrets injected via runtime env vars (not in image)
• [ ] Image version pinned for production deployments
• [ ] Alpine variant used for production to reduce image size