Gerencie Laravel aplicativos com cipi.yml

Por Andrea Pollastri · Última atualização: 7 de setembro de 2026 · grátis para ler, sem acesso pago

O estado que um aplicativo espera no servidor – aliases, PHP, trabalhadores, saúde, backups – geralmente fica em um painel ou na cabeça de alguém. Desde Cipi 5.1 ele pode viver em um cipi.yml na raiz do repositório, revisado na mesma solicitação pull do código que dele depende. Este guia é o ciclo prático: gerar, planejar, aplicar e, em seguida, ativar para que cada implantação seja reconciliada.

Por que o arquivo pertence ao lado do código

Uma versão que adiciona um trabalho na fila sem um trabalhador é enviada pela metade. Uma reversão que sai da semana passada upload_max_filesizeestá meio revertido. O estado do servidor geralmente reside em outro lugar: um painel, uma página wiki ou a memória de quem configurou a caixa.

A cipi.yml confirmado próximo ao aplicativo Laravel torna esse estado parte da mesma solicitação pull que o código que depende dele. O arquivo é declarativo: descreve o estado final, não as etapas. Cipi lê o que o servidor tem, compara com o arquivo e mostra a diferença antes de mexer em qualquer coisa.

Comece no servidor ativo

Você não precisa escrever o arquivo manualmente. Em uma caixa Cipi 5.1+, imprima a configuração atual do aplicativo — aliases, versão PHP e configurações por aplicativo, bancos de dados extras, trabalhadores da fila lidos de Supervisor, Horizon, Reverb, o agendador e os perfis de backup que o aplicativo possui — como um arquivo pronto para commit:

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

Confirme esse arquivo na raiz do repositório. Cipi procura em current/cipi.yml, então current/cipi.yaml, então shared/cipi.yml - substituir por --file=<path> se você mantê-lo em outro lugar.

Prefere um modelo em branco e totalmente comentado? cipi yml example myapp imprime um com bancos de dados de espaço reservado e perfis já dentro do namespace desse aplicativo, para que o modelo seja validado como está.

Os comandos que você usará

$ 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

O que você pode declarar

Sete áreas. Você não precisa declarar todos eles – apenas as seções que você escreve são reconciliadas.

• Aliases — a lista declarada substitui a atual. Um alias que você exclui do arquivo é removido de Nginx. Curingas como*.myapp.com são aceitos. O domínio primário nunca é gerenciado aqui.
• PHP e php.ini — fixe o aplicativo em PHP 8.3, 8.4 ou 8.5 (já instalado no servidor) e defina substituições por aplicativo: upload_max_filesize, post_max_size, memory_limit e o resto. Os valores de todo o servidor permanecem com cipi ini set.
• Bancos de dados extras — além daquele criado com o aplicativo, em MariaDB ou PostgreSQL. As credenciais chegam shared/cipi-databases.env e nunca são gravados de volta no repositório. Bancos de dados são criados, nunca descartados.
• Fila de trabalhadores e Horizon — declara cada fila com contagem de processos, tentativas e tempo limite, e Supervisor é reconciliado para corresponder. Ou definir horizon: true e deixe Horizon ser o dono das filas. Desde 5.1.2, horizon: false é realmente lido - anteriormentefalse foi tratado como uma chave perdida.
• Laravel Reverb - desde 5.1.2, reverb: true dá ao aplicativo uma porta localhost, um programa Supervisor, um proxy nginx para /app/{key} e /apps/{id}/… em seu próprio domínio e gerado REVERB_* credenciais. Laravel apenas aplicativos. Um aplicativo que já possui /app ou /apps não é possível compartilhar esse domínio com Reverb.
• Agendador - uma volta booleana * * * * * artisan schedule:run ligado ou desligado. Nenhuma edição do crontab no próximo servidor.
• Verificação de integridade — uma investigação HTTP em um dos domínios do próprio aplicativo, verificada a cada cinco minutos e novamente logo após cada implantação. Opcionalmente, reverta automaticamente uma versão com falha - apenas o link simbólico do código; as migrações não são desfeitas.
• Perfis de backup — perfis por aplicativo com escopo, programação, retenção, destinos e criptografia próprios. Os nomes devem ser myapp ou myapp-*.

Um arquivo completo

Isso é o que um aplicativo de produção normalmente fornece. Você pode gerar a maior parte; os comentários são para a solicitação pull.

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

Planeje e depois aplique

Nada muda até você olhar para a diferença. cipi yml plan myapp lista cada alias, trabalhador, banco de dados, configuração e perfil que seriam adicionados, alterados ou removidos. Leia da mesma forma que você lê uma solicitação pull.

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

Um arquivo que falha na validação é rejeitado como um todo e nunca aplicado parcialmente. Esse é o mesmo caminho de falha fechada que uma implantação usa quando yml auto está ativado: e-mail yml_fail, sem meio estado na caixa.

Uma semana de mudanças reais

Trate o arquivo como código de aplicativo. Cada um deles é um commit de uma linha (ou um bloco), revisado e então aplicado — ou aplicado automaticamente após o lançamento, se yml auto já está ligado.

• Segunda-feira - apelidos. Adicionar www.myapp.com e *.myapp.com para subdomínios multilocatários. Lembre-se: a lista é oficial. Eliminar um alias do arquivo o remove de Nginx.
• Terça-feira — php.ini. Um formulário começa a aceitar uploads de 40 MB. Colisão upload_max_filesize e post_max_size em app.ini. Os padrões de todo o servidor permanecem com cipi ini set.
• Quarta-feira – uma nova fila. O lançamento adiciona um emails fila. Adicione o trabalhador com processes, tries e timeout. Supervisor corresponde ao arquivo. Se você mudar o aplicativo para Horizon, defina horizon: true e elimine a lista de filas.
• Quinta-feira – um banco de dados extra. Os relatórios precisam de seu próprio MariaDB (ou engine: pgsql). Dê um nome myapp_reporting. As credenciais aparecem em /home/myapp/shared/cipi-databases.env- nunca no Git. Cipi cria bancos de dados; eles não serão descartados se você excluir a entrada posteriormente.
• Sexta-feira – saúde e backups. Ponto health.url em https://myapp.com/up (deve ser um dos domínios próprios do aplicativo). Adicione um barato myapp-db perfil a cada 30 minutos e uma cópia noturna criptografada para S3.

Ative após cada implantação

As implantações ignoram o arquivo até que você diga o contrário. Isso é deliberado: um primeiro commit decipi.ymlnão deve surpreender a produção.

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

Com o opt-in fornecido, cada bem sucedido implantar reconciliações - de ambos cipi deploy e o Git webhook. Um lançamento que não traz cipi.yml é um ambiente silencioso e autônomo. Um arquivo que falha na validação é relatado por email (yml_fail) e nunca aplicado pela metade. Uma reconciliação bem-sucedida dispara yml_apply.

O que o arquivo não tocará

• Só pode configurarum aplicativo que já existe – nunca crie, renomeie ou exclua um.
• As seções que você omitir serão deixadas em paz. A única exceção deliberada é a lista de alias: ela é oficial.
• O banco de dados primário do aplicativo e os perfis de backup em todo o servidor permanecem seus. generate os deixa de fora de propósito.
• Bancos de dados são criados, nunca descartados. A remoção de uma entrada de banco de dados do arquivo não exclui o banco de dados.
• Nenhum campo contém um comando shell ou um caminho a ser incluído. Chaves desconhecidas são erros.

É seguro aceitar em vez do Git

O arquivo chega de um repositório, então qualquer pessoa que possa fazer commit controla seu conteúdo. O esquema é fechado com falha em:

• Os bancos de dados devem ser nomeados <app> ou <app>_*; perfis de backup <app> ou <app>-*.
• O URL de verificação de integridade deve ser resolvido para um dos domínios do próprio aplicativo — caso contrário, um commit poderia direcionar a sonda de cinco minutos para um endereço interno e ler a resposta dos e-mails de alerta.
• O analisador implementa um pequeno subconjunto YAML e recusa âncoras, aliases, tags, chaves de mesclagem, escalares de bloco e mapeamentos de fluxo de uma vez.

Perguntas frequentes

Continue lendo