Passare da cPanel a Koapanel senza cambiare WHMCS

26 settembre 2026 · lettura 9 min · Koapanel

Se fatturi con WHMCS, puoi lasciare cPanel senza rifare clienti, fatture, prodotti e automazioni: WHMCS parla con i pannelli tramite moduli server, e per Koapanel esiste un modulo ufficiale che fa le stesse operazioni di quello per cPanel. Il lavoro vero è installare il modulo, aggiungere un server, creare i prodotti corrispondenti e poi spostare i servizi esistenti uno alla volta, con la migrazione di Koapanel e un piano per tornare indietro.

Perché si può fare: i moduli server di WHMCS

WHMCS non sa nulla di cPanel in sé. Ogni prodotto di hosting è collegato a un modulo di provisioning (server module) e a un server o gruppo di server: quando un ordine viene pagato, una fattura resta scoperta o un cliente fa un upgrade, WHMCS chiama le funzioni del modulo (creare, sospendere, riattivare, terminare, cambiare pacchetto o password). Vedi la documentazione per sviluppatori sui moduli di provisioning e l'elenco delle funzioni supportate.

Da qui una conseguenza pratica: clienti, contratti, cicli di fatturazione, promozioni, gateway di pagamento, regole di sospensione e ticket restano dove sono. Cambia solo a quale modulo e a quale server punta ogni servizio.

Cosa fa il modulo Koapanel per WHMCS

Il modulo koapanel funziona con WHMCS 8.x e 9.x e con Koapanel 0.21.0 o successivo. Ecco cosa succede sul pannello per ogni comando di WHMCS:

Alcuni dettagli che contano nel lavoro di tutti i giorni:

• Creazione idempotente: se WHMCS ripete «Crea» sullo stesso servizio (per esempio dopo un timeout), non nascono doppioni.
• Password e nomi utente corretti in automatico: se la password di WHMCS è troppo debole per il pannello (almeno 12 caratteri, 5 diversi) il modulo ne genera una forte e la salva nel servizio; se il nome utente non rispetta le regole (3–32 caratteri a-z 0-9 . _ -) lo corregge e lo salva.
• Collegamenti rapidi nell'area clienti: il servizio mostra Pannello, File, WordPress, Email, Database, e ognuno porta il cliente dritto in quella sezione. Un account sospeso non riceve link di accesso.
• Prodotti rivenditore: con «Tipo di account» = Rivenditore il modulo crea un rivenditore sul pannello, e i limiti del prodotto diventano la sua quota (account, spazio, siti, caselle).
• Pacchetti automatici: se nel prodotto lasci vuoto il pacchetto, il modulo crea sul pannello un pacchetto con i limiti indicati (per esempio «WHMCS 3s-10g-5d-20m») e lo riusa per i servizi uguali.
• Opzioni configurabili chiamate Siti, Spazio disco (GB), Database, Caselle email, Account permettono al cliente di scegliere i limiti.

Il modulo usa una chiave API del pannello, con al massimo 300 richieste al minuto per chiave. Ogni operazione compare nel Registro attività del pannello con «con API key WHMCS …», e in WHMCS i dettagli di ogni chiamata finiscono in Utilità › Log › Log dei moduli (senza chiavi né password). La pagina Koapanel e WHMCS e il capitolo del manuale WHMCS e chiavi API riassumono tutto.

Passo 1: crea la chiave API nel pannello

Entra in Koapanel come amministratore e apri Chiavi API › Crea chiave (nome, per esempio, «WHMCS»). Copia subito la chiave kpk_…: viene mostrata una sola volta.

Una chiave agisce come il suo account. La chiave di un rivenditore crea account solo tra i suoi clienti, con i suoi pacchetti e dentro la sua quota; per vendere prodotti rivenditore serve la chiave di un amministratore.

Passo 2: installa il modulo in WHMCS

Scarica lo zip e scompattalo nella cartella principale di WHMCS (qui /var/www/whmcs, adatta il percorso al tuo):

cd /tmp
curl -fsSLO https://console.koapanel.app/updates/integrations/koapanel-whmcs-1.0.0.zip
unzip koapanel-whmcs-1.0.0.zip -d koapanel-whmcs
sudo cp -r koapanel-whmcs/modules/servers/koapanel /var/www/whmcs/modules/servers/
# solo se rivendi licenze Koapanel:
sudo cp -r koapanel-whmcs/modules/servers/koapanel_license /var/www/whmcs/modules/servers/

Non serve altro: WHMCS riconosce i moduli da solo. Requisiti lato WHMCS: PHP 8.1 o successivo con curl, json e mbstring (WHMCS 9.0 richiede PHP 8.2 o 8.3), e il server WHMCS deve raggiungere il pannello sulla porta 8443. La guida completa è anche nel file README.md dentro lo zip.

Passo 3: aggiungi il server

In Impostazioni di sistema › Server › Aggiungi nuovo server:

Premi Test connessione: deve rispondere «Connessione riuscita». Salva e metti il server in un gruppo di server.

Passo 4: crea i prodotti (o duplica quelli di cPanel)

Il modo più rapido per non perdere prezzi, cicli, email di benvenuto e opzioni è duplicare i prodotti cPanel esistenti e cambiare solo la scheda Impostazioni modulo: Modulo Koapanel, il nuovo gruppo di server e le opzioni del modulo.

Consiglio pratico: prima crea sul pannello i pacchetti equivalenti ai piani che vendi oggi, poi collegali ai prodotti. Nascondi i vecchi prodotti cPanel dal carrello quando i nuovi ordini devono andare su Koapanel.

A questo punto i nuovi ordini vengono già creati su Koapanel. Restano i clienti esistenti.

Passo 5: sposta i clienti esistenti, un servizio alla volta

Per ogni servizio ci sono due lavori distinti: portare i dati (siti, database, posta) dal server cPanel al server Koapanel, e far puntare il servizio WHMCS al nuovo server. L'ordine che ti suggeriamo:

1. Collega il servizio al nuovo server. Nel profilo del cliente, scheda Prodotti/Servizi, cambia il campo Prodotto/Servizio con il prodotto Koapanel equivalente e il campo Server con il server Koapanel, poi salva. Il modulo usato è quello del prodotto, quindi il cambio di prodotto è ciò che sposta il servizio sul modulo Koapanel. Controlla che l'importo ricorrente e la data di scadenza non siano cambiati.
2. Crea l'account vuoto. Nella sezione Comandi modulo premi Crea: il modulo crea l'account sul pannello con lo stesso nome utente del servizio (i nomi utente di cPanel di solito rispettano già le regole di Koapanel; se no, il modulo li corregge e salva il nuovo nome nel servizio). Se la password salvata è troppo debole, il modulo ne genera una nuova e la salva nel servizio: tienilo presente quando scrivi al cliente.
3. Porta i dati. Con la migrazione di Koapanel importi il backup completo dell'account cPanel scegliendo come destinazione l'account appena creato; con la migrazione via SSH il pannello si collega da solo al server cPanel, anche come root, ed elenca gli account da portare. Vengono importati siti, file, database (con password nuove, riscritte in wp-config.php), caselle email con messaggi e password originali se il servizio di posta è attivo, e i cron in pausa.
4. Cambia i DNS dopo la sincronizzazione finale (disponibile per 7 giorni con la migrazione via SSH), con il TTL abbassato il giorno prima.

Queste indicazioni seguono il funzionamento generale di WHMCS descritto nella documentazione della scheda Prodotti/Servizi: verifica sulla documentazione della tua versione, e fai una prova su un servizio interno prima dei clienti veri. Controlla anche che il pacchetto del prodotto sia abbastanza grande per i dati: la migrazione rispetta i limiti del pacchetto e lo spazio libero su disco. Per i dettagli sulla parte cPanel c'è la guida Migrare da cPanel.

Checklist di prova per ogni servizio

• «Accedi» dall'area admin e dall'area clienti apre il pannello; i collegamenti rapidi File, WordPress, Email e Database funzionano.
• I siti rispondono dal nuovo server (prova con il file hosts prima del cambio DNS) e il report di migrazione non segnala errori.
• Le caselle ricevono e inviano posta, con MX, SPF e DKIM pubblicati.
• Sospendi e Riattiva da WHMCS funzionano (fallo su un servizio di prova, non su un cliente).
• Cambia pacchetto applica i nuovi limiti; il giorno dopo WHMCS mostra lo spazio usato aggiornato.
• Il Log dei moduli di WHMCS non riporta errori.

Piano di rollback

Il vantaggio di questo approccio è che finché non tocchi il vecchio server puoi tornare indietro:

• Non eliminare l'account cPanel fino a quando il servizio non ha passato almeno un ciclo senza problemi. Dopo il cambio, WHMCS non lo gestisce più: lo cancellerai tu da WHM alla fine.
• Annota prodotto e server originali di ogni servizio. Per tornare indietro rimetti i vecchi valori nella scheda Prodotti/Servizi e riporta i DNS al vecchio indirizzo (con il TTL basso, il ritorno è rapido).
• Non usare Termina sul servizio durante la prova: su Koapanel elimina l'account e i siti.

Come comunicarlo ai clienti

Un cambio di pannello è un cambio visibile: scrivi prima. Spiega data e finestra del cambio, cosa resta uguale (fattura, prezzo, area clienti WHMCS, indirizzi email) e cosa cambia (l'interfaccia del pannello, niente .htaccess perché il server usa nginx, SFTP al posto dell'FTP). Ricorda che si entra dall'area clienti con un clic, e che le password dei database cambiano ma i siti WordPress sono già aggiornati.

Rivendi licenze? Il modulo koapanel_license

Se sei un provider partner e vuoi vendere licenze Koapanel ai tuoi clienti (per esempio a chi ha un VPS), nello stesso zip c'è il modulo koapanel_license. Serve una chiave partner kpp_… che Koapanel rilascia ai partner. Aggiungi un server con Hostname console.koapanel.app, Modulo Koapanel Licenze, Password = chiave partner, SSL, porta 443; poi un prodotto di tipo «Altro» con il Piano (Starter, Pro, Agency…). Alla creazione il modulo emette la licenza e salva nel servizio il codice di attivazione, che il cliente vede nell'area clienti. Sospendi, Riattiva, Termina e Cambia pacchetto funzionano, e Libera per un altro server sgancia la licenza per attivarla altrove. Condizioni e prezzi all'ingrosso sono nella pagina provider.

I limiti, detti chiaramente

• Koapanel gira solo su Ubuntu 24.04 LTS con nginx: niente Apache né .htaccess, niente LiteSpeed, niente CloudLinux. Se i tuoi clienti dipendono da regole .htaccess complesse, vanno tradotte in nginx.
• Il modulo richiede WHMCS 8.x o 9.x, PHP 8.1+ e Koapanel 0.21.0 o successivo.
• La migrazione dell'account è di Koapanel, non di WHMCS: il cambio del servizio in WHMCS va fatto a mano, servizio per servizio.

Se ti servono Apache o CloudLinux, cPanel resta la scelta più adatta; se il motivo del cambio sono i prezzi di cPanel, vale la pena fare due conti.

Domande frequenti

Devo reimportare i clienti in WHMCS?

No. Clienti, fatture e servizi restano in WHMCS; cambi solo prodotto e server di ogni servizio e crei i nuovi prodotti con il modulo Koapanel.

Posso tenere cPanel e Koapanel insieme durante il passaggio?

Sì. Sono due server con due moduli diversi nello stesso WHMCS: puoi spostare i servizi un po' alla volta e mandare i nuovi ordini su Koapanel.

Cosa succede se WHMCS ripete la creazione di un account?

Il modulo è idempotente: ripetere «Crea» sullo stesso servizio non crea un secondo account.

Posso vendere hosting rivenditore da WHMCS?

Sì, con «Tipo di account» = Rivenditore e la chiave API di un amministratore. Vedi anche rivenditori e la guida diventare rivenditore di hosting.

Prova prima su un server di test

Installa Koapanel gratis su un Ubuntu 24.04 nuovo con curl -fsSL https://get.koapanel.app | sudo bash, collegalo a una copia di prova di WHMCS e sposta un servizio interno. Se gestisci più server, guarda le condizioni per i provider o contattaci per organizzare il passaggio.