Frameworks — zeltro new

zeltro new <framework> <name> cria a estrutura de um projeto do zero que você escreve. Os dois argumentos são posicionais e obrigatórios.

zeltro new laravel my-shop
zeltro new flask my-api --database sqlite
zeltro new express my-service --database postgres --version latest

Para apps prontos de terceiros que você roda em vez de escrever, veja a Biblioteca de apps.

Frameworks suportados#

Cada runtime é uma das imagens base do Zeltro: canebaycomputers/cbc:nginx-php8 (PHP 8.3 atrás do nginx e do php-fpm), canebaycomputers/cbc:nginx-python3 (Python 3.12; seu app escuta na porta 8000 e o nginx faz o proxy) ou canebaycomputers/cbc:nginx-node (Node 22; seu app escuta na porta 3000 e o nginx faz o proxy). Todo projeto responde na porta 80.

Se você pedir um banco de dados que o framework não consegue usar, o Zeltro avisa e troca por um que ele consiga. O WordPress é só MySQL, e Laravel, Kavera, October CMS, Drupal e Django não recebem MongoDB.

Frameworks de front-end#

nextjs, nuxt, sveltekit, astro, react e vue são criados como servidores de desenvolvimento rodando com hot reload, com proxy pelo nginx na porta 80. Edite um arquivo e a página se atualiza — sem etapa de build, sem porta para lembrar.

Eles usam SQLite por padrão, ao contrário de todos os outros frameworks daqui, porque um projeto de front-end não deve iniciar um servidor de banco de dados que nunca consulta. Peça um explicitamente quando precisar:

zeltro new nextjs my-app --database postgres

react e vue são single-page apps simples no Vite, sem renderização no servidor. hono é um framework de API, não de interface, e só está agrupado com eles porque usa a mesma imagem base do Node.

Kavera#

O Kavera é um framework de sites nativo do Laravel: páginas Blade em arquivos simples, mais conteúdo dinâmico vindo de serviços (posts do Blogger, eventos do Eventbrite, galerias do Flickr, webhooks de formulários) em cache no Redis. Os formulários já vêm com e-mail, webhooks, controle de spam e reCAPTCHA; as páginas trazem títulos de SEO e JSON-LD opcional.

Ele existe porque um agente editando arquivos de página funciona melhor que um agente operando o painel administrativo de um CMS. Prefira-o ao Laravel puro para sites de marketing, sites institucionais, portfólios e galerias — e o Laravel puro quando você precisar de uma aplicação de verdade, com models personalizados e regras de negócio.

zeltro new kavera my-site

As páginas ficam em resources/views/content. Depois de adicionar ou remover uma, atualize o registro para que as rotas sejam resolvidas:

zeltro art app:update-content-list

October CMS e Drupal#

Os dois são CMSs com painel administrativo, instalados a partir do código-fonte para usarem os bancos de dados compartilhados do Zeltro.

• October CMS (zeltro new octobercms my-site) é baseado no Laravel. Temas e plugins ficam no projeto, então um agente pode editá-los. O painel administrativo fica em /admin (o BACKEND_URI no .env); crie o usuário administrador com zeltro art october:passwd <email> <password>. Ele é gratuito para desenvolvimento local, mas o uso em produção exige uma licença de octobercms.com.
• Drupal (zeltro new drupal my-site) instala o Drupal 11 com o Composer e depois roda drush site:install. O docroot é public/ em vez do web/ habitual do Drupal. É o framework mais lento para criar, então conte com vários minutos. Rode o Drush com zeltro drush <args>.

Opções#

Bancos de dados#

SQLite#

zeltro new flask notes --database sqlite
zeltro new django blog --database sqlite
zeltro new laravel shop --database sqlite

O SQLite não precisa de serviço compartilhado — é um único arquivo. O Zeltro cria o arquivo, aponta o .env do projeto para ele e roda as migrations normalmente.

O arquivo sempre fica dentro do diretório do projeto:

Esse local é proposital. O diretório do projeto é o único caminho montado (bind mount) no contêiner, então um banco de dados em qualquer outro lugar seria destruído toda vez que o contêiner fosse recriado no zeltro up. Ele também fica no gitignore por padrão.

Bom para protótipos, ferramentas de um usuário só e fixtures de teste. Para qualquer coisa com acesso concorrente, use Postgres ou MySQL.

Bancos de dados em servidor compartilhado#

mysql, postgres e mongodb se conectam aos contêineres dos serviços compartilhados. O Zeltro cria o banco de dados e escreve as configurações de conexão no .env do projeto — você nunca configura credenciais à mão. Veja Arquitetura → Serviços compartilhados para nomes de host e credenciais.

Trabalhando dentro de um projeto#

Rode estes comandos a partir do diretório do projeto. Eles são executados dentro do contêiner, com o runtime correto.

PHP#

zeltro composer install
zeltro art migrate
zeltro wp plugin list --status=active
zeltro drush status
zeltro php script.php
zeltro tinker

Python#

zeltro python -c "import sys; print(sys.version)"
zeltro pip install httpx
zeltro django manage migrate
zeltro django manage createsuperuser
zeltro shell

Os contêineres Python oferecem python3, não python.

Node#

zeltro npm install
zeltro npx tsc --init
zeltro node script.js
zeltro shell

Qualquer framework#

zeltro exec <cmd>              # run a command, no TTY — good for scripts and CI
zeltro exec-root <cmd>         # as root
zeltro bash                    # interactive shell
zeltro shell                   # framework-aware REPL (tinker / django shell / node / python3; bash otherwise)
zeltro supervisor restart all  # restart in-container processes
zeltro supervisor-status

Use zeltro supervisor, nunca zeltro exec supervisorctl — este último roda como o usuário developer e tem o acesso ao socket do supervisor negado.

Extras do Laravel#

zeltro db-refresh      # fresh migration + seed
zeltro cache-refresh   # clear all caches
zeltro phpcs app/      # static analysis
zeltro phpcbf app/     # auto-fix
zeltro phpmd app/File.php
zeltro php -l app/File.php

Adotando um projeto existente#

zeltro setup my-project                          # a folder already in ~/zeltro-projects/
zeltro setup my-project --framework django       # force detection
zeltro setup my-project --overwrite-env          # repoint an existing .env at shared services
zeltro setup my-project --no-startup             # register without starting, to review the compose

A detecção do framework lê os arquivos do projeto: artisan, manage.py, main.py, app.py, package.json, wp-config.php e um composer.json que exija drupal/core. Um main.py ou app.py que importa o Flask é Flask; qualquer outro main.py é tratado como FastAPI. Em projetos Node, as dependências no package.json decidem entre Next.js, Nuxt, SvelteKit, Astro, Hono, Fastify, Express, NestJS, React, Vue e Node puro.

Achou um erro nesta tradução? Avise a gente no GitHub.