App

cipi app create

cipi app create supporta due tipi di app: Laravel (predefinito) e Custom (--custom). Le app Laravel ottengono un ambiente completamente isolato: utente Linux, pool PHP-FPM oppure Laravel Octane (FrankenPHP) dalla v5.0, vhost Nginx, database (MariaDB di default; PostgreSQL opzionale dalla v4.8.0), queue worker Supervisor, voce crontab, release Deployer zero-downtime, chiave deploy SSH e .env compilato automaticamente. Le app personalizzate sono più semplici — vedi app personalizzate per i dettagli.

App Laravel (predefinita — PHP-FPM)

$ cipi app create

Laravel Octane (FrankenPHP)

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

Vedi Laravel Octane per i requisiti, la conversione e come il vhost differisce da FPM.

Non interattivo (flag)

$ 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

App

Laravel Octane (FrankenPHP)

Dalla v5.0, le app Laravel possono servire HTTP via Laravel Octane con il server FrankenPHP invece di un pool PHP-FPM per app. Octane e le app FPM classiche convivono sullo stesso server Cipi.

Cosa configura Cipi

• Alloca una porta localhost in 8100–8999 e salva octane / octane_port in apps.json
• Il vhost Nginx usa proxy_pass verso Octane e serve i file statici da current/public — nessun pool FPM per app
• Programma Supervisor ${app}-octane accanto ai queue worker
• Il template Deployer laravel-octane.php riavvia / ricarica Octane al deploy
• .env: OCTANE_SERVER=frankenphp, OCTANE_HTTPS=true

Requisiti dell'app

Il tuo repository Laravel deve includere laravel/octane ed eseguire php artisan octane:install --server=frankenphp. Octane parte dopo il primo deploy riuscito.

# 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 riscrive pool / vhost / Supervisor / template Deployer / .env e riapplica SSL quando un certificato è già presente.

cipi app create --custom

Crea un'app personalizzata con deploy classico (senza zero-downtime): il codice viene deployato in htdocs — nessun symlink current/shared. Ideale per siti statici, SPA (Vue, React, Svelte), WordPress, altri CMS o qualsiasi progetto PHP non Laravel o framework.

Durante la creazione scegli solo la document root (predefinito /, oppure es. www, dist, public). Nginx è preconfigurato con index index.html index.php, try_files $uri $uri/ /index.php?$args e error_page 404 /404.html — nessuna richiesta per try_files o entry point.

Git opzionale (solo SFTP)

Il repository Git è opzionale per le app personalizzate. Le app Laravel richiedono ancora un repository. Se salti il repository per un'app personalizzata, Cipi crea /home/<app>/htdocs con un index.html segnaposto e non configura chiave deploy o webhook — carichi i file con SFTP (o SCP/rsync) in ~/htdocs come utente dell'app. L'output di onboarding spiega questo flusso “no repo — solo SFTP”. Se fornisci un repository, il comportamento resta invariato: usa cipi deploy <app> per scaricare il codice in htdocs.

Cosa è incluso e cosa aggiungi tu

Le app personalizzate non hanno database, nessun .env, nessun cron e nessun queue worker. Quando un repository è configurato, vengono mostrati chiave deploy e (con Git auto-setup) webhook; per le app solo SFTP, vengono omessi. Il riepilogo post-creazione elenca l'accesso SSH e i passi successivi di conseguenza.

Se la tua app personalizzata necessita di un database (es. WordPress, Drupal), creane uno con cipi db create --name=<app> dopo il deploy. Vedi cipi db per backup, restore e gestione password.

Con Git — esempio non interattivo:

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

Solo SFTP — ometti --repository e --branch:

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

Con un repository, usa cipi deploy <app> per fare il deploy; il codice viene clonato in /home/<app>/htdocs.

app list / app show / app edit / app delete

cipi app reverb

Dalla v5.0, abilita Laravel Reverb per WebSocket first-party su un'app Laravel. Cipi alloca una porta localhost in 9000–9099, aggiunge il programma Supervisor ${app}-reverb, fa proxy Nginx di /app su quella porta e scrive REVERB_* in .env.

$ cipi app reverb enable myapp
$ cipi app reverb status myapp
$ cipi app reverb disable myapp

cipi app clone

Dalla v5.0, clona un'app Laravel esistente in una nuova app staging (o review) con dominio proprio. Imposta cloned_from in apps.json; non copia webhook o ID git.

$ 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

Dalla v5.0, imposta limiti di risorse per app con cap rigidi applicati da 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

Disponibile dalla v4.5.8. Metti un'app offline senza eliminarla — utile per blocchi di fatturazione, finestre di manutenzione o siti staging che vuoi completamente spenti. La sospensione sostituisce il vhost Nginx con una pagina statica HTTP 503 servita da /var/www/cipi-suspended/.

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

Comportamento

• HTTPS incluso — certbot clona il vhost di sospensione nel blocco :443, quindi anche HTTPS mostra la pagina offline
• Let's Encrypt funziona ancora — il percorso /.well-known/acme-challenge/ resta pubblico così i certificati possono essere emessi o rinnovati mentre l'app è sospesa
• Sopravvive alla rigenerazione del vhost — cambi alias, modifiche PHP e installazioni SSL rispettano il flag suspended
• Visibile negli elenchi — cipi app list segna le app sospese; cipi domains aggiunge ⏸ suspended su ogni riga

Disponibile anche via REST API (POST /api/apps/{name}/suspend), cipi-cli (apps suspend) e il modulo WHMCS (pulsanti Suspend / Unsuspend). Richiede l'abilità token apps-suspend per l'accesso API.

cipi basicauth

Disponibile dalla v4.5.2. Proteggi qualsiasi app — Laravel o personalizzata — dietro un prompt username/password Nginx. Utile per siti staging, tool interni o app non ancora pronte al traffico pubblico.

Le credenziali sono hashate con openssl passwd -apr1 (non serve apache2-utils) e salvate in /etc/nginx/cipi-basicauth/<app>.htpasswd; lo stato attivo è in apps.json. Le direttive auth_basic sono iniettate per blocco location, quindi la protezione sopravvive alla rigenerazione del vhost (cambi alias, modifiche PHP) ed è clonata nel blocco :443 da certbot — HTTPS coperto. Le challenge ACME restano pubbliche, quindi emissione e rinnovo certificati non sono mai bloccati. Basic auth viene rimosso automaticamente con cipi app delete.

Gestione variabili ENV

Ogni app Laravel ha un unico file .env in /home/<app>/shared/.env. Le app personalizzate non hanno .env. Viene creato e precompilato da Cipi durante app create con credenziali database, APP_KEY, APP_URL, impostazioni cache/session/queue e token webhook. La directory shared/ è symlinkata in ogni release, quindi lo stesso .env è sempre attivo indipendentemente dalla release corrente.

Modifica interattiva via CLI

Il modo più sicuro per cambiare valori ENV è tramite Cipi — apre il file in nano come utente dell'app, con i permessi corretti:

$ cipi app env myapp

Salva con Ctrl+O poi esci con Ctrl+X. Le modifiche hanno effetto immediato per le nuove richieste — nessun restart per la maggior parte dei valori. Se cambi connessione queue o driver cache, riavvia i worker:

$ cipi worker restart myapp

Modifica direttamente via SSH

Puoi anche modificare il file direttamente via SSH come root o come utente dell'app:

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

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

Variabili ENV chiave impostate da Cipi

Aggiungere le tue variabili

Aggiungi qualsiasi variabile personalizzata in fondo al file come faresti normalmente in un progetto Laravel. Sono preservate tra i deploy perché il .env vive in shared/ e non viene mai sovrascritto da Deployer.

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

cipi app logs

Segui i log applicativi in tempo reale. I log ruotano giornalmente e restano 14 giorni. Per default vengono mostrati tutti i log inclusi i log giornalieri Laravel (laravel-YYYY-MM-DD.log) da 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

Esegui comandi Artisan e Tinker come utente dell'app con la versione PHP corretta e contesto open_basedir — esattamente come girerebbero durante un deploy.

$ 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 come utente dell'app

Ogni app gira sotto un utente Linux isolato. A volte devi lavorare direttamente nell'ambiente di quell'utente — ispezionare file, eseguire script one-off o debuggare qualcosa che si riproduce solo come utente corretto.

SSH diretto come utente dell'app (consigliato)

Gli utenti app possono fare SSH direttamente al server con la password generata alla creazione dell'app:

# 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

La password viene mostrata quando l'app viene creata (o usa cipi app reset-password myapp per rigenerarla). Funziona per client SFTP, sessioni remote IDE e accesso terminale.

Via cipi (percorso admin)

Se sei già connesso come cipi, puoi passare direttamente a qualsiasi utente app:

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

myapp@server:~$ pwd
/home/myapp

Reimposta la password dell'utente app

Se devi rigenerare la password di un utente app (es. per SSH diretto o SFTP), usa:

$ cipi app reset-password myapp

La nuova password viene mostrata a schermo — salvala subito.

Comandi utili una volta loggato come utente app

# 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/

Il .bashrc di ogni utente app definisce un comodo alias ll='ls -al' (dalla v4.5.5) per elenchi directory più rapidi via SSH, insieme alle scorciatoie deploy e composer. Le app create prima della 4.5.5 ricevono l'alias ll automaticamente al prossimo cipi self-update via la migrazione 4.5.5.