Gérez Laravel applications avec cipi.yml

Par Andrea Pollastri · Dernière mise à jour : 7 septembre 2026 · lecture gratuite, pas de paywall

L'état qu'une application attend sur le serveur (alias, PHP, Workers, santé, sauvegardes) se trouve généralement dans un panneau ou dans la tête de quelqu'un. Depuis Cipi 5.1, il peut vivre dans un cipi.yml à la racine du dépôt, revu dans la même pull request que le code qui en dépend. Ce guide est la boucle pratique : générer, planifier, appliquer, puis s'inscrire pour que chaque déploiement soit réconcilié.

Pourquoi le fichier appartient à côté du code

Une version qui ajoute une tâche en file d'attente sans travailleur est à moitié expédiée. Un rollback qui laisse celui de la semaine dernière upload_max_filesizeest à moitié annulé. L'état du serveur réside généralement ailleurs : un panneau, une page wiki ou la mémoire de celui qui a configuré la boîte.

A cipi.yml validé à côté de l'application Laravel fait que cet état fait partie de la même pull request que le code qui en dépend. Le fichier est déclaratif: il décrit l'état final, pas les étapes. Cipi lit ce que possède le serveur, le compare avec le fichier et vous montre la différence avant de toucher à quoi que ce soit.

Démarrer à partir du serveur live

Vous n'êtes pas obligé d'écrire le fichier à la main. Sur une boîte Cipi 5.1+, imprimez la configuration actuelle de l'application (alias, version PHP et paramètres par application, bases de données supplémentaires, files d'attente relues à partir de Supervisor, Horizon, Reverb, le planificateur et les profils de sauvegarde que possède l'application) — sous forme de fichier prêt à être validé :

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

Validez ce fichier à la racine du référentiel. Cipi le recherche dans current/cipi.yml, alors current/cipi.yaml, alors shared/cipi.yml — remplacer par --file=<path> si vous le gardez ailleurs.

Vous préférez un modèle vierge et entièrement commenté ? cipi yml example myapp en imprime un avec des bases de données et des profils réservés déjà dans l'espace de noms de cette application, de sorte que le modèle soit validé tel quel.

Les commandes que vous utiliserez

$ 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

Ce que vous pouvez déclarer

Sept domaines. Vous n’êtes pas obligé de tous les déclarer : seules les sections que vous rédigez sont rapprochées.

• Alias — la liste déclarée remplace la liste actuelle. Un alias que vous supprimez du fichier est supprimé de Nginx. Caractères génériques tels que*.myapp.com sont acceptés. Le domaine principal n'est jamais géré ici.
• PHP et php.ini — épinglez l'application sur PHP 8.3, 8.4 ou 8.5 (déjà installée sur le serveur) et définissez des remplacements par application : upload_max_filesize, post_max_size, memory_limit et le reste. Les valeurs à l'échelle du serveur restent les mêmes cipi ini set.
• Bases de données supplémentaires — au-delà de celui créé avec l'application, le MariaDB ou le PostgreSQL. Les informations d’identification arrivent shared/cipi-databases.env et ne sont jamais réécrits dans le référentiel. Les bases de données sont créées, jamais supprimées.
• Travailleurs de file d'attente et Horizon — déclarez chaque file d'attente avec le nombre de processus, les tentatives et le délai d'attente, et Supervisor est rapproché pour correspondre. Ou définir horizon: true et laissez Horizon posséder les files d'attente. Depuis 5.1.2, horizon: false est effectivement lu - auparavantfalse a été traité comme une clé manquante.
• Laravel Reverb — depuis 5.1.2, reverb: true donne à l'application un port localhost, un programme Supervisor, un proxy nginx pour /app/{key} et /apps/{id}/… sur son propre domaine, et généré REVERB_* informations d'identification. Laravel applications uniquement. Une application qui possède déjà /app ou /apps ne peut pas partager ce domaine avec Reverb.
• Planificateur — un tour booléen * * * * * artisan schedule:run allumé ou éteint. Pas de modification de crontab sur le serveur suivant.
• Bilan de santé — une sonde HTTP sur l'un des domaines propres à l'application, vérifiée toutes les cinq minutes et à nouveau juste après chaque déploiement. Facultativement, annulez automatiquement une version défaillante - le lien symbolique du code uniquement ; les migrations ne se défont pas.
• Profils de sauvegarde — des profils par application avec leur propre portée, calendrier, conservation, destinations et cryptage. Les noms doivent être myapp ou myapp-*.

Un dossier complet

C’est ce qu’une application de production propose généralement. Vous pouvez en générer la majeure partie ; les commentaires sont pour la pull request.

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

Planifiez, puis postulez

Rien ne change jusqu'à ce que vous regardiez la différence. cipi yml plan myapp répertorie tous les alias, travailleurs, bases de données, paramètres et profils qui seraient ajoutés, modifiés ou supprimés. Lisez-le comme vous lisez une pull request.

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

Un dossier dont la validation échoue est rejeté dans son ensemble et jamais partiellement appliqué. Il s'agit du même chemin fermé en cas d'échec qu'un déploiement utilise lorsque yml auto est activé : email yml_fail, pas de demi-état sur la boite.

Une semaine de vrais changements

Traitez le fichier comme du code d'application. Chacun d'entre eux est un commit d'une ligne (ou d'un bloc), révisé, puis appliqué - ou appliqué automatiquement après la publication si yml auto est déjà allumé.

• Lundi – pseudonymes. Ajouter www.myapp.com et *.myapp.com pour les sous-domaines multi-locataires. N'oubliez pas : la liste fait autorité. Supprimer un alias du fichier le supprime de Nginx.
• Mardi — php.ini. Un formulaire commence à accepter les importations de 40 Mo. Bosse upload_max_filesize et post_max_size dans app.ini. Les valeurs par défaut à l'échelle du serveur restent les mêmes cipi ini set.
• Mercredi — une nouvelle file d'attente. La version ajoute un emails file d'attente. Ajoutez le travailleur avec processes, tries et timeout. Supervisor correspond au fichier. Si vous basculez l'application sur Horizon, réglez horizon: true et supprimez la liste d'attente.
• Jeudi — une base de données supplémentaire. Le reporting nécessite son propre MariaDB (ou engine: pgsql). Nommez-le myapp_reporting. Les informations d'identification apparaissent dans /home/myapp/shared/cipi-databases.env- jamais dans Git. Cipi crée des bases de données ; il ne les supprimera pas si vous supprimez l'entrée plus tard.
• Vendredi – santé et sauvegardes. Point health.url à https://myapp.com/up (il doit s'agir de l'un des domaines propres à l'application). Ajoutez un bon marché myapp-db profil toutes les 30 minutes et une copie nocturne cryptée sur S3.

Inscrivez-vous après chaque déploiement

Les déploiements ignorent le fichier jusqu'à ce que vous disiez le contraire. C'est délibéré : un premier engagement decipi.ymlne devrait pas surprendre la production.

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

Avec l'opt-in donné, chaque réussi déployer des rapprochements - des deux cipi deploy et le Git webhook. Une version qui ne porte aucun cipi.yml est une opération silencieuse. Un fichier dont la validation échoue est signalé par email (yml_fail) et jamais appliqué à mi-chemin. Un rapprochement réussi des incendies yml_apply.

Ce que le fichier ne touchera pas

• Cela ne peut que configurerune application qui existe déjà – ne jamais en créer, renommer ou supprimer.
• Les sections que vous omettez sont laissées telles quelles. La seule exception délibérée est la liste d’alias : elle fait autorité.
• La base de données principale de l'application et les profils de sauvegarde à l'échelle du serveur restent les vôtres. generate les laisse volontairement de côté.
• Les bases de données sont créées, jamais supprimées. La suppression d'une entrée de base de données du fichier ne supprime pas la base de données.
• Aucun champ ne contient de commande shell ou de chemin à inclure. Les clés inconnues sont des erreurs.

Acceptation sûre via Git

Le fichier provient d'un référentiel, donc toute personne pouvant valider contrôle son contenu. Le schéma est fermé en cas d'échec :

• Les bases de données doivent être nommées <app> ou <app>_*; profils de sauvegarde <app> ou <app>-*.
• L'URL du contrôle de santé doit correspondre à l'un des propres domaines de l'application. Dans le cas contraire, une validation pourrait viser une sonde de cinq minutes vers une adresse interne et relire la réponse dans les e-mails d'alerte.
• L'analyseur implémente un petit sous-ensemble YAML et refuse catégoriquement les ancres, les alias, les balises, les clés de fusion, les scalaires de bloc et les mappages de flux.

Questions fréquemment posées

Continuez à lire