Administra Laravel aplicaciones con cipi.yml

Por Andrea Pollastri · Última actualización: 7 de septiembre de 2026 · lectura gratuita, sin muro de pago

El estado que una aplicación espera en el servidor (alias, PHP, trabajadores, salud, copias de seguridad) generalmente reside en un panel o en la cabeza de alguien. Desde Cipi 5.1 puede vivir en un cipi.yml en la raíz del repositorio, revisado en la misma solicitud de extracción que el código que depende de él. Esta guía es el circuito práctico: genere, planifique, aplique y luego opte por participar para que cada implementación se concilie.

Por qué el archivo pertenece al lado del código

Una versión que agrega un trabajo en cola sin un trabajador se envía a medias. Un retroceso que deja la semana pasada upload_max_filesizeestá medio revertido. El estado del servidor generalmente reside en otro lugar: un panel, una página wiki o la memoria de quien configuró el cuadro.

A cipi.yml commit junto a la aplicación Laravel hace que ese estado sea parte de la misma solicitud de extracción que el código que depende de él. El archivo es declarativo: describe el estado final, no los pasos. Cipi lee lo que tiene el servidor, lo compara con el archivo y te muestra la diferencia antes de tocar nada.

Comience desde el servidor en vivo

No es necesario escribir el archivo a mano. En un cuadro Cipi 5.1+, imprima la configuración actual de la aplicación (alias, versión PHP y configuraciones por aplicación, bases de datos adicionales, trabajadores en cola leídos de Supervisor, Horizon, Reverb, el programador y los perfiles de respaldo que posee la aplicación) como un archivo listo para confirmar:

$ cipi yml generate myapp > cipi.yml
$ cipi yml plan myapp                  # reports nothing to do

Confirme ese archivo en la raíz del repositorio. Cipi lo busca en current/cipi.yml, entonces current/cipi.yaml, entonces shared/cipi.yml — anular con --file=<path> si lo guardas en otro lugar.

¿Prefieres una plantilla en blanco y completamente comentada? cipi yml example myapp imprime uno con bases de datos de marcador de posición y perfiles que ya están dentro del espacio de nombres de esa aplicación, por lo que la plantilla se valida tal como está.

Los comandos que usarás

$ cipi yml generate myapp
$ cipi yml example myapp
$ cipi yml validate myapp
$ cipi yml plan myapp
$ cipi yml apply myapp [--yes]
$ cipi yml auto myapp on|off|status

Que puedes declarar

Siete áreas. No es necesario que los declare todos; solo se concilian las secciones que escriba.

• Alias — la lista declarada sustituye a la actual. Un alias que elimine del archivo se elimina de Nginx. Comodines como*.myapp.com son aceptados. El dominio principal nunca se administra aquí.
• PHP y php.ini — fije la aplicación a PHP 8.3, 8.4 u 8.5 (ya instalada en el servidor) y configure anulaciones por aplicación: upload_max_filesize, post_max_size, memory_limit y el resto. Los valores de todo el servidor se mantienen cipi ini set.
• Bases de datos adicionales — más allá del creado con la aplicación, en MariaDB o PostgreSQL. Las credenciales aterrizan en shared/cipi-databases.env y nunca se vuelven a escribir en el repositorio. Las bases de datos se crean, nunca se eliminan.
• Trabajadores de cola y Horizon — declara cada cola con el recuento de procesos, los intentos y el tiempo de espera, y Supervisor se concilia para que coincida. O establecer horizon: true y dejar que Horizon sea dueño de las colas. desde 5.1.2, horizon: false en realidad se lee - previamentefalse Fue tratado como una llave perdida.
• Laravel Reverb — desde 5.1.2, reverb: true le da a la aplicación un puerto de host local, un programa Supervisor, un proxy nginx para /app/{key} y /apps/{id}/… en su propio dominio, y generado REVERB_* credenciales. Solo Laravel aplicaciones. Una aplicación que ya posee. /app o /apps No puedo compartir ese dominio con Reverb.
• Programador - un giro booleano * * * * * artisan schedule:run encendido o apagado. No hay edición de crontab en el siguiente servidor.
• control de salud — una sonda HTTP en uno de los propios dominios de la aplicación, verificada cada cinco minutos y nuevamente inmediatamente después de cada implementación. Opcionalmente, revierte automáticamente una versión defectuosa: solo el enlace simbólico del código; las migraciones no se deshacen.
• Perfiles de respaldo – perfiles por aplicación con su propio alcance, programación, retención, destinos y cifrado. Los nombres deben ser myapp o myapp-*.

un archivo completo

Esto es lo que normalmente incluye una aplicación de producción. Puedes generar la mayor parte; los comentarios son para la solicitud de extracción.

version: 1

app:
  php: "8.5"
  aliases:
    - "www.myapp.com"
    - "*.myapp.com"
  ini:
    upload_max_filesize: 50M
    post_max_size: 60M
    memory_limit: 512M

databases:
  - name: myapp_reporting
  - name: myapp_analytics
    engine: pgsql

workers:
  horizon: false
  reverb: false
  queues:
    - queue: default
      processes: 2
    - queue: emails
      processes: 1
      tries: 5
      timeout: 300

schedule: true

health:
  url: "https://myapp.com/up"
  expect: 200

backup:
  profiles:
    - name: myapp-db
      scope: db
      databases: ["myapp", "myapp_*"]
      exclude_tables: ["*.jobs", "*.telescope_*"]
      every: 30m
      keep: 48
      destinations: [local]
    - name: myapp-nightly
      scope: all
      cron: "0 2 * * *"
      keep_days: 14
      destinations: [s3]
      encrypt: true

Planifique y luego aplique

Nada cambia hasta que miras la diferencia. cipi yml plan myapp enumera todos los alias, trabajadores, bases de datos, configuraciones y perfiles que se agregarían, cambiarían o eliminarían. Léelo de la misma manera que lees una solicitud de extracción.

$ cipi yml validate myapp
$ cipi yml plan myapp
$ cipi yml apply myapp                 # asks for confirmation
$ cipi yml apply myapp --yes           # scripts and CI

Un archivo que no pasa la validación se rechaza en su totalidad y nunca aplicado parcialmente. Esa es la misma ruta cerrada por falla que usa una implementación cuando yml auto está en: correo electrónico yml_fail, no hay medio estado en la caja.

Una semana de cambios reales

Trate el archivo como código de aplicación. Cada uno de estos es un compromiso de una línea (o de un bloque), revisado y luego aplicado, o aplicado automáticamente después del lanzamiento si yml auto ya está encendido.

• Lunes: alias. Añadir www.myapp.com y *.myapp.com para subdominios multiinquilino. Recuerde: la lista tiene autoridad. Al eliminar un alias del archivo, se elimina de Nginx.
• Martes — php.ini. Un formulario comienza a aceptar cargas de 40 MB. golpe upload_max_filesize y post_max_size en app.ini. Los valores predeterminados de todo el servidor permanecen con cipi ini set.
• Miércoles: una nueva cola. El comunicado añade un emails cola. Agregue el trabajador con processes, tries y timeout. Supervisor coincide con el archivo. Si cambia la aplicación a Horizon, configure horizon: true y suelte la lista de cola.
• Jueves: una base de datos adicional. Los informes necesitan su propio MariaDB (o engine: pgsql). Nómbralo myapp_reporting. Las credenciales aparecen en /home/myapp/shared/cipi-databases.env- nunca en Git. Cipi crea bases de datos; no los eliminará si elimina la entrada más tarde.
• Viernes: salud y copias de seguridad. Punto health.url en https://myapp.com/up (debe ser uno de los dominios propios de la aplicación). Añadir un barato myapp-db perfil cada 30 minutos y una copia nocturna cifrada a S3.

Inscríbase después de cada implementación

Las implementaciones ignoran el archivo hasta que usted indique lo contrario. Esto es deliberado: un primer compromiso decipi.ymlNo debería sorprender a la producción.

$ cipi yml auto myapp on       # reconcile after every successful deploy
$ cipi yml auto myapp status
$ cipi yml auto myapp off      # back to manual apply

Con la aceptación otorgada, cada exitoso implementar conciliaciones - de ambos cipi deploy y el Git webhook. Un lanzamiento que no lleva cipi.yml es una operación silenciosa y no operativa. Un archivo que no pasa la validación se informa por correo electrónico (yml_fail) y nunca se aplicó hasta la mitad. Una reconciliación exitosa enciende yml_apply.

Lo que el archivo no tocará

• Sólo puede configuraruna aplicación que ya existe: nunca cree, cambie el nombre ni elimine una.
• Las secciones que omitas se dejan solas. La única excepción deliberada es la lista de alias: tiene autoridad.
• La base de datos principal de la aplicación y los perfiles de respaldo de todo el servidor siguen siendo suyos. generate los deja fuera a propósito.
• Las bases de datos se crean, nunca se eliminan. Eliminar una entrada de base de datos del archivo no elimina la base de datos.
• Ningún campo lleva un comando de shell o una ruta para incluir. Las claves desconocidas son errores.

Es seguro aceptarlo a través de Git

El archivo llega desde un repositorio, por lo que cualquiera que pueda confirmarlo controla su contenido. El esquema está cerrado a prueba de fallos en todo momento:

• Las bases de datos deben tener nombre <app> o <app>_*; perfiles de respaldo <app> o <app>-*.
• La URL de verificación de estado debe resolverse en uno de los dominios propios de la aplicación; de lo contrario, una confirmación podría apuntar el sondeador de cinco minutos a una dirección interna y leer la respuesta de los correos electrónicos de alerta.
• El analizador implementa un pequeño subconjunto YAML y rechaza directamente anclajes, alias, etiquetas, claves de fusión, escalares de bloques y asignaciones de flujo.

Preguntas frecuentes

Sigue leyendo