BoxLang with Docker

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

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

Image	Purpose	Default port
ortussolutions/boxlang:cli	Run scripts, REPL, batch jobs	—
ortussolutions/boxlang:miniserver	Standalone web server	8080
ortussolutions/boxlang:miniserver-nginx	Web server + Nginx reverse proxy	80

Variants

Suffix	Description
(none)	Debian base
-alpine	Alpine Linux — smaller image (~50% smaller)
-snapshot	Latest nightly snapshot build

---

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

Variable	Description
BOXLANG_MODULES	Space-delimited list of BoxLang modules to install on startup
BOXLANG_DEBUG	true to enable verbose BoxLang debug output
MINISERVER_JSON	Override path to the miniserver.json config file
JAVA_OPTS	JVM options (e.g., -Xmx512m -XX:+UseG1GC)
MAX_MEMORY	Maximum JVM heap (e.g., 512m) — shortcut for -Xmx
MIN_MEMORY	Minimum JVM heap (e.g., 128m) — shortcut for -Xms

---

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:

Setting	Value
Check interval	20 seconds
Timeout	30 seconds
Retries	15
URI	/healthcheck

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