Download the PHP package gsferro/starter-kit-easy without Composer

🇧🇷 Português · 🇺🇸 English

Starter kit Laravel 13 + Filament 5 pronto para uso. Um comando cria o projeto, instala tudo, migra, popula o banco e entrega três painéis funcionando: negócio, administração e infraestrutura.

Não há passo manual: o create-project já cria o .env, gera a APP_KEY, cria o banco, roda as migrations, semeia papéis/permissões/usuário, publica os assets do Filament e faz o build do front-end. Ao final ele imprime as URLs e o login inicial.

Antes de tocar no banco, ele pergunta cinco coisas — como o laravel new faz:

Enter em tudo instala exatamente como antes — nenhuma pergunta é obrigatória, e a primeira delas é "personalizar agora?", que pula todas de uma vez. Sem terminal (CI, Docker, --no-interaction) nada é perguntado. Ao final o instalador mostra o resumo do que mudou, o que continua sendo editado à mão, e oferece rodar os testes do kit.

No Windows as perguntas não aparecem, e isso não é bug do kit. Medido nos dois shells, PowerShell e Git Bash: o Composer nunca liga TTY em Windows — ProcessExecutor::runProcess() descarta o modo TTY quando Platform::isWindows(), porque o symfony/process lançaria TTY mode is not supported on Windows platform. O artisan recebe pipes, e o instalador se pula pelo próprio guarda de terminal, avisando na tela.

O que fazer, e a ordem importa:

Rode logo depois de instalar, com o banco ainda só com os dados de seed: aí o --force é inócuo. Mais tarde ele é destrutivo, porque apaga o SQLite antes de perguntar.

Se já tem dado no banco e quer só o nome e a cor:

As outras três perguntas não têm versão não destrutiva, e o comando explica por quê: banco e multi-organização exigem recriar (as tabelas de permissão só nascem com a coluna de contexto antes do migrate), e as credenciais do administrador não são sincronizadas pelo seeder — ele garante que exista um administrador, e não que ele espelhe o .env, porque roda em todo db:seed e sobrescrever ali reverteria a senha trocada à mão.

Para trocar e-mail ou senha do administrador, o caminho é deliberado:

Ele pede confirmação, nunca ecoa a senha, recusa e-mail que já pertence a outra conta e para se houver mais de um master_global — em vez de escolher um por ordenação. A tela de perfil do painel também serve.

Em Linux, macOS e WSL as perguntas aparecem no create-project e nada disso é necessário.

A multi-organização é o item que mais compensa decidir agora: ligada na instalação, ela custa zero; ligada depois, o kit:tenancy recria o banco (as tabelas de permissão só nascem com a coluna de contexto se a flag estiver ativa antes do migrate).

Prefere clonar? O mesmo instalador roda sozinho:

Acesso de demonstração

O seeder cria um usuário master que já entra nos três painéis:

Entre por /app, /admin ou /infra — a mesma sessão vale para os três, e o menu do usuário troca de painel.

⚠️ Troque a senha antes de expor o ambiente. Para nascer com outra credencial, defina KIT_ADMIN_EMAIL, KIT_ADMIN_PASSWORD e KIT_ADMIN_NAME no .env antes de rodar a instalação (os valores ficam em config/kit.php). Num projeto já instalado, troque pelo próprio painel em /admin/users ou em Meu perfil.

Para testar o recorte de acesso, crie um usuário só com o papel admin ou infra: ele entra no painel correspondente e toma 403 no outro.

Os três painéis

Quem entra vem do papel, não de uma lista no código. Cada papel declara em qual painel vale, na coluna roles.painel — é o campo Painel na tela /admin → Papéis. App\Models\User::canAccessPanel() compara essa coluna com o painel que está sendo aberto. Criar um papel e escolher o painel dele é o ato de dar acesso.

Nulo não é coringa: papel sem painel só carrega permissões e não abre painel algum. O papel master_global entra nos três de outro jeito — ele vence qualquer gate via Gate::before (App\Providers\KitServiceProvider), sem precisar de permissions no banco, e o canAccessPanel() o libera antes de olhar a coluna.

Nos painéis sem tenancy (/admin, /infra) o papel precisa estar atribuído no contexto global: ser admin dentro de uma organização não é credencial para administrar a instalação. No /app vale o papel em qualquer organização — qual delas você abre é decidido depois, por canAccessTenant().

O badge do menu do usuário mostra o papel da organização ABERTA. Quem pertence a mais de uma pode ter papéis diferentes em cada — panel_user numa, admin_app noutra —, e o badge acompanha a troca de organização. Sem papel na organização aberta, não há badge: entrar no painel não depende da organização (é o parágrafo acima), mas a exibição sim. Nos painéis sem tenancy nada muda, porque lá não há organização corrente.

Com o modo multi-tenant ligado, o App vira /app/{tenant} e passa a mostrar só os dados do tenant selecionado. Admin e Infra seguem globais.

Separar admin de infra é o ponto do kit: quem administra usuários não precisa (nem deve) enxergar logs, filas e comandos operacionais, e vice-versa.

Como cada um se parece

Login	Administração
Auth Designer em duas colunas — a arte mostra o nome da aplicação	Usuários, papéis, agentes de IA e indicadores de administração

Infraestrutura	Negócio
Saúde, filas, trilhas, comandos e custos de IA — agrupados em Observabilidade, IA, Trilhas e Sistema	Vazio de propósito: é onde o seu projeto nasce

Mais telas: saúde da aplicação · usuários · permissões (Shield) · catálogo de agentes de IA · central de comandos · busca ⌘K · acesso negado

Nossos números

Não é vitrine: é o inventário de tudo que já existe, e o que você não vai precisar escrever.

O /app é o menor de propósito — ele nasce vazio, porque é onde o seu projeto entra. Os outros dois já vêm completos.

O critério de cada linha, para que os números sejam auditáveis. Tela navegável é rota GET do painel com nome de rota, descontadas as de autenticação, os endpoints que devolvem JSON e os redirects. Páginas próprias é $painel->getPages(), sem exclusão. Rotas GET conta tudo sob o caminho do painel, inclusive autenticação e redirect. Widgets é $painel->getWidgets() — widget de painel; os 6 widgets de resource de Tenants/Widgets/ não entram, e por isso um ls dá um número maior. Medido com kit.tenancy.enabled = false; com tenancy ligada as rotas do /app ganham o prefixo da organização.

Até a v0.36.1 a linha Telas navegáveis não tinha critério declarado e não era falsificável — ela ficou parada em 12 / 28 / 27 desde 18/08/2026 e atravessou um fact-check inteiro sem ser corrigida, porque não havia como conferi-la. Agora as cinco linhas são travadas por tests/Kit/SiteDeDocumentacaoTest.php.

O detalhamento saiu daqui e está no site: Referência e Começar.

O que já vem pronto

Porta de entrada

• Página de boas-vindas na rota /, no lugar da welcome padrão do Laravel: um cartão por painel e as informações do que o kit:install personalizou (detalhes)

Administração e segurança

• Shield (papéis e permissões com UI) sobre spatie/laravel-permission
• Breezy: perfil do usuário, avatar, 2FA e passkeys
• Ficha de usuário em tela cheia (/admin/users/{id} e /app/users/{id}): conta, situação, origem e datas, com o botão de editar no topo. Só no /admin ela lista as organizações e os papéis da pessoa — no /app a omissão é a feature: contá-los ali diria a quem administra uma organização que aquela conta também é de outra (detalhes)
• Avatar desenhado aqui dentro: sem foto, o provider padrão do Filament manda o navegador de cada pessoa pedir ui-avatars.com em toda tela — com as iniciais na query string e o Referer do painel junto. App\Support\AvatarDeIniciais devolve um SVG embutido nos três painéis: mesma aparência, nenhuma requisição externa
• Auth Designer: tela de login em duas colunas — a arte mostra o nome da aplicação, lido de APP_NAME a cada carregamento; para usar a sua imagem, envie em /admin/configuracoes-da-aplicacao
• Registro aberto opcional (desligado por default): cadastro sem convite no /app, com papel único, aprovação manual e validação de e-mail — cada um em sua chave (detalhes)
• Lockscreen: bloqueio de sessão por inatividade (30 min), registrado nos 3 painéis — a tela de bloqueio usa o mesmo layout do login (Auth Designer), não o layout simples do Filament
• Impersonate, log de autenticação, auditoria de alterações (owen-it)
• Panel Switch: troca de painel pelo menu do usuário
• DTO com spatie/laravel-data: todo dado estruturado que cruza fronteira de classe é objeto tipado, com guarda automático — credencial não entra em DTO, e consumo/resposta de API exige um (detalhes)
• Proteção anti-robô opcional (desligada por default): reCAPTCHA v2/v3, Turnstile ou hCaptcha nas telas de login, recuperação de senha e registro, via ddr/filament-captcha (detalhes)
• Página única de login (desligada por default): KIT_LOGIN_UNIFICADO=true leva /admin/login, /infra/login e /app/login a /login; quem acessa um painel entra direto, quem acessa mais de um escolhe numa tela de cartões depois de entrar. Atenção: SSO externo (SAML/OIDC corporativo) ainda não é pré-configurado e não passa por essa regra — ver a página de docs
• Login social por painel: cada provedor pode ser liberado separadamente em /app, /admin e /infra; botão, rota e destino respeitam o painel de origem

Observabilidade e manutenção (painel infra)

• Spatie Health com checks de banco, cache, filas, agendador, disco (exceto no Windows), debug mode, ambiente, app otimizado e IA local
• Backup Monitor (spatie/laravel-backup), Jobs Monitor, Logs Explorer (sem botão de apagar — trilha é evidência)
• Exceções agrupadas por tipo e frequência — o que Health, Pulse e arquivo de log não respondem
• Trilha de e-mails enviados: separa "não foi enviado" de "foi enviado e caiu no spam"
• Lixeira: restaura o que foi apagado com SoftDeletes (detalhes)
• Command Center: comandos Artisan pré-aprovados pela UI, com histórico
• Laravel Pulse embutido como página do painel
• Dependency Graph: mapa de models, relações, resources e painéis
• Release Notifier: avisa quando há versão nova dos pacotes Composer

IA (opcional, local por padrão)

• laravel/ai com catálogo de agentes no banco: system prompt, provider, modelo, tools e guardrails são dados, editáveis no /admin sem deploy
• Guardrails encadeados: budget, prompt injection, classificador local, redação de PII e filtro de saída sensível
• Ledger de execuções (ai_runs) com custo e tokens no painel infra
• Widget de chat com streaming
• Inferência 100% local via llama.cpp (docker compose --profile ai up -d) ou qualquer provider SaaS trocando AI_PROVIDER

Produtividade

• Busca ⌘K no lugar do campo nativo da topbar: encontra registros, telas, páginas e ações de criação — tudo recortado por permissão (detalhes abaixo)
• Badges de contagem animados no menu, centro de notificações com abas, indicador de ambiente
• Dashboards já preenchidos nos painéis admin e infra: 29 widgets (stat cards com contador animado, funis, metas, breakdowns, timelines) sobre os dados que os painéis já têm — incluindo logins de hoje com histórico de sete dias e, com tenancy, insights e acessos das organizações
• Páginas de erro brandadas (Sentinel) em pt-BR — a de 403 só mostra o diagnóstico de permissão fora de produção
• UI 100% em pt-BR, inclusive nos plugins que só trazem inglês (traduções em lang/vendor/)
• Seletor de idioma nos três painéis e nas telas de login — dirigido por dado, não por flag (detalhes abaixo)
• Camada de mídia (spatie/laravel-medialibrary) nos componentes do Filament: upload, coleções e conversões em formulário, tabela e infolist (detalhes)
• Cabeçalho rico no topo das telas de ver e editar usuário e organização: avatar (ou as iniciais), nome, badge de situação e metadados copiáveis, no lugar do título de texto do Filament
• Aviso de alterações não salvas ao sair de um formulário nos três painéis, e a versão do seu sistema no rodapé — os dois são interruptor em /admin/configuracoes-da-aplicacao, sem deploy (detalhes)
• Densidade do layout em três níveis, na mesma tela de configurações: confortável (o padrão do Filament), compacto e denso. Aperta de uma vez os cartões de estatística, as tabelas, o menu lateral e os botões dos três painéis, e vale no próximo F5 — sem tema Vite, sem npm run build, sem deploy. Medido no próprio kit: a linha da tabela cai −17,1% no compacto e −23,4% no denso (detalhes)
• Link de acesso direto ao painel de cada organização (com multi-tenancy) nas três telas do /admin — listagem, ficha e edição. Na listagem é uma coluna com o endereço visível, abrindo em nova aba: o destino é conhecido antes do clique (detalhes)

A densidade do layout, na mesma tela

Confortável (padrão)	Compacto	Denso

Repare na coluna de ações: no confortável ela é cortada em "Edi…"; no denso cabe inteira. Apertar não é só ganhar altura — é deixar de esconder conteúdo.

Documentação completa

O que antes vivia aqui — e eram mais de duas mil linhas — agora tem site próprio, com busca e navegação: https://gsferro.github.io/filament-starter-kit-easy/pt/

A versão em inglês fica em https://gsferro.github.io/filament-starter-kit-easy/en/.

Futuras melhorias

O roadmap do kit registra o que já foi olhado e decidiu-se adiar, com o motivo e, quando houve, a medição que sustentou a decisão: preferências de aparência por usuário, o tema compacto pago da Filament, e o gatilho que aposenta a implementação atual de densidade.

Ele vem junto com o seu projeto de propósito — é o futuro do kit, não o do seu projeto, e serve para você não gastar uma tarde reavaliando do zero algo que já tem número registrado.

Requisitos

• PHP 8.4+ e Composer 2
• Node 20+ (opcional — sem ele a instalação segue e avisa como fazer o build depois)
• Docker (opcional — só para Postgres/MySQL, Redis, IA local e e-mail)

Banco de dados

A instalação pergunta — SQLite, PostgreSQL ou MySQL. O padrão é SQLite, para não depender de nada.

PostgreSQL é o recomendado, e por um motivo funcional: ele é o único que traz pgvector, de que dependem as funções de IA local que usam busca semântica (embeddings). Com SQLite ou MySQL o resto do kit roda igual — só essas funções ficam indisponíveis.

Postgres e MySQL têm container no kit — o MySQL em profile próprio, porque a instalação escolhe um banco só. Os comandos estão na seção Docker.

Escolhendo Postgres na instalação, o .env já sai com o bloco que o docker-compose.yml lê, e falta só subir o container. Se ele não estiver de pé na hora da instalação, o kit avisa, pula as migrations e diz o comando para refazer:

Para trocar depois da instalação, suba os containers e copie as variáveis:

Docker

Tudo é opt-in por profile. Um container por feature:

O Reverb usa 8090 e não o default 8080 para não colidir com o llama.cpp.

Nenhum serviço tem container_name fixo: o prefixo vem de COMPOSE_PROJECT_NAME, que o kit:install grava com o nome do seu projeto. Detalhes no site.

Endereço local por nome, em vez de IP e porta

Dá para abrir o projeto em http://meu-projeto.test no lugar de http://127.0.0.1:8000: custa uma linha no arquivo hosts da máquina e duas chaves no .env. Nenhum arquivo versionado muda, a adoção é individual e quem não fizer nada continua em http://localhost:8000. Receita completa, com a armadilha de elevação no Windows.

O kit:install oferece fazer isso no fim da instalação: ele sugere o domínio a partir do nome que você escolheu, escreve a linha no hosts (pedindo elevação no Windows) e ajusta a APP_URL. É opt-in, não depende de flag nenhuma, e recusar deixa tudo como sempre foi. Domínio fora dos sufixos reservados ao uso local (.test, .localhost, .example, .invalid) pede um sim a mais, porque apontar um domínio real para 127.0.0.1 derruba o acesso ao site de verdade nesta máquina.

Atualizando a stack na máquina que a hospeda

./deploy_docker_local.sh roda no host dos containers (não na máquina de desenvolvimento) e faz a sequência inteira: git pull, rebuild da imagem, --profile app up -d, migrations, optimize:clear, health check em /up e sonda TCP do Reverb. A saída fica em storage/logs/deploy_docker_local.log.

O rebuild vem depois do pull porque a imagem é self-contained (o código é assado nela) — rebuild antes reassa o código velho. E como ele recria reverb e pulse, que estão no mesmo profile app, não há comando de restart à parte: processo long-running não vê código novo sem reiniciar.

--recreate acrescenta --force-recreate, e é necessário quando o .env mudou: o Compose lê o env_file na criação do container, então um container já existente mantém os valores antigos. Se o .env.example mudou no pull, o script avisa.

Comandos

Personalize seu projeto

Os cinco primeiros o instalador já pergunta — a lista abaixo é para mudar depois, ou para quem pulou as perguntas.

Os onze últimos não entram nas perguntas porque são código ou dado de tela, não um valor que caiba num prompt de terminal. O instalador os lista no resumo final, com o arquivo de cada um.

⚠️ O item 5 é o único que não é "edite um arquivo" depois de instalado: o kit:tenancy roda migrate:fresh --seed e apaga os dados. Ele exige árvore git limpa e confirmação explícita. Respondido na instalação, ele não apaga nada — o banco ainda nem existe, e é essa a hora certa de decidir.

A cor primária vale para os três painéis. Com o modo multi-tenant ligado, a cor de cada organização vence esta dentro de /app/{slug} — o /admin e o /infra continuam com a do projeto. Para uma paleta completa, e não só a primary, o caminho continua sendo ->colors([...]) em cada app/Providers/Filament/*PanelProvider.php.

Atualizando um projeto que já nasceu do kit

O kit é um ponto de partida, não uma dependência. Depois do create-project o projeto é seu: você renomeia painéis, muda canAccessPanel(), edita seeders. Por isso não existe um kit:update que sobrescreve arquivos — ele reescreveria justamente o que você personalizou, e um starter kit que estraga o projeto do usuário não serve para nada.

O que muda separa-se em três camadas, e cada uma tem um caminho próprio:

Solução de problemas

• 403 em todos os painéis, logo depois de autenticar — o usuário não tem papel nenhum, ou o papel dele está sem painel declarado (roles.painel vazio não é coringa: não abre nada). Dê o papel em /admin → Usuários, ou preencha o campo Painel em /admin → Papéis.
• /infra ou /admin dando 403 — seu usuário precisa de um papel cujo painel seja esse (master_global, admin ou infra), e com a tenancy ligada o papel tem de estar atribuído no contexto global. A tela de 403 mostra qual permissão faltou, mas só fora de produção: em produção ela não revela papéis nem permissões.
• Assets do Filament sumidos — php artisan filament:assets.
• Pulse sem dados — falta o daemon: php artisan pulse:check (ou o serviço pulse do compose).
• Sininho não atualiza em tempo real — BROADCAST_CONNECTION=reverb exige o processo Reverb no ar; sem ele o kit cai para polling de 30s.
• Assistente de IA indisponível — suba docker compose --profile ai up -d (o primeiro boot baixa ~4,5 GB de modelo) ou troque AI_PROVIDER para um provider SaaS com API key.

Licença

MIT.