Pannello di controllo (GUI)

Il pannello di controllo web opzionale

Cipi è, e resterà sempre, CLI-first. Tutto ciò che un server richiede — app, database, SSL, deploy, backup, firewall — è a un solo comando cipi via SSH. Ma dalla v4.7.0 Cipi include anche un opzionale pannello di controllo web: una dashboard Laravel self-hosted che gestisce uno o più server Cipi dal browser, sulla stessa REST API usata dal client CLI e dal modulo WHMCS.

Il pannello è un sottile layer visuale sopra l'API — non sostituisce la CLI né aggiunge un control plane proprietario. Qualsiasi cosa fai nel browser, puoi farla ancora dal terminale, e viceversa. Un singolo pannello può guidare molti server, quindi funge anche da cockpit multi-server leggero.

Cosa puoi fare dal pannello

• Gestisci le app — crea, modifica, fai deploy, sospendi/riattiva ed elimina app Laravel e custom; gestisci alias, redirect WWW/apex, SSL (installa + forza HTTPS) e autenticazione HTTP basic.
• Crea app Laravel con Laravel Octane (FrankenPHP) opzionale (API 1.13+ / Cipi 5.0+); le viste list e detail mostrano FPM vs Octane.
• Scegli un motore database alla creazione app (mariadb o pgsql) e gestisci database multi-engine (API 1.12+ / Cipi 4.8+).
• Sfoglia log applicazione e server con filtro tipo, paginazione e auto-refresh.
• Monitora i job asincroni in un overlay interattivo (spinner + output terminale mentre fa polling su GET /api/jobs/{id}).
• Dashboard live — CPU, memoria, disco, servizi e conteggio app via GET /api/status.
• Registra e passa tra più server da un unico login.

Pannello di controllo (GUI)

Requisiti

Il pannello comunica con i tuoi server esclusivamente tramite la Cipi REST API. Prima di installarlo, assicurati che ogni server che vuoi gestire abbia l'API abilitata con un token che copre l'intero set di ability.

• Un server Cipi attivo (Ubuntu 24.04 / 26.04) per ospitare il pannello — può essere uno dei server che gestisci o una piccola macchina dedicata.
• Un dominio (o sottodominio) puntato a quel server, es. panel.example.com.
• cipi api abilitato su ogni server che vuoi controllare, ciascuno con un token full-ability (includi www-manage e status-view). Per create Octane e indicatori FPM/Octane, i server gestiti richiedono API 1.13+ e Cipi 5.0+. Per MariaDB/PostgreSQL multi-engine e redirect www, API 1.12+ e Cipi 4.8+.

PHP, il pool FPM, il vhost Nginx e lo scheduler sono tutti provisionati dall'installer — non configuri un ambiente Laravel a mano.

Pannello di controllo (GUI)

Installazione — cipi gui <domain>

Un comando provisiona l'intero pannello su un server Cipi: un pool PHP-FPM dedicato, un vhost Nginx per il tuo dominio e un job cron scheduler. L'app Laravel è bundled in /opt/cipi/gui, lo stesso modello usato dal package cipi-api.

cipi gui panel.example.com

L'installer chiede interattivamente il primo account amministratore — email e password. La password deve soddisfare la policy del pannello:

• Minimo 12 caratteri.
• Almeno una maiuscola, una minuscola, una cifra e un carattere speciale.
• Non più di 4 caratteri identici consecutivi.

La configurazione è scritta in /etc/cipi/gui.json. Quando il comando termina, apri il tuo dominio nel browser e accedi con l'account admin appena creato.

Pannello di controllo (GUI)

SSL — cipi gui ssl

Emetti un certificato Let's Encrypt gratuito per il dominio del pannello e passalo a HTTPS. Il pannello è HTTPS-aware e imposta gli header forwarded corretti dietro il vhost Nginx Cipi.

cipi gui ssl

Il certificato si rinnova automaticamente tramite lo stesso rinnovo ACME che Cipi usa per i domini app.

Pannello di controllo (GUI)

Autenticazione a due fattori (TOTP)

Il pannello usa login session classico e supporta autenticazione a due fattori TOTP opzionale. Ogni amministratore può registrare un'app authenticator (Google Authenticator, 1Password, Aegis, …) dal proprio profilo. Il 2FA è opt-in per utente, non obbligatorio.

Se un amministratore perde accesso al secondo fattore, un operatore con accesso shell può azzerarlo dal server con cipi gui reset-user, che riscrive l'account e rimuove l'iscrizione 2FA.

Pannello di controllo (GUI)

Aggiornamento — gui update vs gui upgrade

Il pannello è distribuito come package Composer cipi/gui, quindi gli aggiornamenti sono normali aggiornamenti Composer più migration. Due comandi coprono i casi comuni:

cipi gui update — aggiornamento soft

Esegue composer update cipi/gui, applica migration database e aggiorna il tema compilato. È il percorso di aggiornamento quotidiano.

cipi gui update

cipi gui upgrade — rebuild completo

Ricostruisce il pannello da zero. Usalo dopo una release major, o se un ambiente ha derivato e una reinstall pulita del codice app è il modo più veloce per tornare a uno stato noto.

cipi gui upgrade

cipi gui refresh-theme — solo tema

Ricompila e ricarica il tema del pannello senza toccare codice o database — utile dopo una modifica al tema.

cipi gui refresh-theme

Pannello di controllo (GUI)

Operazioni

cipi gui status

Riporta lo stato attuale del pannello — se è installato, il suo dominio e lo stato dei suoi servizi.

cipi gui status

cipi gui fix-permissions

Ripara la restrizione PHP-FPM open_basedir del pannello e tutti i permessi file runtime. Eseguilo se il pannello inizia a lanciare errori di permesso o autoload dopo un aggiornamento.

cipi gui fix-permissions

cipi gui reset-user

Riscrive email, nome e password di un amministratore e azzera la sua iscrizione 2FA — il percorso di recovery quando qualcuno è bloccato fuori. reset-password è un alias dello stesso comando.

cipi gui reset-user

Pannello di controllo (GUI)

Rimozione del pannello — cipi gui remove

Disinstalla il pannello e il suo vhost Nginx, pool PHP-FPM e scheduler. I tuoi server e app restano intatti — il pannello è solo un client dell'API. uninstall è un alias, e --force salta il prompt di conferma.

cipi gui remove
cipi gui remove --force

Rimuovere il pannello è l'espressione definitiva della sua optionalità: disinstallalo in qualsiasi momento e Cipi torna a una CLI pura, esattamente com'era prima.

Pannello di controllo (GUI)

Architettura

Il pannello è un'applicazione Laravel 12 standard distribuita come package cipi/gui dal proprio repository (cipi-sh/gui) e installata via entry Composer VCS che traccia dev-main. Vive in /opt/cipi/gui, speculare a come il package cipi-api è bundled.

Poiché non tiene queue worker locali e non salva stato server proprio, il pannello resta stateless rispetto alla tua infrastruttura: si autentica all'API di ogni server, invia job e ne interroga lo stato. Smonta il pannello e ricostruiscilo altrove senza toccare un singolo server gestito.

Copertura API

La GUI consuma l'intera superficie OpenAPI della Cipi API. Tieni aggiornati il pannello e il package cipi/api di ogni server gestito (cipi gui update / cipi api update) così i form di creazione e i campi list corrispondono al server.