MiniServer
BoxLang includes a lightning fast web server powered by Undertow!
Last updated
Was this helpful?
BoxLang includes a lightning fast web server powered by Undertow!
Last updated
Was this helpful?
The BoxLang MiniServer runtime is a lightweight, lightning-fast web server powered by Undertow. It's ideal for light-weight applications, electron apps, embedded web servers, and development. For those who desire a more robust and feature-rich servlet server implementation, we offer our and 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 , it becomes a powerhouse for mission-critical applications. Check out all that you get with CommandBox Pro:
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.
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 localhost:8080 by default
This configures the web server with some default welcome files and no rewrites.
BoxLang will process any BoxLang or CFML files
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.
These are the supported arguments you can pass into the binary to configure the server.
--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. By default we use false
--host ip|domain
-h ip|domain
Bind the hostname to the mini server. By default we use localhost
--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
--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/
--webroot path/
-w path/
The webserver root. By default, we use the directory from where you started the command.
The boxlang-miniserver binary will also scan for several environment variables as overrides to the execution process.
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 localhost 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_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.
You can load up custom third-party JARs into the runtime in two ways
BOXLANG_HOME/lib - You can place all the jars that the runtime will load in this location
Remember, you can use the --serverHome to choose the location of the server's home
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.
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.
You can use the BOXLANG_MINISERVER_OPTS env variable to seed the Java arguments the miniserver will start with.
We welcome any pull requests, testing, docs, etc.
Please note that our can also assist you in managing and starting/stopping servers.
The runtime source code can be found here:
