🎈devInRed

Installare Strapi V5 su cPanel

Installare Strapi V5 su cPanel

Questo è il primo articolo della nuova sezione TT;DR – Too Technical; Didn’t Read.

Sì, lo so: è fuori target, super tecnico e probabilmente non interesserà a molti.
Ma ho trovato davvero pochissima documentazione chiara su questa operazione, quindi ho deciso di scrivere un articolo per avere una traccia quando dovrò rifarla – e, già che ci sono, togliere le castagne dal fuoco a chi si trova nella mia stessa situazione.

In questo caso: come installare Strapi su cPanel. Let’s go nerd.

Se vuoi migliorare il tuo sito e non ami questioni troppo complesse, puoi sempre andare qui, qui, qui o qui 😉

Premessa

Ho dovuto installare Strapi V5, CMS headless che consiglio vivamente, su un server con cPanel.

Avevo già usato la V4 in passato, ma su Plesk. Quindi partivo con un’idea di massima… ma su cPanel ho trovato diversi intoppi.

Ecco il processo, con tutti i suoi ostacoli e relative soluzioni.

1. Crea (o aggiorna) un repository privato

Può essere su GitHub, GitLab, Bitbucket… quello che preferisci.

Io ho usato GitHub, repo privato, perché devo deployare codice non pubblico.

2. Genera una chiave SSH dal tuo computer

Qui cominciano i problemi. cPanel non permette di generare chiavi senza passphrase, a meno di modifiche alle impostazioni. Ma su uno shared hosting non hai accesso a quelle impostazioni.

Quindi:

1. Genera la chiave dal tuo computer, ma…

2. Errore: la versione di cPanel che avevo non supportava il formato OPENSSH, potresti incorrere nello stesso problema.

3. Soluzione: rigenera la chiave in formato legacy PEM, con questo comando:

ssh-keygen -p -m PEM -f ~/.ssh/id_rsa

4. Ottieni due file, recupera il contenuto con questi due comandi:

cat ~/.ssh/id_rsa       # chiave privata  
cat ~/.ssh/id_rsa.pub   # chiave pubblica

Usare id_rsa come nome per la chiave SSH semplifica la configurazione perché è il nome predefinito cercato da SSH.
Evita di dover specificare il percorso ogni volta che ti connetti.
È anche compatibile out-of-the-box con molti pannelli e client, incluso cPanel.

3. Importa la chiave su cPanel

Vai nella sezione Accesso SSH → Importa chiave e inserisci:

  • Nome: id_rsa
  • Chiave privata: contenuto del file id_rsa
  • Passphrase: lasciata vuota
  • Chiave pubblica: contenuto di id_rsa.pub

4. Aggiungi la chiave su GitHub

Vai nelle impostazioni del tuo account GitHub → SSH and GPG Keys → New SSH Key.

Qui inserisci solo la chiave pubblica, quindi il contenuto di id_rsa.pub.

5. Prepara il dominio o sottodominio

Se non l’hai già fatto, crea un dominio o sottodominio su cPanel.
Io ho creato un sottodominio dedicato e l’ho svuotato completamente (è importante altrimenti non è possibile configurare il repo al punto 6).

Se non sai fare questa parte, fammi sapere: posso scrivere un articolo ad hoc.

6. Collega il repository via Git in cPanel

Vai in Git Version Control su cPanel.

Crea un nuovo repository:

  • Inserisci l’URL SSH del tuo repo privato (non usare https).
  • Specifica la cartella del tuo sottodominio come destinazione.

7. Configura l’app Node.js

Ora vai in Setup Node.js App e crea una nuova app con queste impostazioni:

  • Node version: 20.x.x
  • Application root: la cartella del tuo sottodominio
  • Application URL: quello scelto in fase di creazione
  • Startup file: server.js (lo creiamo nel prossimo punto)

Salva, poi clicca:

  • Run NPM install
  • Run JS script → seleziona Build

Attendi l’esecuzione dei due processi, potrebbe volerci qualche minuto.

8. Crea il file server.js

Dentro la cartella root della tua app, crea un file server.js con questo contenuto:

const { createStrapi } = require('@strapi/strapi');

(async () => {
  try {
    const app = await createStrapi({ distDir: './dist' });
    await app.start();
  } catch (err) {
    console.error('Errore durante l\'avvio di Strapi:', err);
    process.exit(1);
  }
})();

❗ Attenzione: non inserire log fuori dal blocco catch.
Altrimenti Node penserà che lo script finisca subito e tenterà di rilanciarlo ad ogni caricamento.

9. Prepara il file .env

Se usi Strapi con un DB mysql, o con Stripe o altre integrazioni, avrai sicuramente un file .env locale.

Questo file non sarà presente nel repo (grazie .gitignore), quindi copialo manualmente nella root del tuo progetto.

Verifica e modifica:

  • URL dell’applicazione (APP_URL)
  • Credenziali del database
  • Chiavi varie di configurazione

Se non hai ancora creato un database online:

  • Crealo via cPanel
  • Crea utente e assegna i permessi
  • Importa il dump del DB locale

10. Avvia (o riavvia) l’app

Torna nella sezione Setup Node.js App, clicca su Start App (o Restart, se già attiva).

Considerazioni finali

Il processo in sé è piuttosto lineare, ma ci sono alcuni dettagli critici:

  • Serve una chiave SSH legacy, non in formato OpenSSH
  • cPanel non ti permette di scegliere la chiave da usare, quindi è bene usare id_rsa
  • Lo script server.js deve avviare Strapi dalla cartella dist, specialmente se usi TypeScript, perché Node non interpreta direttamente i file .ts.

Hai bisogno di una mano per Installare Strapi V5 su cPanel?

Se ti sei ritrovato in questo articolo per caso e sei arrivato fin qui… probabilmente ti sei imbattuto negli stessi problemi.
Se vuoi evitare di perdere ore tra debug, configurazioni e workaround, posso aiutarti.

Offro consulenze tecniche personalizzate, anche per setup “non standard” come questo.

👉 Scopri come funziona la consulenza

[ads_loop]

More posts