Aller au contenu

Déploiement

Mappings Medusa et synchronisation des resources

Au démarrage du conteneur FiveM, l’entrypoint consulte la dernière révision de la branche main des trois dépôts publics suivants :

  • The-Medusa-Project/medusamappings vers [medusamappings] ;
  • celenys/medusamappings2 vers [medusamappings2] ;
  • celenys/medusamappings3 vers [medusamappings3].

Pour chaque dépôt, si le SHA distant diffère de son .bundle-revision, l’entrypoint récupère la branche puis remplace intégralement le groupe correspondant. Sinon, les fichiers installés sont conservés sans retéléchargement. Les trois groupes sont ensuite activés par leurs directives ensure respectives.

Les dépôts sont publics : aucun token GitHub ni secret Portainer n’est nécessaire. La branche main est imposée par l’entrypoint et n’est pas configurable. Il n’est pas nécessaire de configurer un SHA : chaque recréation ou redémarrage du conteneur FiveM utilise automatiquement la dernière révision disponible sur main.

FIVEM_LOAD_MLOS vaut true par défaut. Avec false (ainsi que 0, no ou off), l'entrypoint saute les trois synchronisations réseau et génère un server.cfg sans les groupes medusamappings*, bob74_ipl, lotustatoo ni mod_mapFiveM. fivem-appearance et realistic-handling restent chargés explicitement. Les dossiers éventuellement présents dans le volume sont conservés mais ne sont pas démarrés. Le convar mlos_enabled=false empêche également le synchroniseur de medusa-admin de les réactiver. Une valeur inconnue arrête le conteneur avec une erreur explicite.

La synchronisation est exécutée de façon bloquante avant la préparation finale et les commandes exec de FXServer/txAdmin. Une erreur sur l’un des trois dépôts termine le conteneur avec un code d’erreur : aucun processus FXServer ne peut donc démarrer avec des mappings incomplets. Le journal All Medusa mappings repositories are synchronized; FXServer startup may proceed. confirme l’ouverture de cette barrière de démarrage.

Le volume persistant contient .medusa-managed-resources. À chaque démarrage, les resources intégrées sont recopiées par remplacement complet : les fichiers supprimés dans l’image disparaissent donc aussi du volume. Lors d’une recréation, le manifeste supprime en plus les anciennes resources gérées qui ne sont plus présentes dans l’image. Chaque groupe de mappings est remplacé intégralement lorsque sa révision change. Les resources ajoutées manuellement hors du manifeste ne sont pas supprimées.

Prérequis et configuration

Installer Docker Compose v2, puis copier .env.example vers .env. Remplacer au minimum les mots de passe PostgreSQL/Redis, les clés internes et JWT, les secrets Discord et la licence FiveM. Ne jamais committer .env.

docker compose build
docker compose up -d
docker compose exec api alembic upgrade head

RUN_MIGRATIONS_ON_START=true est aussi imposé à l'API pour éviter qu'elle soit prête avec un schéma obsolète.

Versions FiveM automatiques

L'entrypoint consulte à chaque démarrage l'index officiel build_proot_linux/master, sélectionne l'URL fx.tar.xz dont le numéro d'artefact est le plus élevé, puis la compare au marqueur .artifact-url du volume fivem_artifacts. Il remplace intégralement l'artefact installé lorsque l'URL change. FIVEM_ARTIFACT_URL n'est plus une variable de déploiement : une valeur ancienne ne peut donc plus épingler accidentellement le serveur.

Le game build client suit une politique distincte, versionnée dans fivem/game-build-policy.conf. production_game_build=3751 désigne le plus haut build approuvé pour le canal Production ; ce n'est pas nécessairement le plus grand numéro déjà ajouté à la documentation. resolve-game-build.sh lit strictement cette politique, extrait la section sv_enforceGameBuild de la documentation officielle Cfx.re et vérifie que le build approuvé y figure. Il renvoie uniquement cette valeur à l'entrypoint, qui rend ensuite server.cfg via FIVEM_GAME_BUILD. Une valeur documentée supérieure est journalisée puis ignorée jusqu'à sa promotion stable officielle.

FIVEM_GAME_BUILD n'est pas une variable de déploiement : Portainer ne peut pas contourner la politique versionnée. Pour promouvoir un build après confirmation de sa disponibilité Production, modifier production_game_build, exécuter fivem/tests/resolve-game-build.test.sh, faire revoir le changement puis reconstruire le service FiveM. Une politique inconnue, dupliquée ou non numérique, une table absente/malformée, un build approuvé absent ou une source inaccessible arrête le conteneur avant FXServer. Le convar sv_replaceExeToSwitchBuilds false reste appliqué, et la sélection du dernier artefact serveur demeure indépendante et automatique.

Nommage des ressources Medusa

Toutes les ressources locales appartenant au projet utilisent le préfixe medusa- (par exemple medusa-core, medusa-admin et medusa-inventory). Les dépendances, exports, ACL et directives ensure utilisent ces nouveaux noms. Lors de la première recréation après migration, le manifeste des ressources gérées retire du volume persistant les anciens dossiers gta-* et basicspawn, puis installe leurs équivalents medusa-*.

Documentation

Le service docs construit les sources avec MkDocs Material en mode strict, puis sert le résultat avec nginx :

docker compose build docs
docker compose up -d docs

Ouvrir http://HOTE:8001, ou le port défini par DOCS_PORT.

Endpoints publiés

  • admin : ADMIN_PORT, défaut 8080 ;
  • documentation : DOCS_PORT, défaut 8001 ;
  • FiveM : FIVEM_GAME_PORT, défaut 30120 en TCP/UDP ;
  • txAdmin : TXADMIN_PORT, défaut 40120.

Dans Portainer, renseigner les variables dans l'éditeur de stack. Les services se joignent par leur nom Docker (api, database, redis) et jamais via localhost.

Avant de lancer FXServer ou txAdmin, l'entrypoint appelle GET /internal/v1/system/ready avec X-Internal-Api-Key. La barrière exige PostgreSQL, Redis et alembic_version exactement à l'unique head Alembic embarquée. Un refus 401/403 arrête immédiatement le conteneur ; une indisponibilité 503 est retentée jusqu'au délai configuré. Déployer l'image API avant l'image FiveM lors d'une mise à jour séparée.

Dépendances ARPhone

Chaque build embarque la tête de pma-voice/main et screenshot-basic/master. Les builders officiels Cfx.re yarn/webpack, requis par le manifeste courant de screenshot-basic, ne sont ni clonés ni vendorisés : chaque artefact FXServer embarque déjà ses propres copies sous citizen/system_resources/{yarn,webpack} (confirmé par inspection d'un fx.tar.xz téléchargé et par la présence du chemin littéral /system_resources/ compilé dans libcitizen-server-impl.so), que ensure yarn/ensure webpack dans server.cfg.template résolvent automatiquement — un dépôt externe avait auparavant fourni une copie de ces builders, mais ce dépôt a depuis supprimé resources/[system]/[builders] sans le déplacer (2026-07-20), ce qui a cassé la construction de l'image FiveM jusqu'à ce que la dépendance à ce dépôt soit supprimée entièrement plutôt que réparée. Le volume arphone_media doit être sauvegardé avec PostgreSQL au même point de cohérence.

Activation des véhicules

VEHICLES_ENABLED=true est le défaut du dépôt pour l'auto-déploiement de VirgiilBranch. RUN_MIGRATIONS_ON_START=true applique 0028_vehicle_keys avant que l'API soit prête, puis FiveM attend /ready. Contrôler immédiatement les logs et que medusa-vehicles précède medusa-admin, puis tester d'abord un véhicule vanilla et ensuite un custom avec deux clients. Le retour arrière sûr définit explicitement VEHICLES_ENABLED=false dans Portainer et redéploie sans supprimer les tables ; après des données réelles, ne pas exécuter de downgrade destructif.

Cette branche a rejoint master (compétences, ARPhone) après que chaque environnement avait déjà appliqué sa propre migration en tête de 0027_banking_system (0028_skill_tree_system côté master, 0028_vehicle_keys côté VirgiilBranch). Ni l'un ni l'autre identifiant de révision n'a été renommé après déploiement — cela aurait laissé un environnement avec un alembic_version introuvable dans l'historique. La migration 0031_merge_skills_and_vehicles réunit les deux têtes sans aucune opération de schéma ; alembic upgrade head converge vers elle depuis l'un ou l'autre état.

Activation handling, compartiments et commandes

Le déploiement de MED-20260827-001 doit appliquer 0033_vehicle_handling_storage avant de redémarrer medusa-vehicles, medusa-inventory, medusa-interactions, medusa-admin et le web. Conserver API, ressources FiveM et admin web sur le même hash. Sauvegarder PostgreSQL avant alembic upgrade head, puis vérifier /ready, /internal/v1/vehicles/features et l'empreinte du catalogue ORIGINAL.

L'entrypoint API résout l'historique Alembic avant la migration et refuse tout identifiant dépassant les 32 caractères de alembic_version.version_num. Cette limite est également couverte par les tests API avec une table de version déclarée en VARCHAR(32). Une validation de livraison doit toujours exécuter l'upgrade depuis le head précédent sur un PostgreSQL réel puis le rejouer une seconde fois ; la génération SQL hors ligne et SQLite ne remplacent pas cette preuve.

Les trois flags sont activés par défaut dans le dépôt :

VEHICLE_HANDLING_ENABLED=true
VEHICLE_INVENTORIES_ENABLED=true
VEHICLE_CONTROL_MENUS_ENABLED=true

Les limites associées sont : preview 300 s, batch handling 25, historique 20 versions, session de compartiment 120 s, réservation de siège 5 s et rate limit 12 actions/10 s. Un canary doit couvrir un vanilla, un modèle realistic-handling, un custom, un véhicule personnage et un groupe avant l'ouverture générale.

Le rollback fonctionnel désactive seulement le flag fautif. Un rollback applicatif peut redéployer le commit précédent, mais ne doit pas downgrader ni supprimer les tables 0033 : profils, contenus, événements et audits restent dormants jusqu'à une version compatible. Un push Git vers VirgiilBranch ne constitue pas à lui seul une preuve de déploiement Portainer/FXServer.

Migration 0036 et personnalisation du compteur

0036_speedometer_placement doit être appliquée après 0035_speedometer_cruise_v2. Elle ajoute scale_percent, position_x et position_y, transforme small/normal/large en 80/100/120 et initialise (0.5,0.8). Thème, visibilité, éclairage, révision, timestamps, relations et ownership restent inchangés. Les nouveaux comptes utilisent classic/100/0.5/0.8/visible/auto.

Avant toute livraison : sauvegarder PostgreSQL, confirmer que 0035 est le head de départ, tester l'upgrade 0035→0036 sur une copie PostgreSQL représentative avec les trois tailles, vérifier les contraintes et relancer alembic upgrade head. Attendre ensuite /ready avant le chargement de FiveM. Le SQL hors ligne et SQLite ne remplacent pas ce test PostgreSQL réel. Aucun downgrade 0036 n'est autorisé en production.

VEHICLE_SPEEDOMETER_ENABLED=true

Le régulateur et sa variable d'environnement ont été supprimés. Pendant un rollback applicatif, conserver toute éventuelle ancienne variable externe de régulateur explicitement à false, couper le compteur avec VEHICLE_SPEEDOMETER_ENABLED=false, redéployer si nécessaire et conserver 0036. Après déploiement, surveiller les codes GET/PATCH, conflits de révision, transitions repli/récupéré, fréquence de télémétrie, resmon et mémoire. API, HUD et ressources véhicules doivent provenir du même commit de VirgiilBranch.

Fusion avec le crafting (0037)

master a avancé après 0029_arphone avec 0030_crafting_system puis 0031_fix_bank_terminal_ped_model, pendant que VirgiilBranch avançait avec 0031_merge_skills_and_vehicles jusqu'à 0036_speedometer_placement. Ces deux têtes sont réunies sans aucune opération de schéma par 0037_merge_crafting_vehicles, suivant exactement le précédent posé par 0031_merge_skills_and_vehicles : aucun identifiant de révision existant n'est renommé, alembic upgrade head converge vers 0037_merge_crafting_vehicles depuis l'un ou l'autre état.

Head 0042 et déploiement multicarburant

Le head courant devient 0042_energy_charger_heading, forward-only depuis 0041_vehicle_fuel_ports, lui-même forward-only depuis 0040_vehicle_lc_fuel et 0039_vehicle_energy_simple. Avant déploiement, exécuter les harnais PostgreSQL 0040, 0041 puis 0042 isolés, sauvegarder la vraie base et relever les sessions/réserves. Le harnais 0041 confirme les 669 calibrations protégées et la Buffalo exacte ; le harnais 0042 prouve que seules les bornes canoniques encore sur leur heading 0040 sont retournées et que les orientations F10 sont préservées. Charger les ressources dans l'ordre medusa-vehicles, lc_utils, medusa-energy, lc_fuel, medusa-admin.

Le préflight vérifie le head exact, les commits LC pinés, les licences, le contrat de façade writer=false/database=false/commands=false et l'absence de tout writer carburant concurrent. Après 0042, couper les flags concernés et corriger en avant ; ne jamais redémarrer un binaire 0041 ou antérieur ni downgrader. Le préflight et le canary doivent notamment couvrir Buffalo sur pompe GTA, calibration/reset F10, cohérence web et refresh après restart/reconnexion. Ils sont détaillés dans Énergie des véhicules.

Après le démarrage, le diagnostic serveur medusa-energy doit annoncer un catalogue de trappes ready=669 (ou davantage si des modèles additionnels ont été calibrés). Un client déjà présent et un client arrivé après la diffusion initiale doivent obtenir le même état via la demande ciblée de schéma 2, indépendamment du bootstrap de compte et de l’état entered. Rejouer ensuite reconnexion, restart client, restart serveur de medusa-energy, mutation/reset F10 et Buffalo sur pompe GTA. SYNC-FUEL-PORT est acceptable uniquement pendant une indisponibilité réelle et transitoire ; CAL-FUEL-PORT sur la Buffalo bloque la promotion. Vérifier enfin que réseau, F8 et console restent silencieux par frame. Les corrections R2 à R7 n’ajoutaient aucune migration ; la correction d’orientation R1 de MED-20260904-001 porte désormais la tête attendue 0042_energy_charger_heading.