Comment installer ESX ou QBCore sur un serveur FiveM
Choisissez entre ESX Legacy et QBCore, préparez la base MariaDB, déployez le framework avec txAdmin sur votre serveur Linux, vérifiez le résultat et revenez en arrière si besoin.
Sur cette page
Vos valeurs
Renseignez-les une fois, les commandes du guide se mettent à jour.
ESX Legacy et QBCore sont des frameworks de roleplay : ils ajoutent à FiveM les personnages, les métiers, l'argent et l'inventaire. Ce guide vous aide à choisir entre les deux, puis à en déployer un avec txAdmin, sans perdre votre configuration actuelle.
Prérequis
- Un serveur installé avec le guide Créer un serveur FiveM : utilisateur
fivem, servicefivem.service, script/usr/local/sbin/backup-fivem.sh - MariaDB installée, avec la base
fivemet l'utilisateurfivemcréés dans la section MariaDB de ce guide - Le mot de passe de cet utilisateur MariaDB
- Votre clé de licence
cfxk_et un compte administrateur txAdmin principal
Choisir entre ESX et QBCore
Les deux frameworks répondent au même besoin. Le critère décisif est la liste des ressources que vous comptez utiliser : une ressource écrite pour l'un ne fonctionne pas telle quelle sur l'autre.
| Critère | ESX Legacy | QBCore |
|---|---|---|
| Déploiement dans txAdmin | Popular Recipes, recette ESX Legacy | Remote URL Template, avec l'adresse de la recette |
| Ressource principale | es_extended |
qb-core |
| Dépendances principales | oxmysql, esx_lib |
oxmysql |
| Table des joueurs | users |
players |
| Droits des joueurs | Groupes enregistrés en base, modifiés avec setgroup |
Niveaux god, admin et mod, gérés par des permissions ACE |
| OneSync | Activé par la recette | Activé par la recette |
| Documentation | docs.esx-framework.org | qbcore.org/docs |
Pour décider :
- Prenez ESX Legacy si vous voulez suivre le chemin proposé directement par txAdmin, ou si vos ressources visées sont écrites pour ESX.
- Prenez QBCore si vos ressources visées sont écrites pour QBCore, ou si votre équipe le connaît déjà.
- Regardez aussi Qbox si vous hésitez du côté de QBCore : txAdmin propose sa recette dans Popular Recipes et la présente comme compatible avec les ressources QBCore. Ce guide ne détaille pas son installation.
Changer de framework plus tard revient à repartir de zéro : les tables, les fonctions et les ressources diffèrent. N'installez jamais les deux sur le même serveur.
Étape 1 : sauvegarder le serveur
Lancez le script de sauvegarde et vérifiez que les archives sont bien créées :
sudo /usr/local/sbin/backup-fivem.sh
sudo ls -lh /home/fivem/backupsNotez la date des deux derniers fichiers, fivem_DATE.tar.gz et fivem_db_DATE.sql.gz. Ils serviront au retour arrière.
Étape 2 : préparer la base de données
Vérifiez que MariaDB fonctionne et comptez les tables de la base fivem :
sudo systemctl is-active mariadb
sudo mariadb -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='fivem';"- Le résultat est
0: la base est vide, utilisezfivemet passez à l'étape 3. - Le résultat est supérieur à
0: la base contient déjà des données. Créez-en une autre pour le framework, comme ci-dessous.
sudo mariadbCREATE DATABASE fivem_rp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON fivem_rp.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;
EXIT;Indiquez ensuite cette base au script de sauvegarde, sinon elle ne sera pas sauvegardée :
sudo sed -i 's/^DB_NAME="fivem"$/DB_NAME="fivem_rp"/' /usr/local/sbin/backup-fivem.sh
sudo grep '^DB_NAME' /usr/local/sbin/backup-fivem.shDans la suite, remplacez fivem par fivem_rp lorsqu'il s'agit du nom de la base.
Si vous avez perdu le mot de passe, générez-en un avec openssl rand -hex 16, puis appliquez-le dans sudo mariadb :
ALTER USER 'fivem'@'localhost' IDENTIFIED BY 'MOT_DE_PASSE_GENERE';Si un serveur existant utilise déjà ce compte, mettez aussi à jour sa ligne mysql_connection_string.
Étape 3 : revenir à l'assistant de txAdmin
Passez cette étape si aucun serveur n'a encore été déployé : txAdmin affiche déjà l'assistant.
Sinon, ouvrez txAdmin par le tunnel SSH, puis :
- Allez dans Settings, onglet FXServer.
- Copiez la valeur de Server Data Folder et gardez-la : c'est le chemin de votre serveur actuel.
- Cliquez sur Reset, puis confirmez.
Cette action arrête le serveur et ramène txAdmin à l'assistant. Elle ne supprime ni les fichiers des ressources ni la base de données.
Étape 4 : lancer le déploiement
Dans l'assistant, donnez un nom au serveur, puis choisissez la recette :
- ESX Legacy : sélectionnez Popular Recipes, puis ESX Legacy.
- QBCore : sélectionnez Remote URL Template, puis collez cette adresse :
https://raw.githubusercontent.com/qbcore-fivem/txAdminRecipe/main/qbcore.yamlConservez le dossier de destination proposé et passez au Recipe Deployer. Collez votre clé cfxk_, puis cliquez sur Show/Hide Database options (advanced) et renseignez :
| Champ | Valeur |
|---|---|
| Database Host | 127.0.0.1 |
| Database Port | 3306 |
| Database Username | fivem |
| Database Password | Le mot de passe de l'utilisateur fivem |
| Database Name | fivem (ou fivem_rp) |
| Delete Database | Désactivé |
Cliquez sur Run Recipe. Le déploiement télécharge de nombreuses ressources et peut durer plusieurs minutes. À la fin, cliquez sur Save & Run Server.
Étape 5 : vérifier l'installation
Attendez environ une minute, puis cherchez la connexion à la base et le démarrage du framework dans la console :
sudo grep -a -E 'Database server connection established|Started resource (es_extended|qb-core)' /home/fivem/fxserver.logVous devez voir la ligne de connexion à la base et celle de es_extended ou de qb-core. Vérifiez ensuite que le serveur déclare ces ressources :
curl -fsS http://127.0.0.1:30120/info.json | grep -oE '"(oxmysql|es_extended|qb-core)"'Contrôlez enfin que la recette a créé la table des joueurs :
# ESX Legacy
sudo mariadb fivem -e "SHOW TABLES LIKE 'users';"
# QBCore
sudo mariadb fivem -e "SHOW TABLES LIKE 'players';"Connectez-vous ensuite au jeu avec connect IP_DU_SERVEUR:30120 et créez un personnage. Une ligne doit alors apparaître dans cette table.
Étape 6 : vous donner les droits d'administration
- ESX Legacy : connectez-vous au serveur, repérez votre numéro de joueur dans la liste des joueurs connectés de txAdmin, puis tapez dans Live Console
setgroup 1 admin, en remplaçant1par ce numéro. Le groupe est enregistré dans la tableusers. - QBCore : ajoutez votre identifiant au groupe
qbcore.god, comme expliqué dans Gérer les permissions ACE.
Lancez aussi une nouvelle sauvegarde : c'est désormais votre point de retour de référence.
sudo /usr/local/sbin/backup-fivem.shRevenir en arrière
Cette procédure restaure le serveur et la base tels qu'ils étaient à l'étape 1. Remplacez DATE par la date notée.
sudo systemctl stop fivem.service
sudo mv /home/fivem/txData /home/fivem/txData.framework
sudo -u fivem tar -xzf /home/fivem/backups/fivem_DATE.tar.gz -C /home/fivem
sudo mariadb -e "DROP DATABASE fivem; CREATE DATABASE fivem CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
zcat /home/fivem/backups/fivem_db_DATE.sql.gz | sudo mariadb fivem
sudo systemctl start fivem.serviceSi vous aviez créé fivem_rp, l'archive de l'étape 1 contient la base fivem d'origine, qui n'a pas été modifiée : ne lancez pas les lignes DROP DATABASE et zcat. Supprimez plutôt fivem_rp avec sudo mariadb -e "DROP DATABASE fivem_rp;", puis remettez DB_NAME="fivem" dans le script de sauvegarde.
Le dossier /home/fivem/txData.framework conserve l'essai. Supprimez-le quand vous n'en avez plus besoin.
En cas de problème
Database connection failed
Ce message apparaît dans le Recipe Deployer, suivi de la cause :
connect ECONNREFUSED 127.0.0.1:3306: MariaDB ne tourne pas. Vérifiez avecsudo systemctl status mariadb.Access denied for user 'fivem'@'localhost': le mot de passe est incorrect.Access denied for user 'fivem'@'127.0.0.1': ajoutez ce compte en suivant Installer et configurer oxmysql.
Access denied for user 'fivem'@'localhost' to database
Le champ Database Name contient un autre nom que fivem. Par défaut, txAdmin y place l'identifiant du déploiement, et l'utilisateur fivem n'a aucun droit sur cette base. Corrigez le champ.
Table 'addon_account' already exists
La recette ESX a déjà été lancée sur cette base, par exemple lors d'un déploiement interrompu. Si la base ne contient rien d'utile, videz-la, puis relancez la recette :
sudo mariadb -e "DROP DATABASE fivem; CREATE DATABASE fivem CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"Le déploiement s'arrête pendant un téléchargement
Les recettes téléchargent beaucoup de fichiers depuis GitHub, qui peut limiter temporairement les requêtes. Attendez quelques minutes, puis relancez le déploiement. Vérifiez aussi l'espace disque avec df -h /home.
La recette n'apparaît pas ou txAdmin la juge incompatible
QBCore n'est pas dans Popular Recipes : utilisez Remote URL Template. Si txAdmin indique Some recipes are not compatible with your txAdmin version, mettez à jour FXServer, qui embarque txAdmin.
Could not find dependency oxmysql for resource es_extended
La ressource oxmysql est absente ou mal placée. Le même message existe pour qb-core et pour esx_lib. Vérifiez sa présence avec le guide Installer et configurer oxmysql.
Resource 'oxmysql' can't run
Si la ligne suivante indique server needs to be 12913 or higher, votre version de FXServer est trop ancienne pour cette version d'oxmysql. Mettez à jour FXServer.
Table 'fivem.users' doesn't exist
La chaîne de connexion pointe vers une autre base que celle du déploiement, ou l'import SQL n'a pas abouti. Comparez mysql_connection_string dans CFG Editor avec le résultat de sudo mariadb -e "SHOW DATABASES;".
Le serveur démarre mais reste instable
Consultez Diagnostiquer les crashs et lenteurs d'un serveur FiveM pour trouver la ressource en cause.