Getting Started
Install BoxLang, clone the template, configure your database, and open the login screen.
Getting Started
System requirements
- Java 21+ (JDK or JRE)
- Node.js 18+ (for the Vite frontend)
- MySQL 8+ (default - any JDBC-compatible database works)
- macOS, Linux, or Windows
Install BoxLang
# macOS & Linux
/bin/bash -c "$(curl -fsSL https://install.boxlang.io)"
# ...with automatic Java 21 installation
curl -fsSL https://install.boxlang.io | bash -s -- --with-jre
powershell -NoExit -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://install-windows.boxlang.io'))"
Use BVM instead if you need to switch between multiple BoxLang versions:
curl -fsSL https://install-bvm.boxlang.io | bash
bvm install latest && bvm use latest
Verify the install:
boxlang --version
CB Genesis is a BoxLang template. Do not install the standard Lucee-based CommandBox distribution. After installing BoxLang with the quick installer or BVM, install the BoxLang-native CLI module. This is required before running box install, box server, box migrate, or box testbox:
install-bx-module bx-cli
Verify that the BoxLang CLI is active:
box version
Current developers using the Lucee-based CommandBox distribution should clean cached artifacts to ensure they are running the latest versions of the required modules:
box artifacts clean
If box is not found after installation, restart the terminal or add the directory reported by the installer to your PATH.
Scaffold your app
git clone https://github.com/coldbox-templates/cbGenesis my-app
cd my-app
box install
Runs through bx-cli and installs ColdBox, WireBox/CacheBox/LogBox, TestBox, qb, cbsecurity, cborm, cbmailservices, and every other box.json dependency into lib/.
npm install
Pulls in Alpine.js, Bootstrap 5, and Vite for the frontend build.
The template ships pre-configured for MySQL (bx-mysql, installed automatically on first server start via server.json's onServerInitialInstall). Swap it for another database instead:
box install bx-postgresql # PostgreSQL
box install bx-mssql # Microsoft SQL Server
box install bx-h2 # H2 (embedded, dev only)
box install bx-oracle # Oracle
box install bx-sqlite # SQLite
Then update both .env (connection string) and the datasource block in public/Application.bx.
cp .env.example .env
Edit .env with your database credentials - see Configuration for what each variable does.
box migrate up
box migrate seed
resources/database/seeds/AdminData.bx creates an Administrator role with all 16 built-in permissions, and one admin user:
| Field | Value |
|---|---|
admin@cbgenesis.com | |
| Password | test |
Change this password immediately after your first login - see the production checklist.
box server start
This is the BoxLang CLI server command. The first run installs the BoxLang modules listed in server.json (bx-esapi, bx-password-encrypt, bx-mail, bx-orm, bx-mysql).
npm run dev
Open the app
Visit http://127.0.0.1:8080 - you'll land on the login page. Sign in with the seeded admin credentials above.
See how public/, app/, resources/ and lib/ fit together, and walk the request lifecycle.
Understand the login flow and the resource:action permission model before you add your first protected page.
Ready to build? Start here for the exact steps to add a new CRUD module.