Da Cipi 5.1

cipi.yml — la configurazione viaggia con il codice.

Un solo file nella radice del repository descrive lo stato che un'app si aspetta sul server: alias di dominio, versione PHP e impostazioni per-app, database aggiuntivi, worker di coda, scheduler, healthcheck e profili di backup. Lo rivedi in una pull request, viaggia con la release e cipi yml apply riallinea il server.

7 areeAlias, PHP, php.ini, database, worker, scheduler, health e backup.
plan → applyNon cambia nulla finché non leggi il diff e dai l'ok.
Fail-closedLimitato a una sola app, nessun comando di shell nello schema.
Riferimento completo nella documentazione Novità della 5.1

Configurazione del server, revisionata come il codice

Di solito lo stato del server vive altrove: in un pannello, in una pagina di wiki o nella memoria di chi ha preparato la macchina. Un cipi.yml committato accanto all'applicazione Laravel porta quello stato dentro la stessa pull request del codice che ne dipende. La release che aggiunge una coda aggiunge anche il suo worker. La release che ha bisogno di un upload_max_filesize più alto se lo porta dietro. Se torni indietro con il codice, torna indietro anche la configurazione.

Il file è dichiarativo: descrive lo stato finale, non i passaggi. Cipi legge com'è il server, lo confronta con il file e ti mostra la differenza prima di toccare qualsiasi cosa.

I comandi

bash
$ cipi yml generate myapp          # la config attuale dell'app, come cipi.yml
$ cipi yml example myapp           # template vuoto e commentato, nel namespace di myapp
$ cipi yml validate myapp          # analizza e verifica, senza cambiare nulla
$ cipi yml plan myapp              # mostra esattamente cosa cambierebbe
$ cipi yml apply myapp [--yes]     # applica
$ cipi yml auto myapp on|off|status  # applica dopo ogni deploy riuscito
Comando Cosa fa
cipi yml generate Stampa la configurazione dell'app così com'è sul server — alias, versione PHP e impostazioni per-app, database aggiuntivi, worker di coda riletti da Supervisor, scheduler e profili di backup dell'app — in un file pronto da committare.
cipi yml example Un template vuoto e interamente commentato. Passando il nome di un'app, database e profili di esempio finiscono nel namespace di quell'app e il template è già valido.
cipi yml validate Analizza il file e verifica ogni valore rispetto allo schema. Non cambia nulla.
cipi yml plan Il diff: ogni alias, worker, database, impostazione e profilo che verrebbe aggiunto, modificato o rimosso. Da leggere prima di applicare.
cipi yml apply Applica il piano. Con --yes per script e CI.
cipi yml auto Attiva — o disattiva — il riallineamento automatico dopo ogni deploy riuscito. status mostra l'impostazione corrente.

Il file viene cercato in current/cipi.yml, poi current/cipi.yaml, poi shared/cipi.yml — si può forzare con --file=<path>.

Cosa può configurare il file

app.aliases

Alias di dominio

L'elenco dichiarato sostituisce quello attuale: un alias che togli dal file viene rimosso da Nginx. Sono ammessi i wildcard come *.myapp.com, per i sottodomini multi-tenant. Il dominio principale non si gestisce qui.

Alias nella documentazione → app.php · app.ini

Versione PHP e php.ini

Fissa l'app su PHP 8.3, 8.4 o 8.5 (già installato sul server) e imposta gli override per-app: upload_max_filesize, post_max_size, memory_limit e gli altri. I valori validi per tutto il server restano in cipi ini set.

php.ini nella documentazione → databases

Database aggiuntivi

Oltre a quello creato con l'app: reportistica, analytics, quello che serve alla release, su MariaDB o PostgreSQL. Le credenziali finiscono in shared/cipi-databases.env e non tornano mai nel repository. I database vengono creati, mai cancellati.

Database nella documentazione → workers

Worker di coda e Horizon

Dichiari ogni coda con numero di processi, tentativi e timeout, e Supervisor viene riallineato. In alternativa horizon: true e le code le gestisce Horizon.

Worker nella documentazione → schedule

Lo scheduler di Laravel

Un booleano accende o spegne * * * * * artisan schedule:run per l'app. Niente crontab da modificare a mano, niente riga dimenticata sul prossimo server.

Scheduler nella documentazione → health

Healthcheck e rollback

Una sonda HTTP su uno dei domini dell'app, verificata ogni cinque minuti e di nuovo subito dopo ogni deploy. Volendo, la release che fallisce viene annullata da sola: solo il symlink del codice, le migration non vengono annullate.

Health check nella documentazione → backup.profiles

Profili di backup

Profili per-app con scope, frequenza, retention, destinazioni e cifratura: un giro leggero sui database ogni 30 minuti, una copia completa e cifrata su S3 di notte. I nomi dei profili restano nel namespace dell'app.

Backup nella documentazione → riferimento

Ogni chiave, documentata

Lo schema completo, l'ordine di ricerca del file, le regole di validazione e le notifiche stanno nel capitolo deploy della documentazione.

Leggi il riferimento →

Un file completo

Non devi scriverlo a mano. cipi yml generate <app> stampa quello che il server ha già: lo committi e cipi yml plan non trova nulla da fare.

bash
$ cipi yml generate myapp > cipi.yml   # poi committalo
$ cipi yml plan myapp                  # non c'è nulla da fare
yaml
version: 1

app:
  # 8.3, 8.4 o 8.5 — deve essere già installata (cipi php install 8.5)
  php: "8.5"

  # L'elenco dichiarato sostituisce gli alias attuali: quello che togli qui
  # viene rimosso dal server. Il dominio principale non si gestisce qui.
  aliases:
    - "www.myapp.com"
    - "*.myapp.com"      # wildcard, per sottodomini multi-tenant

  # Override php.ini per-app. I valori globali restano in `cipi ini set`.
  ini:
    upload_max_filesize: 50M
    post_max_size: 60M
    memory_limit: 512M

# Database aggiuntivi oltre a quello creato con l'app. Le credenziali finiscono
# in /home/myapp/shared/cipi-databases.env — mai riscritte nel repository.
databases:
  - name: myapp_reporting
  - name: myapp_analytics
    engine: pgsql          # mariadb (default) o pgsql

workers:
  horizon: false           # true sostituisce i worker qui sotto
  queues:
    - queue: default
      processes: 2
    - queue: emails
      processes: 1
      tries: 5
      timeout: 300

# Scheduler di Laravel (* * * * * artisan schedule:run)
schedule: true

# Healthcheck HTTP. Verificato ogni 5 minuti e subito dopo ogni deploy.
# L'URL deve essere uno dei domini dell'app.
health:
  url: "https://myapp.com/up"
  expect: 200
  # grace: 8                      # secondi prima della prima sonda dopo un deploy
  # postdeploy: false             # salta il controllo subito dopo il deploy
  # rollback_on_unhealthy: true   # annulla la release che fallisce il controllo
  #                               # (solo il symlink del codice — le migration NO)

# Strategia di backup dell'app. I profili devono chiamarsi myapp o myapp-*.
backup:
  profiles:
    # Frequente ed economico: solo database, senza le tabelle rumorose.
    - name: myapp-db
      scope: db
      databases: ["myapp", "myapp_*", "tenant_*"]
      exclude_tables: ["*.jobs", "*.telescope_*"]
      every: 30m           # 5m/10m/15m/20m/30m, 1h..12h, 1d..28d
      keep: 48             # conserva le ultime 48 esecuzioni
      destinations: [local]

    # Più lento, completo, off-site e cifrato.
    - name: myapp-nightly
      scope: all           # all | files | db
      cron: "0 2 * * *"
      keep_days: 14
      destinations: [s3]
      encrypt: true

I deploy ignorano il file finché non lo attivi

Al deploy non succede nulla finché non esegui cipi yml auto <app> on. Da quel momento ogni deploy riuscito riallinea — sia con cipi deploy sia con il webhook Git. Una release senza cipi.yml è semplicemente un no-op, e un file che non supera la validazione viene segnalato via email (yml_fail) e mai applicato a metà. Un riallineamento riuscito genera yml_apply.

bash
$ cipi yml auto myapp on       # riallinea dopo ogni deploy riuscito
$ cipi yml auto myapp status   # è attivo?
$ cipi yml auto myapp off      # torna all'apply manuale

Perché è sicuro accettarlo da Git

Il file arriva da un repository, quindi chiunque possa committare ne controlla il contenuto. Per questo è fail-closed dall'inizio alla fine:

Con yml auto attivo, chiunque possa fare push su quel repository può cambiare alias, impostazioni PHP, worker, healthcheck e profili di backup dell'app. È il senso della configuration-as-code: regola di conseguenza i permessi di scrittura sul repo.

Domande

Devo scrivere il file a mano?

No. cipi yml generate <app> stampa la configurazione attuale dell'app come cipi.yml pronto da committare, e cipi yml example stampa un template vuoto e commentato se preferisci partire da zero.

Un commit può rompere il server?

Lo schema non contiene comandi di shell né percorsi da includere, un'app può toccare solo i propri database e i propri profili di backup, e un file che non supera la validazione viene rifiutato per intero invece di essere applicato a metà. Finché non attivi cipi yml auto, i deploy ignorano del tutto il file.

Cosa succede a ciò che il file non menziona?

Resta com'è. Vengono riallineate solo le sezioni dichiarate, con un'eccezione voluta: l'elenco degli alias è autoritativo, quindi togliere un alias dal file lo rimuove dal server.

Funziona con il webhook Git?

Sì. Con cipi yml auto attivo, riallineano dopo una release riuscita sia cipi deploy sia un deploy avviato dal webhook.

Riferimento completo di cipi.yml Installa Cipi