Déployer le Headless CMS Strapi 5 sur le CPanel de O2switch

Dans ce tutoriel, nous allons voir les étapes clés pour déployer une application Strapi sur CPanel en Typescript. Par défaut, Strapi utilise SQLite comme base de données, ce qui est pratique pour le développement local mais présente des limitations en production (notamment en termes de concurrence). Nous allons donc migrer vers MySQL, configurer les règles CORS, et déployer l’application sur CPanel en utilisant un accès SSH avec PuTTY.
On partira du principe que Strapi et la partie “admin” se trouvera au même endroit (comportement par défaut).

Préparation : Passage de SQLite à MySQL

1. Créer une base de données MySQL sur CPanel

• Connectez-vous à votre CPanel
• Accédez à la section Bases de données MySQL®
• Créez une nouvelle base de données et assignez-lui un utilisateur avec les permissions appropriées

2. Configurer Strapi pour utiliser MySQL

Ouvrez le fichier config/ database.ts et assurez-vous qu’il contient une configuration pour MySQL :

mysql: {
  connection: {
    host: env('DATABASE_HOST', 'localhost'),
    port: env.int('DATABASE_PORT', 3306),
    database: env('DATABASE_NAME', 'strapi'),
    user: env('DATABASE_USERNAME', 'strapi'),
    password: env('DATABASE_PASSWORD', 'strapi'),
    ssl: env.bool('DATABASE_SSL', false) && {
      key: env('DATABASE_SSL_KEY', undefined),
      cert: env('DATABASE_SSL_CERT', undefined),
      ca: env('DATABASE_SSL_CA', undefined),
      capath: env('DATABASE_SSL_CAPATH', undefined),
      cipher: env('DATABASE_SSL_CIPHER', undefined),
      rejectUnauthorized: env.bool('DATABASE_SSL_REJECT_UNAUTHORIZED', true),
    },
  },
  pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
},

Configurez les variables d'environnement dans le fichier `.env.production` :

# Database mysql
DATABASE_CLIENT=mysql
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_NAME=NOM_DE_VOTRE_BDD
DATABASE_USERNAME=UTILISATEUR_INSCRIT_A_LA_BDD
DATABASE_PASSWORD=MOT_DE_PASSE_UTILISATEUR
DATABASE_SSL=false

Installez les dépendances nécessaires (mysql2 ici) :

npm install mysql2
npm install --save-dev @types/node  // Si vous utilisez TypeScript

Configuration des Middlewares CORS

La configuration de strapi::cors permet de gérer les règles CORS (Cross-Origin Resource Sharing) pour votre API Strapi. Elle définit les domaines externes autorisés à interagir avec votre API Strapi via des requêtes HTTP (comme GET, POST, PUT, DELETE, etc.).

Par exemple, si vous avez un sous-domaine comme « blog.mon-site-internet.fr », celui-ci devra être explicitement autorisé pour interagir avec votre application Strapi hébergée sur « api.blog.mon-site-internet.fr ».
Veillez à respecter l’ordre des paramètres dans ce fichier pour garantir un fonctionnement optimal.

Configurez les règles CORS dans le fichier config/ middlewares.ts :

export default [
  'strapi::cors', // Active CORS
  {
    name: 'strapi::cors',
    config: {
      origin: ['http://localhost:3000', 'https://blog.mon-site-internet.fr', process.env.FRONT_END_URL],
      methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
      headers: ['Content-Type', 'Authorization', 'Origin', 'Accept'],
      keepHeaderOnError: true,
    },
  },
];

Build de l’application

Si vous êtes sur une solution d’hébergement mutualisée, vous serez sans doute dans l’obligation de build votre application en local avant de l’importer.
La raison vient d’une restriction de la mémoire utilisable.

1. Créez un build de production (génère un dossier dist) :

   npm run build
   

2. Téléversez le contenu du dossier dist sur votre serveur CPanel dans un dossier dédié.
   Rappel : ne pas utiliser ‘www’ ou ‘public_html’ pour des raisons de sécurité.

3. Ajoutez les fichiers suivants au dossier :

   • server.js :

   const strapi = require('@strapi/strapi');
   strapi.createStrapi({ distDir: './dist' }).start();
   

   • Le fichier .env.production renommé en .env
   • Le fichier package.json

Pour le fichier ‘.env’, vous pouvez installer la librairie dotenv et ajouter cette ligne dans la partie script du fichier package.json :

"production": "npm run build --dotenv .env.production"

Ensuite, au lieu de faire “npm run build”, faites à la place “npm run production”. Cela permettra normalement (pas 100 % fiable) de faire un build avec le fichier .env.production. Si vous rencontrez des problèmes étranges pour exécuter votre projet Strapi, renommez plutôt le fichier .env.production en .env

Si vous avez une erreur à cause de better-sqlite3 et que vous utilisez mysql, vous pouvez le retirer du fichier package.json avant de build.

Accès SSH avec PuTTY

Pour les mêmes raisons que nous devons build l’application en local, pour ne pas être pénalisés par un manque de mémoire depuis le terminal de CPanel, il faut passer par un accès SSH, que nous allons configurer ci-dessous.

1. Installer PuTTY

Nous allons utiliser l’outil PuTTY qui est un client SSH comprenant différents outils afin de vous permettre de gérer et d’interagir avec vos sessions SSH.
Vous pouvez vous aider en parallèle de cette vidéo Youtube : ici

• Téléchargez la dernière version de PuTTY depuis le site officiel (ici)
• Installez PuTTY sur votre ordinateur

2. Générer une clé SSH dans CPanel

1. Connectez-vous à votre CPanel
2. Accédez à la section Accès SSH > Gérer les clés SSH
3. Cliquez sur Générer une nouvelle clé
4. Donnez un nom à votre clé (par exemple, testkey)
5. Utilisez le Générateur de mots de passe pour créer un mot de passe sécurisé
6. Cliquez sur Générer une clé
7. Autorisez la clé publique en cliquant sur Gérer puis sur Autorize

3. Télécharger et convertir la clé privée

1. Téléchargez la clé privée
2. Ouvrez PuTTYgen
3. Importez la clé privée via Conversions > Import Key
4. Entrez le mot de passe généré
5. (Optionnel) Supprimez le mot de passe pour plus de simplicité
6. Sauvegardez la clé au format .ppk

4. Configurer PuTTY pour se connecter au serveur

1. Dans la catégorie Session :
   • Entrez l’adresse : nomUtilisateur@ip_du_serveur
     Le nom et l’ip du serveur sont visibles au même endroit depuis l’écran d’accueil de CPanel.
   • Port : 22 (défaut)
2. Dans Connection > SSH > Auth :
   • Sélectionnez votre clé privée .ppk
3. Sauvegardez la configuration
4. Lancez la connexion

5. Résolution des problèmes de connexion

En cas de « connection timed out », il peut être nécessaire d’ajouter une autorisation supplémentaire dans la section « Autorisation SSH » de cPanel.

• Vérifiez que votre IP est autorisée dans CPanel (Autorisation SSH)
• Consultez votre adresse IP sur WhatIsMyIPAddress par exemple, pour effectuer l’étape précédente

Création de l’application Node.js sur CPanel

1. Accédez à la section Setup Node.js App dans CPanel
2. Créez une nouvelle application Node.js
3. Configurez l’application selon les instructions de CPanel

Mettez de côté l’URL indiquée sous « Enter to the virtual environment. To enter the virtual environment, run the command ».
Une fois connecté à votre terminal SSH, il vous suffira de la coller.

Transfert des données SQLite vers MySQL

Cette commande va créer un fichier « gz » non crypté afin de faciliter l’import.
Ce fichier contient les informations suivantes :

• La configuration du projet
• Les différentes entités et leur contenu
• Les relations entre les entités
• Les fichiers « assets » présents dans le dossier « uploads »
• Les schémas
• Le fichier metadata.json

Exportez les données locales :

npm run strapi export -- --no-encrypt

Importez les données sur le serveur :

npm run strapi import -- -f monFichierUploader.tar.gz

Il est possible que vous rencontriez des problèmes (par exemple, un « time out ») à cette étape, notamment en raison de la taille de votre dossier uploads . Vous devrez peut-être importer votre contenu en plusieurs étapes (configuration, contenu et fichiers).

Vous trouverez des informations à ce sujet depuis la documentation officielle ici

Vous pouvez aussi ajouter manuellement le contenu de votre dossier uploads directement vous-même sur votre serveur après l’installation de strapi.

Si vous faites une MAJ qui nécessite de réinstaller strapi, vous pouvez aussi remettre à la main le contenu de votre fichier uploads directement sur votre serveur.

Si vous n’avez pas touché à la base de données de votre serveur, vous n’aurez sans doute qu’à vous soucier du dossier uploads.

Faire une sauvegarde de votre base de données mysql pour restaurer strapi sera sans doute plus fiable que d’utiliser les commandes dédiées de strapi.

Si vous avez déjà votre projet en ligne et que vous souhaitez simplement faire des mises à jours, vous n’aurez

Mise en place de l’application via SSH

1. En premier, on installe les dépendances :

   npm install
   

2. En deuxième, on construit le panneau d’administration :

   npm run build
   

3. Pour finir, on démarre Strapi :

   npm run start
   

Il faudra peut-être utiliser « NODE_ENV=production » devant npm pour build et start.

Si vous avez l’erreur Cannot destructure property ‘client’ of ‘db.config.connection’ as it is undefined, elle peut avoir plusieurs origines.
Si vous avez bien configuré les fichiers “database.ts” et “.env”, alors le problème peut venir de “tsconfig.ts”.
Je pense que ces commandes sont importantes : checkJs allowJs strict skipLibCheck.

Le tsconfig.ts :

{
"compilerOptions": {
 "module": "CommonJS",
 "moduleResolution": "Node",
 "lib": ["ES2020"],
 "target": "ES2019",
 "strict": false,
 "allowJs": true, // Allow JavaScript files to be compiled
 "checkJs": false, // Disable checking JavaScript files
 "skipLibCheck": true,
 "forceConsistentCasingInFileNames": true,
 "incremental": true,
 "esModuleInterop": true,
 "resolveJsonModule": true,
 "noEmitOnError": true,
 "noImplicitThis": true,
 "outDir": "dist",
 "rootDir": ".",
},
"include": [
 // Include root files
 "./",
 // Include all ts files
 "./**/*.ts",
 // Include all js files
 "./**/*.js",
 // Force the JSON files in the src folder to be included
 "src/**/*.json"
],

"exclude": [
 "node_modules/",
 "build/",
 "dist/",
 ".cache/",
 ".tmp/",

 // Do not include admin files in the server compilation
 "src/admin/",
 // Do not include test files
 "**/*.test.*",
 // Do not include plugins in the server compilation
 "src/plugins/**"
]
}

Ensuite, il y a de fortes chances pour que vous soyez obligé de mettre ce fichier avec les autres sur votre serveur avant de lancer la commande “npm install”.

Si vous avez une erreur error: Missing jwtSecret. Please, set configuration variable “jwtSecret” c’est que vous avez oublié de générer votre clé ‘JWT_SECRET’ dans votre fichier env .

Pour générer une clé sur windows :

1. Lancer une invite de commande windows (cmd)
2. Exécuter la commande node
3. Et récupérer le résultat de cette commande :

   require('crypto').randomBytes(16).toString('base64')
   

Vous obtiendrez une clé aléatoire de ce format : FDFw9kjCexz89KpLhrBP3A==

Vous pouvez aussi utiliser Windows Powershell et cette commande : node -e “console.log(require(‘crypto’).randomBytes(16).toString(‘base64’))”

En cas de problème, il est recommandé de garder une copie de htaccess qui pourrait changer.
Par exemple, si vous voulez forcer HTTPS et de ne pas passer par “www” :

# Force www to non-www
<IfModule mod_rewrite.c>
 RewriteEngine On
 RewriteCond %{HTTP_HOST} ^www\.(.*)$ [NC]
 RewriteRule ^(.*)$ https://%1/$1 [L,R=301]
</IfModule>

# Force HTTPS redirection
<IfModule mod_rewrite.c>
 RewriteEngine On
 RewriteCond %{HTTPS} off
 RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</IfModule>

Conclusion

Avec ces étapes détaillées, vous devriez être en mesure de configurer PuTTY pour accéder à votre serveur via SSH, migrer de SQLite à MySQL, et déployer votre application Strapi sur CPanel.
Si vous avez réussi à déployer votre application sans trop de problèmes, vous avez de la chance :)
N’hésitez pas à regarder vos logs passenger afin de vous aider.