Primi passi

Installazione di Cipi

Cipi installa uno stack di produzione completo pronto per Laravel su Ubuntu 24.04 o 26.04 con un solo comando. L'installer impiega circa 10 minuti e configura Nginx, MariaDB, PHP, Valkey (PostgreSQL opzionale via cipi db install pgsql dopo l'installazione), Supervisor, Fail2ban, UFW, Certbot, Deployer e la CLI cipi.

Durante l'installazione, la procedura guidata chiede la tua chiave pubblica SSH (formati accettati: ssh-rsa, ssh-ed25519, ecdsa) prima che venga installato qualsiasi pacchetto. Cipi crea un utente Linux dedicato cipi per l'accesso SSH admin e applica hardening SSH: login root disabilitato, cipi usa solo chiave pubblica (gruppo cipi-ssh), gli utenti app (gruppo cipi-apps) possono connettersi con password. I tentativi di login sono limitati a 3 con grace period di 20 secondi e X11 forwarding è disabilitato.

L'installer genera anche una password root casuale di 40 caratteri, la salva in /etc/cipi/server.json e la mostra nel riepilogo installazione. Le chiavi SSH incollate vengono sanitizzate automaticamente — commenti, carriage return e spazi eccessivi vengono rimossi prima della validazione.

Installazione standard

$ wget -O - https://cipi.sh/setup.sh | bash

Installazione non interattiva

Per setup automatizzati, passa la chiave pubblica SSH via la variabile d'ambiente SSH_PUBKEY per saltare il prompt interattivo:

$ SSH_PUBKEY="ssh-ed25519 AAAA..." wget -O - https://cipi.sh/setup.sh | bash

AWS (login root disabilitato di default)

$ ssh ubuntu@your-server-ip
$ sudo -s
$ wget -O - https://cipi.sh/setup.sh | bash

Alla fine dell'installazione vedrai una schermata riepilogo con i dettagli di accesso SSH, la password root auto-generata e la password root MariaDB. Salvale subito — vengono mostrate una sola volta. Le credenziali sono salvate in /etc/cipi/server.json, che — come tutti i file di configurazione Cipi — è crittografato a riposo con AES-256-CBC via il sistema Vault integrato. Credenziali, chiavi SSH, file .env e dump database sono protetti sia su disco che durante il trasferimento (via archivi crittografati Sync). Cipi applica anche retention log conforme GDPR con policy di rotazione automatica per log applicativi, di sicurezza e HTTP — vedi Retention log per i dettagli.

Accesso post-installazione

Dopo l'installazione, l'accesso admin usa autenticazione a chiave pubblica come utente cipi (login root disabilitato). Gli utenti app possono fare SSH direttamente con ssh myapp@server-ip e la password generata alla creazione dell'app. Per eseguire comandi cipi o qualsiasi task amministrativo, connettiti come cipi e poi escala:

# 1. connect to the server (key-based auth only)
$ ssh cipi@your-server-ip

# 2. escalate to root to run cipi commands
cipi@server:~$ sudo -s

# 3. now you can use all cipi commands
root@server:~# cipi status
root@server:~# cipi app list

# 4. to work as an app user, switch with su
root@server:~# su - myapp

Requisiti

• Ubuntu 24.04 o 26.04 LTS (solo installazioni pulite; le release interim non sono supportate)
• Accesso root (o sudo -s su AWS)
• Porte 22, 80 e 443 aperte
• Un server pulito — non installare Cipi su un server con stack web esistente
• Un server pubblico con accesso internet con indirizzo IPv4 pubblico instradabile — VPS solo NAT, reti domestiche dietro router e host non raggiungibili da internet non sono supportati
• Virtualizzazione KVM completa o bare-metal — non OpenVZ, container LXC o ambienti shared-kernel (inclusi Docker locale, Docker Desktop, OrbStack, Colima, WSL e runtime container desktop simili)

Cipi è testato e funziona su: DigitalOcean, AWS EC2, Vultr, Linode / Akamai, Hetzner, Google Cloud, OVH, Scaleway e qualsiasi host KVM o bare-metal con Ubuntu e IP pubblico.

Avvio rapido

1. Crea la tua prima app

La procedura guidata interattiva chiede username, dominio principale, URL repository Git (formato SSH) e branch quando applicabile, e versione PHP. Le app Laravel richiedono sempre un repository; per app personalizzate puoi lasciare vuoto il repository per ospitare il sito solo via SFTP — vedi app personalizzate. Dalla v5.0, le app Laravel possono usare PHP-FPM classico o Laravel Octane (FrankenPHP) con --octane — vedi Laravel Octane.

$ cipi app create
$ cipi app create --octane   # Laravel Octane (FrankenPHP)

Oppure passa tutti i flag direttamente per saltare la modalità interattiva:

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

Alla fine, Cipi stampa un riepilogo credenziali — salvalo, mostrato una sola volta — inclusi l'indirizzo IP pubblico del server (per configurazione DNS), la chiave deploy SSH, credenziali database, un URL connessione mariadb+ssh:// pronto all'uso per client GUI (TablePlus, DBeaver, Sequel Pro), URL webhook e token webhook.

2. Aggiungi la chiave deploy al tuo provider Git

Se hai configurato un token GitHub o GitLab via cipi git, questo passaggio è automatico — Cipi aggiunge la chiave deploy e crea il webhook per te. Vedi Git auto-setup per i dettagli.

Altrimenti, copia la chiave ssh-ed25519 ... mostrata dopo la creazione dell'app e aggiungila come Deploy Key nel repository:

• GitHub: Repository → Settings → Deploy keys → Add deploy key
• GitLab: Repository → Settings → Repository → Deploy keys

3. Prepara il tuo progetto Laravel

Cipi usa il driver database per cache, sessioni e queue. Esegui questi comandi una volta nel progetto Laravel, fai commit e push delle migration generate:

$ php artisan cache:table
$ php artisan session:table
$ php artisan queue:table
$ php artisan migrate

4. Deploy

$ cipi deploy myapp

Deployer clona il repo in una nuova directory releases/N/, esegue composer install --no-dev, collega .env e storage/, esegue le migration, artisan optimize, crea storage:link, scambia il symlink current atomicamente e riavvia i queue worker. Zero downtime.

5. Installa SSL

$ cipi ssl install myapp

Certbot provisiona un certificato Let's Encrypt, configura Nginx per HTTPS e aggiorna APP_URL in .env. La tua app Laravel è ora live su https://myapp.com.

Tech stack

Cipi porta uno stack completo pronto per la produzione sul tuo server Ubuntu. Ecco tutto ciò che viene installato e configurato:

Struttura app

Quando esegui cipi app create, Cipi crea un ambiente completamente isolato per l'app. Ecco tutto ciò che viene configurato:

/home/myapp/ ← isolated Linux user (chmod 750)
├── .ssh/
│   ├── id_ed25519 ← deploy key (private)
│   └── id_ed25519.pub ← deploy key (public — add to Git)
├── .deployer/
│   └── deploy.php ← Deployer config (auto-generated)
├── current -> releases/3/ ← symlink to active release
├── releases/
│   ├── 1/
│   ├── 2/
│   └── 3/ ← latest release (last 5 kept)
├── shared/
│   ├── .env ← auto-compiled by Cipi
│   └── storage/ ← persistent storage
└── logs/
    ├── nginx-access.log
    ├── nginx-error.log
    ├── php-fpm-error.log
    ├── worker-default.log
    └── deploy.log

Oltre alla home directory, Cipi crea questi file di sistema:

PHP-FPM pool: /etc/php/8.5/fpm/pool.d/myapp.conf (user=myapp; omitted for Octane apps)
Octane (v5+): Supervisor myapp-octane + Nginx proxy_pass → 127.0.0.1:81xx
Nginx vhost:  /etc/nginx/sites-available/myapp
Supervisor:   /etc/supervisor/conf.d/myapp.conf
Crontab:      * * * * * php artisan schedule:run
MariaDB:      database 'myapp', user 'myapp'@'localhost'

Il .env è compilato automaticamente con tutte le credenziali — nome database, password, token webhook e APP_KEY. Non devi mai toccarlo manualmente, ma puoi sempre modificarlo con cipi app env myapp.