Primeros pasos
Instala BoxLang, clona la plantilla, configura tu base de datos y abre la pantalla de inicio de sesión.
En esta página
Primeros pasos
Requisitos del sistema
- Java 21+ (JDK o JRE)
- BoxLang 1.17+
- CommandBox 7+ (
bx-cli) - Node.js 22+ (para el frontend con Vite)
- Una base de datos compatible: MySQL 8+ (predeterminada), MariaDB, PostgreSQL, SQLite, Oracle o MSSQL
- Cualquier sistema operativo
Instalar BoxLang
macOS y Linux
# 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
Windows
powershell -NoExit -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://install-windows.boxlang.io'))"
Usa BVM en su lugar si necesitas alternar entre varias versiones de BoxLang:
curl -fsSL https://install-bvm.boxlang.io | bash
bvm install latest && bvm use latest
Verifica la instalación:
boxlang --version
CBGenesis es una plantilla de BoxLang. No instales la distribución estándar de CommandBox basada en Lucee. Después de instalar BoxLang con el instalador rápido o BVM, instala el módulo CLI nativo de BoxLang. Esto es necesario antes de ejecutar box install, box server, box migrate o box testbox:
install-bx-module bx-cli
Verifica que el CLI de BoxLang esté activo:
box version
Los desarrolladores que ya usan la distribución de CommandBox basada en Lucee deberían limpiar los artefactos en caché para asegurarse de estar ejecutando las últimas versiones de los módulos requeridos:
box artifacts clean
Si box no se encuentra después de la instalación, reinicia la terminal o añade el directorio que indica el instalador a tu PATH.
Monta el andamiaje de tu aplicación
Entra al shell de CommandBox escribiendo box primero:
install coldbox-cli
coldbox create app name="my-app" skeleton="cbgenesis"
!npm install
Abre el archivo .env en tu editor de texto preferido y actualiza las credenciales de la base de datos según corresponda. La plantilla viene preconfigurada para MySQL. MySQL, MariaDB, PostgreSQL y MSSQL son destinos de base de datos compatibles y probados. onServerInitialInstall de server.json instala el módulo del controlador JDBC que coincide con tu ajuste DB_DRIVER (bx-${DB_DRIVER}, predeterminado bx-mysql) la primera vez que ejecutas box server start. Para usar otra base de datos, establece DB_DRIVER en .env antes de ese primer inicio del servidor
Una vez configurado tu .env, ejecuta los siguientes comandos para inicializar y sembrar la base de datos. Debería descargar automáticamente los controladores necesarios para conectar el CLI a la base de datos configurada. Si hay algún problema de conexión, asegúrate de que el DB_DRIVER correcto esté establecido y de que el módulo del controlador JDBC correspondiente esté instalado.
migrate init
migrate up --seed
resources/database/seeds/AdminData.bx crea un rol Admin con los 20 permisos incorporados, y un usuario administrador:
| Campo | Valor |
|---|---|
| Correo electrónico | admin@cbgenesis.com |
| Contraseña | test (pendiente de restablecimiento) |
Esta cuenta se siembra como pendiente de restablecimiento, así que iniciar sesión con test no te da una sesión: te lleva directamente al formulario de restablecimiento de contraseña para elegir una contraseña real. Esto es deliberado: el hash de arranque viene incluido en este repositorio y es público. Consulta la lista de verificación de producción.
CBGenesis viene con directrices, skills y archivos de agentes de IA preconfigurados en .agents/, de modo que asistentes como GitHub Copilot, Cursor y Claude Code obtienen contexto preciso de ColdBox y BoxLang. Estos son generados por el módulo coldbox-cli que instalaste en el paso de andamiaje. Actualízalos después de montar el andamiaje para que las directrices y skills coincidan con tus módulos instalados:
coldbox ai refresh
Ejecuta coldbox ai refresh de nuevo cada vez que instales, actualices o elimines módulos de CommandBox para que se recojan las directrices y skills específicas de cada módulo.
coldbox ai --help # Discover the available AI commands
coldbox ai info # Show installed guidelines, skills, agents, and MCP servers
coldbox ai skills list # List the available skills
coldbox ai agents --help # Add, update, or remove AI agent configuration files
server start
Este es el comando de servidor del CLI de BoxLang. La primera ejecución instala los módulos de BoxLang listados en server.json (bx-esapi, bx-password-encrypt, bx-mail, bx-orm, el controlador JDBC seleccionado por DB_DRIVER, y bx-image).
onServerInitialInstall solo se dispara en el primer arranque de un servidor, así que cambiar DB_DRIVER después no reinstalará el controlador por sí solo. Ejecuta server forget (que borra el estado de instalación del servidor) antes de volver a iniciarlo para que se instale el nuevo controlador:
server forget
server start
npm run dev
Abre la aplicación
Visita http://127.0.0.1:8080 - llegarás a la página de inicio de sesión. Inicia sesión con las credenciales de administrador sembradas arriba.
AuthSplit predeterminado.Una vez dentro, llegarás al panel de control, con la barra lateral de administración lista para Usuarios, Roles, Permisos, Registro de Auditoría y Configuración:
Descubre cómo encajan entre sí public/, app/, resources/ y lib/, y recorre el ciclo de vida de una solicitud.
Comprende el flujo de inicio de sesión y el modelo de permisos resource:action antes de agregar tu primera página protegida.
¿Listo para construir? Empieza aquí para conocer los pasos exactos para agregar un nuevo módulo CRUD.