Aplicativos

cipi app create

cipi app create suporta dois tipos de aplicativos: Laravel (padrão) e Personalizado (--custom). Laravel aplicativos obtêm um ambiente totalmente isolado: Usuário Linux, pool PHP-FPM ou Laravel Octane (FrankenPHP) desde v5.0, Nginx vhost, banco de dados (MariaDB por padrão; opcional PostgreSQL já que v4.8.0), Supervisor trabalhador, entrada crontab, versões com tempo de inatividade zero do Deployer, SSH implantar chave e compilar automaticamente .env. Aplicativos personalizados são mais simples – veja aplicativos personalizados para obter detalhes.

Laravel aplicativo (padrão — PHP-FPM)

$ cipi app create

Laravel Octane (FrankenPHP)

$ cipi app create --octane
$ cipi app create --octane=frankenphp   # explicit (same as --octane)

Veja Laravel Octane para requisitos, conversão e como o vhost difere do FPM.

Não interativo (sinalizadores)

$ cipi app create \
    --user=myapp \
    --domain=myapp.com \
    --repository=git@github.com:you/myapp.git \
    --branch=main \
    --php=8.5

# Laravel Octane (FrankenPHP) — v5.0+
$ cipi app create --user=myapp --domain=myapp.com \
    --repository=git@github.com:you/myapp.git --octane

# optional PostgreSQL (v4.8.0+, after cipi db install pgsql)
$ cipi app create --user=myapp --domain=myapp.com \
    --repository=git@github.com:you/myapp.git --engine=pgsql

Aplicativos

Laravel Octane (FrankenPHP)

Desde v5.0, Laravel aplicativos podem servir HTTP via Laravel Octane com o FrankenPHP servidor em vez de por aplicativo Piscina de PHP-FPM. Aplicativos Octane e FPM clássicos são executados lado a lado no mesmo servidor Cipi.

O que Cipi configura

• Aloca uma porta localhost em 8100–8999 e lojas octane / octane_port em apps.json
• Nginx vhost usa proxy_pass para Octane e exibe arquivos estáticos de current/public — nenhum pool FPM por aplicativo
• Supervisor programa ${app}-octane ao lado dos trabalhadores da fila
• Modelo de implantador laravel-octane.php reinicia/recarrega Octane na implantação
• .env: OCTANE_SERVER=frankenphp, OCTANE_HTTPS=true

Requisitos do aplicativo

Seu repositório Laravel deve incluir laravel/octane e correr php artisan octane:install --server=frankenphp. Octane começa após o primeiro implantação bem-sucedida.

# create an Octane app
$ cipi app create --user=myapp --domain=myapp.com \
    --repository=git@github.com:you/myapp.git --octane

# convert an existing FPM app → Octane (or the reverse)
$ cipi app convert myapp --to=octane
$ cipi app convert myapp --to=fpm

# tune Octane workers (also see app limits)
$ cipi app limits myapp --octane-workers=4

cipi app convert --to=octane|fpm reescreve o pool / vhost / Supervisor / Deployer modelo / .enve reaplica SSL quando um certificado já estiver presente.

cipi app create --custom

Cria um aplicativo personalizado com implantação clássica (sem tempo de inatividade zero): o código é implantado em htdocs - não current/shared links simbólicos. Ideal para sites estáticos, SPAs (Vue, React, Svelte), WordPress, outro CMS ou qualquer projeto ou estrutura que não seja Laravel PHP.

Durante a criação você escolhe apenas a raiz do documento (padrão /, ou por ex. www, dist, public). Nginx está pré-configurado com index index.html index.php, try_files $uri $uri/ /index.php?$argse error_page 404 /404.html — não há prompts para try_files ou ponto de entrada.

Git opcional (somente SFTP)

O repositório Git é opcional para aplicativos personalizados. Laravel os aplicativos ainda exigem um repositório. Se você pular o repositório para um personalizado aplicativo, Cipi cria /home/<app>/htdocs com um espaço reservado index.html e faz não configure uma chave de implantação ou webhook — você carrega arquivos com SFTP (ou SCP/rsync) para ~/htdocscomo o usuário do aplicativo. A saída de integração explica isso “sem repo – apenas SFTP” fluxo de trabalho. Se você fornecer um repositório, o comportamento permanecerá inalterado: use cipi deploy <app> para puxar o código para htdocs.

O que está incluído e o que você adiciona

Aplicativos personalizados têm sem banco de dados, não .env, não cron e não trabalhadores da fila. Quando um repositório é configurado, uma chave de implantação e (com configuração automática do Git) webhook são mostrado; para aplicativos somente SFTP, eles são omitidos. O resumo pós-criação lista o acesso SSH e o próximo passos em conformidade.

Se o seu aplicativo personalizado precisar de um banco de dados (por exemplo, WordPress, Drupal), crie um com cipi db create --name=<app> após a implantação. Vejacipi dbpara backup, restauração e gerenciamento de senhas.

Com Git — exemplo não interativo:

$ cipi app create --custom --user=mysite --domain=mysite.com \
    --repository=git@github.com:you/mysite.git --docroot=dist

Somente SFTP — omitir --repository e --branch:

$ cipi app create --custom --user=mysite --domain=mysite.com --docroot=dist

Com um repositório, use cipi deploy <app> implantar; código é clonado em /home/<app>/htdocs.

app list / app show / app edit / app delete

cipi app reverb

Laravel Reverb é o servidor WebSocket first-party do Laravel. O Cipi gere-o desde v5.0; a v5.1.2 é a release que o torna usável em produção — credenciais geradas, esquema derivado do certificado, limites de ligação mais altos e um proxy que já não engole as tuas próprias rotas.

Ativar o Reverb numa app Laravel configura quatro coisas: uma porta localhost 9000–9099, o programa Supervisor ${app}-reverb, um proxy nginx para /app/{key} e /apps/{id}/… no domínio da app, e as chaves REVERB_* / VITE_REVERB_* no .env.

$ cipi app reverb enable myapp
$ cipi app reverb enable myapp --restart-supervisor   # aplica já o novo limite de ficheiros abertos
$ cipi app reverb status myapp
$ cipi app reverb disable myapp

Reverb é só Laravel. Voltar a correr enable é seguro: não realoca a porta nem toca nas credenciais; recalcula host e esquema e preenche chaves .env em falta. O build Node tem de correr depois do enable. Ver node_build.

ws:// ou wss:// deriva do certificado. Um wildcard resolve para um host concreto. status mostra o URL do cliente e avisa se falta uma credencial, se há certificado mas o esquema ainda é http, ou se o Supervisor ainda tem o limite antigo. --restart-supervisor reinicia todos os queue workers do servidor.

disable restaura BROADCAST_CONNECTION (fallback log). Um clone recebe porta, credenciais e domínio próprios. Declara-se em workers.reverb. A migração 5.1.2 reescreve os vhosts gulosos (backup em /var/lib/cipi/vhost-backup-5.1.2) e preenche o .env sem sobrescrever — depois faz redeploy para o bundle Vite.

cipi app clone

Desde v5.0, clone um aplicativo Laravel existente em um novo aplicativo de teste (ou revisão) com seu próprio domínio. Conjuntos cloned_from em apps.json; faz não copie webhook ou IDs git. Se a origem tiver Reverb, o clone recebe porta, credenciais e host próprios (desde v5.1.2). Ver cipi app reverb.

$ cipi app clone myapp --domain=staging.myapp.com
$ cipi app clone myapp --domain=staging.myapp.com --name=myapp-stg --branch=develop --with-db
$ cipi app clone myapp --domain=staging.myapp.com --no-db

cipi app limits

Desde v5.0, defina limites de recursos por aplicativo com limites rígidos aplicados por Cipi.

$ cipi app limits myapp --fpm-max-children=20 --memory-limit=256M
$ cipi app limits myapp --octane-workers=4 --worker-procs=3
$ cipi app limits myapp   # show current limits

app suspend / app unsuspend

Disponível desde v4.5.8. Coloque um aplicativo off-line sem excluí-lo – útil para faturamento retenções, janelas de manutenção ou sites de teste que você deseja que sejam totalmente escuros. A suspensão troca o Nginx vhost por uma estática HTTP 503 página veiculada de /var/www/cipi-suspended/.

$ cipi app suspend myapp      # take offline (503 page)
$ cipi app unsuspend myapp    # restore normal vhost

Comportamento

• HTTPS incluído — certbot clona o vhost de suspensão no :443 bloco, então HTTPS também mostra a página offline
• Let's Encrypt ainda funciona - o /.well-known/acme-challenge/ caminho permanece público para que os certificados possam ser emitidos ou renovados enquanto estiverem suspensos
• Sobrevive à regeneração vhost — alterações de alias, PHP edições e SSL instalações respeite a bandeira suspensa
• Visível nas listagens — cipi app list marca aplicativos suspensos; cipi domains acrescenta ⏸ suspended em cada linha

Também disponível através do DESCANSE API (POST /api/apps/{name}/suspend), cipi-cli (apps suspend) e o Módulo WHMCS (Suspender / Botões para cancelar a suspensão). Requer habilidade de token apps-suspend para acesso API.

cipi basicauth

Disponível desde v4.5.2. Proteja qualquer aplicativo – Laravel ou personalizado – atrás de um Nginx prompt de nome de usuário/senha. Útil para testar sites, ferramentas internas ou aplicativos que não estão prontos para tráfego público ainda.

As credenciais são hash com openssl passwd -apr1 (não apache2-utils necessário) e armazenado em /etc/nginx/cipi-basicauth/<app>.htpasswd; o estado habilitado reside em apps.json. O auth_basic diretivas são injetadas por location bloco, para que a proteção sobreviva à regeneração do vhost (alterações de alias, PHP edições) e seja clonada no :443 bloquear por certbot — HTTPS também está coberto. Os desafios da ACME permanecem público, portanto a emissão e renovação de certificados nunca são bloqueadas. A autenticação básica é removida automaticamente em cipi app delete.

Gerenciando variáveis ENV

Cada Laravel aplicativo tem um único .env arquivo morando em /home/<app>/shared/.env. Aplicativos personalizados não têm .env. Ele é criado e pré-preenchido por Cipi durante app create com o banco de dados credenciais, APP_KEY, APP_URL, configurações de cache/sessão/fila e o ficha webhook. O shared/ diretório é vinculado simbolicamente a cada versão, então o mesmo .env está sempre ativo, independentemente da versão atual.

Edite interativamente via CLI

A maneira mais segura de alterar os valores ENV é através do próprio Cipi — ele abre o arquivo em nano como o aplicativo usuário, com as permissões corretas:

$ cipi app env myapp

Salvar com Ctrl+O então saia com Ctrl+X. As alterações entram em vigor imediatamente para novos solicitações — não é necessário reiniciar para a maioria dos valores. Se você alterar a conexão da fila ou o driver de cache, reinicie os trabalhadores:

$ cipi worker restart myapp

Sinalizadores não interativos (v5.0.3+)

Desde v5.0.3, scripts, o painel API e a web GUI podem gerenciar .env sem abrir um editor:

$ cipi app env myapp --show
$ cipi app env myapp --show --json
$ cipi app env myapp --get=APP_URL
$ cipi app env myapp --set=APP_DEBUG=false
$ cipi app env myapp --unset=LEGACY_KEY

DESCANSO: GET|PUT /api/apps/{name}/env (habilidadeapps-env, API 1.14+). MCP: AppEnvShow, AppEnvUpdate.

Edite diretamente via SSH

Você também pode editar o arquivo diretamente via SSH como root ou como usuário do aplicativo:

# as root
$ nano /home/myapp/shared/.env

# or switch to the app user first
$ su - myapp
$ nano ~/shared/.env

Principais variáveis ENV definidas por Cipi

Adicionando suas próprias variáveis

Adicione qualquer variável personalizada na parte inferior do arquivo como faria normalmente em um projeto Laravel. Eles são preservados nas implantações porque o .env mora em shared/ e é nunca substituído pelo Deployer.

# your custom variables
STRIPE_KEY=sk_live_...
STRIPE_SECRET=sk_live_...
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org

cipi app run

Desde v5.0.3, execute um não interativo na lista de permissões comando como o aplicativo usuário — útil em CLI, painel API e web GUI “Comandos de aplicativos”. Editores, pagers, shells e REPLs estão bloqueados (nano, vim, less, bash, tinker,…). Sinalizadores interativos (por exemplo tail -f, php -a) são rejeitado.

$ cipi app run myapp composer install --no-dev
$ cipi app run myapp npm ci
$ cipi app run myapp ls -la shared
$ cipi app run --commands          # list allowed binaries
$ cipi app run --commands --json

Os binários permitidos incluem composer, npm/npx/yarn/pnpm, ls/ll, cat/head/tail, sistema de arquivos ajudantes, arquivos, git, php, nodee find. DESCANSO: POST /api/apps/{name}/run (trabalho assíncrono, capacidade apps-run) e GET /api/run-commands (API 1.14+). MCP: AppRun, AppRunCommands.

cipi app logs

Acompanhe os logs do aplicativo em tempo real. Os logs são rotacionados diariamente e mantidos por 14 dias. Por padrão, todos os registros são mostrados, incluindo Laravel registros diários (laravel-YYYY-MM-DD.log) de shared/storage/logs/.

$ cipi app logs myapp                  # all logs (incl. Laravel daily logs)
$ cipi app logs myapp --type=nginx     # Nginx access + error
$ cipi app logs myapp --type=php       # PHP-FPM errors
$ cipi app logs myapp --type=worker    # queue worker output
$ cipi app logs myapp --type=deploy    # deploy history
$ cipi app logs myapp --type=laravel   # Laravel application logs

app artisan & app tinker

Execute os comandos Artisan e Tinker como o usuário do aplicativo com a versão PHP correta e open_basedir contexto — exatamente como seriam executados durante uma implantação.

$ cipi app artisan myapp migrate:status
$ cipi app artisan myapp queue:retry all
$ cipi app artisan myapp db:seed --class=ProductionSeeder
$ cipi app artisan myapp cache:clear
$ cipi app tinker myapp

SSH como usuário do aplicativo

Cada aplicativo é executado sob seu próprio usuário Linux isolado. Às vezes você precisa trabalhar diretamente dentro desse ambiente do usuário - inspecione arquivos, execute scripts únicos ou depure algo que apenas se reproduz como o usuário correto.

SSH direto como usuário do aplicativo (recomendado)

Os usuários do aplicativo podem usar SSH diretamente no servidor com a senha gerada na criação do aplicativo:

# connect as the app user (password auth)
$ ssh myapp@your-server-ip

# you are directly inside the app user's shell
myapp@server:~$ pwd
/home/myapp

myapp@server:~$ cd ~/current
myapp@server:~$ ls

A senha é mostrada quando o aplicativo é criado (ou usa cipi app reset-password myapp para regenerá-lo). Isso funciona para clientes SFTP, sessões remotas IDE e acesso de terminal.

Via cipi (caminho do administrador)

Se você já estiver conectado como cipi, você pode mudar diretamente para qualquer usuário do aplicativo:

$ ssh cipi@your-server-ip
cipi@server:~$ sudo su - myapp

myapp@server:~$ pwd
/home/myapp

Redefinir a senha do usuário do aplicativo

Se você precisar gerar novamente a senha de um usuário do aplicativo (por exemplo, para SSH direto ou SFTP), use:

$ cipi app reset-password myapp

A nova senha é exibida na tela – salve-a imediatamente.

Comandos úteis uma vez logado como usuário do aplicativo

# navigate to the active release
myapp@server:~$ cd ~/current

# run artisan directly with the correct PHP version
myapp@server:~$ /usr/bin/php8.5 ~/current/artisan tinker

# inspect the shared .env
myapp@server:~$ cat ~/shared/.env

# tail all logs
myapp@server:~$ tail -f ~/logs/*.log

# check active releases (ll is a built-in alias for ls -al)
myapp@server:~$ ll ~/releases/

Cada usuário do aplicativo .bashrc define um prático ll='ls -al' apelido (desde v4.5.5) para listagens de diretórios mais rápidas por SSH, junto com o deploy e composer atalhos. Os aplicativos criados antes da versão 4.5.5 recebem o ll alias automaticamente no próximo cipi self-update através do 4.5.5 migração.