Primeiros Passos
Instale o BoxLang, clone o template, configure a sua base de dados, e abra o ecrã de início de sessão.
Nesta página
Primeiros Passos
Requisitos do sistema
- Java 21+ (JDK ou JRE)
- BoxLang 1.17+
- CommandBox 7+ (
bx-cli) - Node.js 22+ (para o frontend com Vite)
- Uma base de dados suportada: MySQL 8+ (predefinição), MariaDB, PostgreSQL, SQLite, Oracle, ou MSSQL
- Qualquer sistema operativo
Instalar o BoxLang
MacOS e Linux
# macOS & Linux
/bin/bash -c "$(curl -fsSL https://install.boxlang.io)"
# ...com instalação automática do Java 21
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'))"
Utilize antes o BVM se precisar de alternar entre várias versões do BoxLang:
curl -fsSL https://install-bvm.boxlang.io | bash
bvm install latest && bvm use latest
Verifique a instalação:
boxlang --version
O CBGenesis é um template BoxLang. Não instale a distribuição padrão do CommandBox baseada em Lucee. Depois de instalar o BoxLang com o instalador rápido ou com o BVM, instale o módulo CLI nativo do BoxLang. Isto é obrigatório antes de executar box install, box server, box migrate, ou box testbox:
install-bx-module bx-cli
Verifique que a BoxLang CLI está ativa:
box version
Os programadores que já utilizam a distribuição do CommandBox baseada em Lucee devem limpar os artefactos em cache para garantir que estão a executar as versões mais recentes dos módulos necessários:
box artifacts clean
Se o box não for encontrado após a instalação, reinicie o terminal ou adicione ao seu PATH a diretoria indicada pelo instalador.
Estruturar a sua aplicação
Entre na Shell do CommandBox digitando primeiro box:
install coldbox-cli
coldbox create app name="my-app" skeleton="cbgenesis"
!npm install
Abra o ficheiro .env no seu editor de texto preferido e atualize as credenciais da base de dados adequadamente. O template vem pré-configurado para MySQL. MySQL, MariaDB, PostgreSQL, e MSSQL são os destinos de base de dados suportados e testados. O onServerInitialInstall do server.json instala o módulo do driver JDBC correspondente à sua definição DB_DRIVER (bx-${DB_DRIVER}, com predefinição bx-mysql) na primeira vez que executar box server start. Para utilizar outra base de dados, defina DB_DRIVER no .env antes desse primeiro arranque do servidor
Depois de definir o seu .env, execute os seguintes comandos para inicializar e semear a base de dados. Deverá transferir automaticamente os drivers necessários para ligar a CLI à base de dados configurada. Se houver algum problema na ligação, garanta que o DB_DRIVER correto está definido e que o módulo do driver JDBC correspondente está instalado.
migrate init
migrate up --seed
resources/database/seeds/AdminData.bx cria uma função Admin com todas as 20 permissões incorporadas, e um utilizador administrador:
| Campo | Valor |
|---|---|
admin@cbgenesis.com | |
| Palavra-passe | test (pendente de reposição) |
Esta conta é semeada como pendente de reposição, pelo que iniciar sessão com test não lhe dá uma sessão - leva-o diretamente ao formulário de reposição de palavra-passe para escolher uma palavra-passe real. Isto é deliberado: o hash de arranque vem incluÃdo neste repositório e é público. Veja a checklist de produção.
O CBGenesis vem com diretrizes de IA, skills, e ficheiros de agente pré-configurados em .agents/, para que assistentes como o GitHub Copilot, o Cursor, e o Claude Code obtenham contexto preciso sobre ColdBox e BoxLang. São gerados pelo módulo coldbox-cli que instalou no passo de estruturação. Atualize-os depois de estruturar o projeto, para que as diretrizes e skills correspondam aos seus módulos instalados:
coldbox ai refresh
Execute coldbox ai refresh novamente sempre que instalar, atualizar, ou remover módulos do CommandBox, para que as diretrizes e skills especÃficas de cada módulo sejam recolhidas.
coldbox ai --help # Descubra os comandos de IA disponÃveis
coldbox ai info # Mostra as diretrizes, skills, agentes, e servidores MCP instalados
coldbox ai skills list # Lista as skills disponÃveis
coldbox ai agents --help # Adicione, atualize, ou remova ficheiros de configuração de agentes de IA
server start
Este é o comando de servidor da BoxLang CLI. A primeira execução instala os módulos BoxLang listados em server.json (bx-esapi, bx-password-encrypt, bx-mail, bx-orm, o driver JDBC selecionado por DB_DRIVER, e bx-image).
onServerInitialInstall só dispara no primeirÃssimo arranque de um servidor, pelo que alterar DB_DRIVER depois não reinstala o driver por si só. Execute server forget (que limpa o estado de instalação do servidor) antes de o iniciar novamente, para que o novo driver seja instalado:
server forget
server start
npm run dev
Abrir a aplicação
Visite http://127.0.0.1:8080 - vai aterrar na página de inÃcio de sessão. Inicie sessão com as credenciais de administrador semeadas acima.
AuthSplit predefinido.Depois de entrar, vai aterrar no dashboard, com a barra lateral de administração pronta para Utilizadores, Funções, Permissões, Registo de Auditoria, e Definições:
Veja como public/, app/, resources/, e lib/ se encaixam, e percorra o ciclo de vida do pedido.
Compreenda o fluxo de inÃcio de sessão e o modelo de permissões resource:action antes de adicionar a sua primeira página protegida.
Pronto para construir? Comece aqui para os passos exatos para adicionar um novo módulo CRUD.