Frameworks: `zeltro new`

zeltro new <framework> <name> crea la base de un proyecto nuevo, desde cero, que escribes tú. Los dos argumentos posicionales son obligatorios.

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

Para apps de terceros ya hechas, que ejecutas en lugar de escribir, consulta la Biblioteca de apps.

Frameworks compatibles#

Framework	Imagen de ejecución	Base de datos predeterminada
`laravel`	PHP 8.3	MySQL
`kavera`	PHP 8.3	MySQL
`octobercms`	PHP 8.3	MySQL
`drupal`	PHP 8.3	MySQL
`wordpress`	PHP 8.3	MySQL
`php`	PHP 8.3	MySQL
`fastapi`	Python 3.12	PostgreSQL
`flask`	Python 3.12	PostgreSQL
`django`	Python 3.12	PostgreSQL
`python`	Python 3.12	PostgreSQL
`express`	Node 22	MySQL
`nestjs`	Node 22	MySQL
`fastify`	Node 22	MySQL
`node`	Node 22	MySQL
`nextjs`	Node 22	SQLite
`nuxt`	Node 22	SQLite
`sveltekit`	Node 22	SQLite
`astro`	Node 22	SQLite
`hono`	Node 22	SQLite
`react`	Node 22	SQLite
`vue`	Node 22	SQLite

Cada entorno de ejecución es una de las imágenes base de Zeltro: canebaycomputers/cbc:nginx-php8 (PHP 8.3 detrás de nginx y php-fpm), canebaycomputers/cbc:nginx-python3 (Python 3.12; tu app escucha en el puerto 8000 y nginx hace de proxy) o canebaycomputers/cbc:nginx-node (Node 22; tu app escucha en el puerto 3000 y nginx hace de proxy). Todos los proyectos responden en el puerto 80.

Si pides una base de datos que el framework no puede usar, Zeltro te avisa y cambia a una que sí pueda. WordPress solo usa MySQL, y Laravel, Kavera, October CMS, Drupal y Django no admiten MongoDB.

Frameworks de front-end#

nextjs, nuxt, sveltekit, astro, react y vue se crean como servidores de desarrollo en marcha con recarga en caliente, detrás de nginx en el puerto 80. Editas un archivo y la página se actualiza: sin paso de compilación y sin ningún puerto que recordar.

A diferencia de todos los demás frameworks de esta lista, usan SQLite de forma predeterminada, porque un proyecto de front-end no debería arrancar un servidor de base de datos que nunca consulta. Pide una explícitamente cuando la necesites:

zeltro new nextjs my-app --database postgres

react y vue son aplicaciones de una sola página sobre Vite, sin renderizado en el servidor. hono es un framework para APIs, no de interfaz, y está en este grupo solo porque comparte la misma imagen base de Node.

La recarga en caliente ya viene configurada. El puerto propio del servidor de desarrollo nunca se publica. El navegador llega a la app por el puerto 80 a través de nginx, así que los proyectos basados en Vite (nuxt, sveltekit, astro, react, vue) fijan el socket de HMR al puerto 80 en su configuración (server.ws.clientPort, que Vite 8.1 renombró desde server.hmr.clientPort). Si lo cambias, la recarga en caliente deja de conectarse aunque la página siga cargando, y es un fallo difícil de entender. nextjs no necesita ningún ajuste de puerto, porque su servidor de desarrollo se conecta de vuelta por la misma dirección que la página. Eso sí, Next.js 16 rechaza las conexiones de recarga en caliente desde hosts que no conoce, así que el next.config.mjs de la plantilla incluye los rangos IPv4 privados en allowedDevOrigins. Agrega cualquier otro nombre de host con el que abras el proyecto.

Kavera#

Kavera es un framework de sitios web nativo de Laravel: páginas Blade en archivos planos más contenido dinámico procedente de servicios (entradas de Blogger, eventos de Eventbrite, galerías de Flickr, webhooks de formularios), guardado en caché mediante Redis. Los formularios incluyen correo, webhooks, control de spam y reCAPTCHA; las páginas llevan títulos SEO y JSON-LD opcional.

Existe porque un agente que edita archivos de páginas rinde más que un agente que maneja el panel de administración de un CMS. Elígelo antes que Laravel a secas para sitios de marketing, sitios corporativos, portafolios y galerías, y elige Laravel a secas cuando necesites una aplicación de verdad con modelos propios y lógica de negocio.

zeltro new kavera my-site

Las páginas están en resources/views/content. Después de agregar o quitar una, actualiza el registro para que las rutas se resuelvan:

zeltro art app:update-content-list

October CMS y Drupal#

Los dos son CMS con panel de administración, instalados desde el código fuente para que usen las bases de datos compartidas de Zeltro.

October CMS (zeltro new octobercms my-site) está basado en Laravel. Los temas y plugins viven en el proyecto, así que un agente puede editarlos. El panel de administración está en /admin (el BACKEND_URI de .env); crea el usuario administrador con zeltro art october:passwd <email> <password>. Es gratis para desarrollo local, pero usarlo en producción requiere una licencia de octobercms.com.
Drupal (zeltro new drupal my-site) instala Drupal 11 con Composer y luego ejecuta drush site:install. La raíz de documentos es public/ en lugar del habitual web/ de Drupal. Es el framework que más tarda en crearse, así que cuenta con varios minutos. Ejecuta Drush con zeltro drush <args>.

Opciones#

Opción	Descripción	Valores
`--database <type>`	Motor de base de datos	`auto` (predeterminado: consulta la tabla de arriba), `mysql`, `postgres`, `mongodb`, `sqlite`
`--db-name <name>`	Nombre de la base de datos	Predeterminado: el nombre del proyecto, con guiones → guiones bajos
`--version <ver>`	Versión del framework	Solo Laravel y WordPress: `latest` (predeterminado) o un número de versión. Los demás frameworks la ignoran
`--image <ref>`	Reemplaza la imagen de Docker	Predeterminado: la imagen base del framework
`--no-migration`	Omite las migraciones	Las migraciones se ejecutan de forma predeterminada
`--one-off`	Omite la entrega a la IA tras la creación
`--github`	Crea un repositorio de GitHub en tu cuenta	Requiere autenticación con `gh`
`--github-org <org>`	Crea el repositorio en una organización
`--public` / `--private`	Visibilidad del repositorio	Privado de forma predeterminada
`--no-storage-symlink`	Omite el enlace simbólico `public/storage`	Solo Laravel

Bases de datos#

SQLite#

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

SQLite no necesita ningún servicio compartido: es un único archivo. Zeltro lo crea, apunta el .env del proyecto hacia él y ejecuta las migraciones con normalidad.

El archivo siempre vive dentro del directorio del proyecto:

Framework	Ruta
Django	`db.sqlite3`
Laravel, Kavera, October CMS	`database/database.sqlite`
Drupal	`public/sites/default/files/.ht.sqlite`
Todos los demás	`database.sqlite`

Esa ubicación es intencionada. El directorio del proyecto es la única ruta montada dentro del contenedor, así que una base de datos en cualquier otro sitio se perdería cada vez que el contenedor se recrea con zeltro up. Además, está en el gitignore de forma predeterminada.

Va bien para prototipos, herramientas de un solo usuario y datos de prueba. Para cualquier cosa con acceso concurrente, usa Postgres o MySQL.

Bases de datos en servidores compartidos#

mysql, postgres y mongodb se conectan a los contenedores de los servicios compartidos. Zeltro crea la base de datos y escribe los datos de conexión en el .env del proyecto: nunca configuras credenciales a mano. Consulta Arquitectura → Servicios compartidos para ver los nombres de host y las credenciales.

Trabajar dentro de un proyecto#

Ejecuta estos comandos desde el directorio del proyecto. Se ejecutan dentro del contenedor, con el entorno de ejecución correcto.

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

Los contenedores de Python incluyen python3, no python.

Node#

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

Cualquier 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

Usa zeltro supervisor, nunca zeltro exec supervisorctl: este último se ejecuta como el usuario developer y se le deniega el acceso al socket de supervisor.

Extras de 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

Adoptar un proyecto 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

La detección del framework lee los archivos del proyecto: artisan, manage.py, main.py, app.py, package.json, wp-config.php y un composer.json que requiera drupal/core. Un main.py o app.py que importa Flask se toma como Flask; cualquier otro main.py se trata como FastAPI. En los proyectos Node, las dependencias de package.json deciden entre Next.js, Nuxt, SvelteKit, Astro, Hono, Fastify, Express, NestJS, React, Vue y Node a secas.

¿Encontraste un error en esta traducción? Avísanos en GitHub.