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)
- A supported database: MySQL 8+ (default), MariaDB, PostgreSQL, or MSSQL
- 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. MySQL, MariaDB, PostgreSQL, and MSSQL are supported and tested database targets. server.json's onServerInitialInstall installs the JDBC driver module matching your DB_DRIVER setting (bx-${DB_DRIVER}, defaulting to bx-mysql) the first time you run box server start. To use another database, set DB_DRIVER in .env before that first server start:
DB_DRIVER=postgresql # installs bx-postgresql
DB_DRIVER=mssql # installs bx-mssql (Microsoft SQL Server)
DB_DRIVER=h2 # installs bx-h2 (embedded, dev only)
DB_DRIVER=oracle # installs bx-oracle
DB_DRIVER=sqlite # installs bx-sqlite
Then update .env's connection details and the datasource block in public/Application.bx (and tests/Application.bx for the test suite).
MariaDB uses the MySQL JDBC driver setting:
DB_DRIVER=mysql
onServerInitialInstall only fires on a server's first-ever start, so changing DB_DRIVER afterward won't reinstall the driver on its own. Run server forget (which clears the server's install state) before starting it again so the new driver gets installed:
server forget
box server start
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 Admin role with all 20 built-in permissions, and one admin user:
| Field | Value |
|---|---|
admin@cbgenesis.com | |
| Password | test (reset-pending) |
This account is seeded as reset-pending, so signing in with test does not give you a session - it takes you straight to the reset-password form to choose a real password. That is deliberate: the bootstrap hash ships in this repository and is public. 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, the JDBC driver selected by DB_DRIVER, and bx-image).
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.
Once you're in, you'll land on the dashboard, with the admin sidebar ready for Users, Roles, Permissions, Audit Log, and Settings:
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.