Docs›Começando›Instalação
Começando

Instalação

Composer, dependências, primeira execução.

O MAD framework é um package Composer (mad/framework) que roda sobre Laravel. Setup é o de qualquer app Laravel — Composer, um .env, migrations — mais um wizard web opcional que cuida do banco e do administrador num clone fresco.

Stack mínima: PHP 8.3+ • Composer 2.x • Node.js 18+/npm (só se o projeto usa o shell padrão com Vite + Tailwind) • um banco relacional (SQLite por padrão; MySQL/MariaDB ou PostgreSQL suportados).

Requisitos do sistema

RequisitoVersãoObservação
PHP8.3+Versão exigida em composer.json ("php": "^8.3").
Composer2.xGerenciador de dependências PHP.
Extensões PHP—pdo, mbstring, openssl, json, tokenizer, ctype, fileinfo + um driver PDO (pdo_sqlite, pdo_mysql ou pdo_pgsql).
Node.js18+Só necessário se o projeto compila o shell padrão (Vite + Tailwind) em resources/css/resources/js.
BancoSQLite / MySQL 8+ / MariaDB / PostgreSQL 13+SQLite é o padrão de desenvolvimento — zero setup, um arquivo.

Duas formas de subir um projeto

Um clone fresco do template MAD pode ser preparado de duas formas — escolha conforme o cenário:

CaminhoQuando usar
Wizard web (/install)Deploy novo (staging/produção/demo) — configura banco, roda migrations/seed e cria o admin pelo navegador, sem SSH.
Setup manual via CLIDesenvolvimento local — você já sabe as credenciais do banco e quer rodar tudo num comando.

Wizard web (/install)

Depois de clonar e instalar as dependências básicas:

git clone <repo> meu-projeto
cd meu-projeto
composer install
cp .env.example .env
php artisan key:generate
php artisan serve            # http://127.0.0.1:8000

Abra http://127.0.0.1:8000/install. O wizard tem 3 passos:

  1. Requisitos — checa PHP, extensões, drivers PDO e permissões de escrita (informativo, não bloqueia).
  2. Banco de dados — escolha SQLite (padrão, caminho do arquivo) ou MySQL/PostgreSQL (host, porta, banco, usuário, senha — o banco já precisa existir). "Testar conexão" valida antes de seguir.
  3. Aplicação e administrador — nome/URL do app + nome/e-mail/senha do admin. "Instalar" grava o .env, roda migrate --force (cobre as 6 conexões lógicas do MAD numa passada) + db:seed --class=Database\Seeders\DatabaseSeeder (que dispara o MadReferenceSeeder — identidade/referência baseline — e, em apps gerados pelo MadBuilder, os seeders de permissão/papel), e cria o usuário admin.

O instalador é protegido por um token timing-safe (gerado em storage/app/install-token.txt, ou fixo via INSTALL_TOKEN no .env) — leia o arquivo no servidor e cole no gate. Depois de concluído, o instalador se fecha sozinho (fail-closed): qualquer acesso novo a /install redireciona pro login. 

cat storage/app/install-token.txt

Precisa reabrir o wizard pra testar de novo? php artisan mad:install-reset apaga o lock, o resumo durável, o token e os arquivos SQLite alvo, e imprime um token novo. Use --keep-db pra reabrir o gate preservando os dados. Só funciona com APP_ENV=local — em qualquer outro ambiente o comando falha sem apagar nada.

Referência completa do wizard (token timing-safe, picker de driver de banco com modo avançado por conexão, detecção fail-closed, mad:install-reset e o mapa de classes Mad\Install\**): Instalador web (/install).

Setup manual via CLI

Pra desenvolvimento local você já sabe as credenciais — pula o wizard e roda tudo direto. O atalho mais rápido é o alias do Composer: 

git clone <repo> meu-projeto
cd meu-projeto
composer setup

composer setup roda, em sequência: composer install, ativa os git hooks do projeto (composer mad:hooks), copia .env.example → .env (se ainda não existir), php artisan key:generate, php artisan migrate --force e o build do shell (npm install + npm run build). Equivalente, passo a passo: 

composer install

# Ativa os git hooks do projeto (guard de pre-push)
composer mad:hooks

cp .env.example .env
php artisan key:generate

# SQLite (padrão) — dois arquivos: as 6 conexões MAD usam app/database/mad.sqlite
# e a conexão default do Laravel usa database/database.sqlite.
mkdir -p app/database
touch app/database/mad.sqlite database/database.sqlite

php artisan migrate

npm install --ignore-scripts
npm run build

php artisan serve
# http://127.0.0.1:8000

Pra subir banco MySQL/PostgreSQL em vez de SQLite, configure DB_* no .env antes do migrate — ver a página de Configuração.

Rodar em desenvolvimento

Pra trabalhar com hot-reload do Vite + queue worker + log tailing junto com o servidor, use o script dev (roda os 4 processos em paralelo, encerra todos juntos com Ctrl+C): 

composer dev

Acessar

ÁreaURLDescrição
Admin/app/loginPainel principal (usuário criado no wizard ou via seeder).
Instalador/installWizard de setup — só responde antes da primeira instalação.
Documentação/docsEsta documentação (você está aqui).
REST API/api/*Endpoints JSON.

Comandos comuns

# Atualizar autoload após adicionar novas classes
composer dump-autoload

# Atualizar dependências
composer update

# Limpar caches de view/config/rota (após mudanças em Blade/config)
php artisan view:clear
php artisan config:clear
php artisan route:clear

# Recompilar e republicar os assets do framework (mad-*.js/css)
# — obrigatório depois de editar packages/mad-framework/assets/**
composer mad:sync

# Migrations
php artisan migrate
php artisan migrate:status
php artisan migrate:rollback

Troubleshooting

500 ao acessar a primeira vez. Verifique permissões em storage/ e bootstrap/cache/ (precisam ser graváveis pelo servidor web) e se o composer install rodou sem erros. Confira storage/logs/laravel.log.

/install retorna 403 ou redireciona pro login. A aplicação já foi instalada (existe storage/mad-installed.lock, ou o usuário admin já existe no banco). Em ambiente local, reabra com php artisan mad:install-reset.

"could not find driver" / conexão recusada no banco. Confira se a extensão PDO certa está habilitada (pdo_sqlite, pdo_mysql ou pdo_pgsql) e as credenciais em .env — host localhost às vezes precisa virar 127.0.0.1 dependendo do socket.

Próximos passos