BeamMP Panel

Interface d'administration web pour serveur BeamMP. Gestion des mods, cartes, configuration, logs et joueurs.

Site, captures et installation pas à pas : https://beammp-web.zyphro.fr · Blog et autres outils : https://zyphro.fr

Système	Installation
Windows	Appli prête à l'emploi : un zip à décompresser, un double-clic, un assistant. Le panel installe, démarre et surveille BeamMP-Server lui-même, et se met à jour en un clic. → Windows
Linux	Docker (un conteneur, à côté de BeamMP-Server géré par systemd). → Installation

v3 = moteur Python + SQLite (branche v3-python). Même interface et même API que la v2, sans PostgreSQL ni Node.js à l'exécution. La branche v2 garde l'ancien moteur Node.js/TypeScript + PostgreSQL ; la branche main l'ancienne V1 (PHP/MariaDB). Passer d'une v2 en place à la v3 : Passage de la v2 à la v3.

---

Fonctionnalités

• Mods, véhicules et cartes — upload (simple ou Scan & Import des .zip déjà présents dans Resources/), activation/désactivation, carte active, image de prévisualisation extraite automatiquement et modifiable, description éditable.
• Analyse automatique du contenu des mods — marque, style de carrosserie, transmission(s), puissance, configurations pour les véhicules ; taille, auteur, catégorie pour les cartes. Affichée en badges sur chaque carte.
• Configs pré-établies — un jeu de mods + une carte appliqués en un clic (voir Configs pré-établies).
• Configuration serveur — édition de ServerConfig.toml, redémarrage et mise à jour du binaire BeamMP-Server via beammp-agent.
• Logs et alertes — consultation de Server.log, bannière d'alerte sur les erreurs critiques (ex. AuthKey refusée par le backend BeamMP).
• Joueurs — historique des connexions, temps de jeu, badge de rang (Bronze/Argent/Or/Platine).
• Cohérence — détection (et correction en un clic) des écarts entre la base et les fichiers réels de Resources/.
• Multi-instance — plusieurs serveurs BeamMP pilotés depuis un seul panel.
• Comptes et rôles — moderator / admin / superadmin, demandes de compte validées par un superadmin, changement de mot de passe en libre-service.
• Page publique — statut du serveur en temps réel (lu directement sur le port de jeu), carte et mods actifs, et catalogue complet du serveur en lecture seule : toutes les cartes, véhicules et mods, avec recherche et badge « En jeu ».
• Notifications Discord (optionnelles), interface en 8 langues (fr, en, de, es, it, pl, pt, ru), thème clair/sombre.

---

Sommaire

1. Fonctionnalités
2. Windows (appli prête à l'emploi)
3. Prérequis (Linux, Docker)
4. Installation
5. Configuration .env
6. Démarrage
7. Premier démarrage
8. Reverse proxy HTTPS
9. Multi-instance
10. Redémarrage du serveur
11. Configs pré-établies
12. Mise à jour
13. Sauvegarde
14. Migration depuis la V1 (MariaDB)

---

Windows (appli prête à l'emploi)

1. Télécharger BeamMP-Panel-<version>-win64.zip dans la dernière release.
2. Le décompresser où vous voulez, puis double-cliquer sur « Lancer BeamMP Panel.bat » : la page s'ouvre dans le navigateur. (Alerte Windows : « Debloquer si alerte Windows.bat », ou « Informations complémentaires » → « Exécuter quand même ».)
3. L'assistant demande le dossier du serveur BeamMP — il peut télécharger BeamMP-Server pour vous —, la clé d'authentification BeamMP (keymaster.beammp.com, obligatoire : le serveur ne démarre pas sans) et votre compte administrateur.

Ensuite :

• le panel démarre BeamMP-Server, le relance s'il plante (5 fois maximum en 10 min) et l'arrête avec lui ; boutons Démarrer / Arrêter / Redémarrer dans Configuration ;
• mise à jour du serveur BeamMP depuis la release officielle (empreinte vérifiée, retour à l'ancien exécutable s'il ne démarre pas) ;
• mise à jour du panel en un clic (Configuration → Mise à jour du panel) : manifeste signé Ed25519 publié avec chaque release, paquet de quelques centaines de Ko, et si la nouvelle version ne démarre pas, la précédente revient au lancement suivant (et la version fautive n'est plus proposée) ;
• si le port 3000 est déjà pris sur le PC, le panel prend le suivant libre et s'en souvient ;
• données dans %APPDATA%\BeamMP Panel (base, images, settings.json, journal panel.log), jamais touchées par une mise à jour.

Par défaut le panel n'écoute que sur ce PC (http://127.0.0.1:3000). Pour y accéder depuis le réseau : "host": "0.0.0.0" dans settings.json, puis relancer (et ouvrir le port dans le pare-feu Windows).

Testé sur Windows 10 (compte utilisateur sans droits d'administrateur).

---

Prérequis (Linux, Docker)

• Docker Engine 24+ et Docker Compose v2 (Docker CE, dépôt officiel get.docker.com) : install.sh propose de l'installer s'il manque
• systemd, accès root (sudo)
• Le serveur BeamMP sur la même machine : install.sh l'installe s'il n'y en a pas
• Linux sans Docker n'est pas pris en charge : sous Linux, le panel tourne en conteneur ; sous Windows, utilisez l'appli ci-dessus.

---

Installation

En une commande (recommandé, depuis la 3.3.0)

curl -fsSL https://raw.githubusercontent.com/Zyphro3D/BeamMP-web/HEAD/install.sh -o beammp-install.sh && sudo bash beammp-install.sh

Le script est téléchargé avant d'être lancé : sudo peut ainsi demander le mot de passe, et vous pouvez le relire avant.

Le script fait tout ce qui est décrit plus bas à la main :

• télécharge la dernière release et vérifie sa signature (Ed25519, clé publique écrite dans le script) et l'empreinte SHA-256 de l'archive ;
• crée .env (droits 600) avec une clé de session et un mot de passe SuperAdmin aléatoires, affichés à la fin ;
• installe BeamMP-Server (binaire officiel, empreinte confirmée par GitHub) et son service beammp.service ;
• installe beammp-agent (boutons Redémarrer / Mettre à jour le serveur), qui n'écoute que sur le réseau Docker du panel ;
• construit et démarre le panel, puis attend qu'il réponde ;
• pose l'unité beammp-panel-update : le bouton Mettre à jour du panel relance ce script sur l'hôte (voir Mise à jour).

Options : --dir DOSSIER (défaut /opt/beammp-panel), --server-dir DOSSIER (défaut DOSSIER/beammp-server), --auth-key CLÉ (clé du serveur sur keymaster.beammp.com), --version vX.Y.Z, --yes (installe Docker sans poser la question).

Sans clé AuthKey, le panel fonctionne mais BeamMP-Server attend sa clé : relancez-le avec --auth-key VOTRE_CLÉ (sudo bash beammp-install.sh --auth-key VOTRE_CLÉ). Port à ouvrir vers la machine pour les joueurs : 30814 TCP+UDP.

Reprendre une installation faite à la main (git)

Relancez la commande avec le dossier existant :

curl -fsSL https://raw.githubusercontent.com/Zyphro3D/BeamMP-web/HEAD/install.sh -o beammp-install.sh
sudo bash beammp-install.sh --dir /opt/app-docker/beammp-panel --server-dir /chemin/de/BeamMP-Server

Le .env, la base (volume app_data), les mods, les services BeamMP et l'unité de beammp-agent sont gardés tels quels ; seul le code du panel et de l'agent est remplacé par celui de la release. Les fichiers du dossier sont alors ceux de la release, plus ceux de git : n'utilisez plus git pull dans ce dossier (les mises à jour passent par le bouton du panel ou la même commande). Si vous aviez modifié docker-compose.yml, reportez vos changements dans docker-compose.override.yml avant (sinon ils sont remplacés).

Dossier d'installation appartenant à un utilisateur — le script garde ce propriétaire, mais l'unité de mise à jour lance DOSSIER/install.sh en root, et Docker construit ce que contient le dossier : quiconque peut écrire dans ce dossier peut donc obtenir les droits root sur la machine. C'est sans effet si cet utilisateur est déjà administrateur (sudo, groupe docker) ; sinon, donnez le dossier à root (sudo chown -R root:root DOSSIER, en gardant update/ à l'uid 1000).

À la main

git clone <repo> beammp-panel
cd beammp-panel
cp .env.example .env
# Éditer .env (voir section ci-dessous)

Puis beammp-agent et le démarrage. Le bouton Mettre à jour du panel n'est disponible qu'avec install.sh.

---

Configuration .env

Variables obligatoires avant le premier démarrage :

# Clé secrète JWT — générer avec : openssl rand -hex 32
JWT_SECRET=

# Compte SuperAdmin créé automatiquement si la base est vide
SUPERADMIN_USERNAME=admin
SUPERADMIN_PASSWORD=

Chemins BeamMP — à adapter à votre installation :

# Linux
BEAMMP_RESOURCES_PATH=/home/user/BeamMP-Server/Resources
BEAMMP_LOG_DIR=/home/user/BeamMP-Server
BEAMMP_CONFIG_PATH=/home/user/BeamMP-Server/ServerConfig.toml

# Windows (Docker Desktop)
BEAMMP_RESOURCES_PATH=C:\Users\user\BeamMP-Server\Resources
BEAMMP_LOG_DIR=C:\Users\user\BeamMP-Server
BEAMMP_CONFIG_PATH=C:\Users\user\BeamMP-Server\ServerConfig.toml

Ces chemins sont les chemins hôte. Docker les monte automatiquement en tant que volumes dans le conteneur (toujours sous /beammp/... côté container).

BEAMMP_LOG_DIR pointe vers le dossier qui contient Server.log, pas vers le fichier lui-même : BeamMP-Server recrée ce fichier (renomme l'ancien en Server.old.log) à chaque démarrage plutôt que de le tronquer sur place, et un bind mount Docker sur un fichier unique resterait accroché à l'ancien inode — plus aucune écriture ne serait revue côté conteneur après un redémarrage du serveur. Monter le dossier évite ce piège.

Si le panel est derrière un reverse proxy HTTPS :

COOKIE_SECURE=true

---

Démarrage

# Premier démarrage / rebuild
docker compose up -d --build

# Redémarrer sans rebuild
docker compose up -d

# Voir les logs
docker compose logs -f app

---

Premier démarrage

1. Ouvrir http://localhost:3000 (ou votre domaine)
2. Se connecter avec le compte SUPERADMIN_USERNAME / SUPERADMIN_PASSWORD défini dans .env

SUPERADMIN_USERNAME et SUPERADMIN_PASSWORD ne créent le compte que si la base est vide. Ils peuvent être supprimés du .env après le premier démarrage.

Import des mods existants :

Si des mods sont déjà présents dans le dossier Resources/ du serveur BeamMP, utiliser la fonctionnalité Scan & Import (sidebar → Import) pour les enregistrer automatiquement en base de données. Le scan extrait le nom depuis info.json et l'image de prévisualisation depuis le zip.

Images des mods/véhicules/cartes :

• Automatique — à l'upload (formulaire simple ou Scan & Import), le panel cherche une image de prévisualisation dans l'archive (preview.jpg, icon.png, la texture par défaut d'un véhicule, une image sous levels/<nom>/…) et la génère en .webp. Aucune garantie de résultat : de nombreux mods ne fournissent pas d'image exploitable dans ce sens.
• Manuelle — l'icône image sur chaque carte (mods, véhicules, cartes) permet de choisir sa propre image à tout moment, y compris pour en remplacer une déjà présente.
• Par défaut — sans image (ni automatique ni manuelle), une icône générique par type (véhicule/mod/carte) s'affiche à la place.

---

Reverse proxy HTTPS

Exemple avec Caddy :

panel.mondomaine.com {
    reverse_proxy localhost:3000
}

Ajouter dans .env :

COOKIE_SECURE=true
# Si frontend sur domaine différent du port par défaut :
# ALLOWED_ORIGIN=https://panel.mondomaine.com

Puis redémarrer : docker compose up -d

Note rate limiting Caddy : Si vous utilisez un rate limit global sur /api*, le dashboard effectue plusieurs appels API au chargement et peut déclencher la limite. Appliquez le rate limit uniquement sur /api/auth/login*. Le backend gère déjà son propre rate limit sur cet endpoint (5 req/min).

---

Multi-instance

Le panel peut gérer plusieurs serveurs BeamMP depuis une seule interface.

Configuration .env

INSTANCES=main,event

INSTANCE_MAIN_NAME=Serveur Principal
INSTANCE_MAIN_SERVER_IP=1.2.3.4
INSTANCE_MAIN_SERVER_PORT=30814
INSTANCE_MAIN_BEAMMP_RESOURCES_PATH=/beammp/main/resources
INSTANCE_MAIN_BEAMMP_LOG_PATH=/beammp/main/logs/Server.log
INSTANCE_MAIN_BEAMMP_CONFIG_PATH=/beammp/main/ServerConfig.toml
INSTANCE_MAIN_AGENT_SERVICE=beammp-main.service

INSTANCE_EVENT_NAME=Serveur Évènement
INSTANCE_EVENT_SERVER_IP=1.2.3.4
INSTANCE_EVENT_SERVER_PORT=30815
INSTANCE_EVENT_BEAMMP_RESOURCES_PATH=/beammp/event/resources
INSTANCE_EVENT_BEAMMP_LOG_PATH=/beammp/event/logs/Server.log
INSTANCE_EVENT_BEAMMP_CONFIG_PATH=/beammp/event/ServerConfig.toml
INSTANCE_EVENT_AGENT_SERVICE=beammp-event.service

BEAMMP_AGENT_URL/BEAMMP_AGENT_TOKEN restent globaux (un seul agent par hôte) — seul AGENT_SERVICE varie par instance, pour cibler le bon service systemd au redémarrage.

Volumes docker-compose.yml

Ajouter un volume par instance sous services.app.volumes :

volumes:
  - app_images:/app/images
  - /host/main/Resources:/beammp/main/resources
  - /host/main/ServerConfig.toml:/beammp/main/ServerConfig.toml
  - /host/event/Resources:/beammp/event/resources
  - /host/event/ServerConfig.toml:/beammp/event/ServerConfig.toml
  # Le DOSSIER contenant Server.log, jamais le fichier seul : BeamMP-Server le
  # recrée (renomme l'ancien en Server.old.log) à chaque démarrage plutôt que
  # de le tronquer sur place, et un bind mount Docker sur un fichier unique
  # reste accroché à l'ancien inode — voir la note sur BEAMMP_LOG_DIR plus
  # haut dans ce README.
  - /host/main/:/beammp/main/logs:ro
  - /host/event/:/beammp/event/logs:ro

---

Redémarrage du serveur

Le panel tourne en conteneur Docker et n'a pas accès à systemctl de l'hôte — le bouton "Redémarrer le serveur" passe donc par beammp-agent, un petit daemon Python (aucune dépendance) installé sur l'hôte, hors Docker.

Installation

Les deux fichiers sont dans le dossier agent/ du dépôt :

sudo mkdir -p /opt/beammp-agent
sudo cp agent/beammp-agent.py /opt/beammp-agent/
sudo cp agent/beammp-agent.service /etc/systemd/system/
sudo chmod +x /opt/beammp-agent/beammp-agent.py

L'agent tourne sous un utilisateur non-root (User= dans le unit) et redémarre le serveur via sudo systemctl restart <service>. Autoriser uniquement cette commande, pour ce(s) service(s) (sudo visudo -f /etc/sudoers.d/beammp-agent) :

beammp ALL=(root) NOPASSWD: /usr/bin/systemctl restart beammp.service

Créer /etc/beammp-agent.env (jamais dans le unit file, qui est lisible par tout le monde par défaut) :

sudo sh -c 'echo "RESTART_TOKEN=$(openssl rand -hex 32)" > /etc/beammp-agent.env'
sudo chmod 600 /etc/beammp-agent.env
sudo chown root:root /etc/beammp-agent.env

Éditer /etc/systemd/system/beammp-agent.service :

• User — l'utilisateur de la règle sudoers ci-dessus
• ALLOWED_SERVICES — nom(s) du/des service(s) systemd du serveur BeamMP (whitelist stricte, l'agent refuse tout service hors de cette liste)
• AGENT_HOST — ne pas utiliser 0.0.0.0 ni l'IP LAN de la machine. Utiliser l'IP de la passerelle du réseau Docker du projet (docker network inspect beammp-panel_default → Gateway, typiquement 172.18.0.1 ou 172.17.0.1) : l'agent reste joignable depuis le conteneur du panel via sa route par défaut, mais injoignable depuis le réseau local.

sudo chmod 600 /etc/systemd/system/beammp-agent.service   # contient des infos internes, pas de secret
sudo systemctl daemon-reload
sudo systemctl enable --now beammp-agent
curl http://<AGENT_HOST>:4445/health   # depuis l'hôte, doit répondre {"ok": true, ...}

Renseigner dans le .env du panel :

BEAMMP_AGENT_URL=http://172.18.0.1:4445
BEAMMP_AGENT_TOKEN=<le même RESTART_TOKEN que /etc/beammp-agent.env>
BEAMMP_AGENT_SERVICE=beammp.service

Sans ces trois variables, le bouton de redémarrage reste désactivé (tooltip "Restart non configuré") plutôt que d'échouer au clic.

Si le réseau Docker du projet est un jour supprimé et recréé (docker compose down puis up, pas un simple restart), l'IP de passerelle peut changer — revérifier AGENT_HOST et BEAMMP_AGENT_URL ensemble dans ce cas.

Mise à jour du serveur BeamMP (binaire du jeu)

À ne pas confondre avec la mise à jour du panel lui-même (section suivante). Un bouton dans Configuration télécharge et installe la dernière release BeamMP-Server officielle via beammp-agent, vérifie son empreinte sha256 (fournie par l'API GitHub) avant toute installation, sauvegarde le binaire précédent (BeamMP-Server.bak-<timestamp>, à supprimer manuellement une fois la mise à jour confirmée stable), puis redémarre le service.

Activation (en plus de la config restart ci-dessus) :

1. Renseigner BEAMMP_BINARY_PATH dans beammp-agent.service (chemin vers l'exécutable BeamMP-Server) et ReadWritePaths=<dossier du binaire> dans la section [Service] (ProtectSystem=strict rend le reste du système en lecture seule pour l'agent — sans ça, l'installation échoue).
2. Dans le .env du panel, ajouter BEAMMP_AGENT_ASSET — le suffixe exact d'un asset de la page releases (ex. debian.13.x86_64, à déterminer via uname -m + cat /etc/os-release sur l'hôte).
3. sudo systemctl daemon-reload && sudo systemctl restart beammp-agent

Sans BEAMMP_AGENT_ASSET, le bloc "Mise à jour du serveur" n'apparaît pas dans Configuration (redémarrage seul reste disponible, indépendamment).

---

Configs pré-établies

Section Configs — bascule d'un scénario serveur à l'autre en un clic (ex. "Soirée Muscle Cars" : tel jeu de véhicules + telle carte) au lieu de cocher les mods un par un.

Une config = un nom + une liste de mods/véhicules à activer + une carte. Appliquer une config :

1. Active exactement les mods/véhicules listés, désactive tout le reste (déplace les fichiers entre Client/ et inactive_mod/ comme le ferait une bascule manuelle).
2. Active la carte choisie (si renseignée) — même mécanisme que Cartes.
3. Redémarre le serveur automatiquement si beammp-agent est configuré (sinon : "redémarrage requis", comme le reste du panel).

Un mod/véhicule supprimé depuis la sauvegarde de la config est ignoré silencieusement à l'application plutôt que de la rendre inutilisable — le résultat affiché indique combien ont été ignorés.

Les configs restent éditables à tout moment (ajout/retrait d'éléments, changement de carte, renommage) depuis l'icône crayon de chaque config. Le bouton "Utiliser les actifs actuels" dans l'éditeur pré-remplit la sélection avec l'état actif du moment — pratique pour créer une config à partir d'une configuration déjà en place.

---

Mise à jour

Installé avec install.sh : bouton Mettre à jour de la carte « Mise à jour du panel » (Administration). Le panel ne fait que déposer une demande dans update/ ; l'hôte relance install.sh, qui revérifie la signature, refuse toute version plus ancienne que celle en place, reconstruit le conteneur et revient à la version précédente si le panel ne répond pas dans la nouvelle. Journal : DOSSIER/update.log. Relancer la commande d'installation fait la même chose à la main.

Installé avec git :

git pull
docker compose up -d --build

La base SQLite est conservée dans le volume app_data (/app/data/panel.db). Le schéma se crée et se met à jour automatiquement au démarrage.

Voir CHANGELOG.md pour le détail des versions.

Depuis la 1.3.0 — TRUST_PROXY_HOPS n'existe plus et est ignoré silencieusement. Derrière un reverse proxy, le remplacer par TRUST_PROXY=<IP du proxy> dans .env, sinon toutes les requêtes semblent venir du proxy et le rate-limit de login devient commun à tous les utilisateurs.

---

Sauvegarde

Le volume app_data (base SQLite panel.db) est la seule copie des comptes, joueurs connus, mods et configs — sans sauvegarde, sa perte est irréversible.

./scripts/backup-db.sh            # copie à chaud vers ./backups/, gardée 14 jours
./scripts/backup-db.sh /mnt/nas    # ou un dossier externe à l'hôte Docker

À planifier via cron sur l'hôte, avec un chemin absolu :

0 3 * * * /opt/app-docker/beammp-panel/scripts/backup-db.sh >> /opt/app-docker/beammp-panel/backup.log 2>&1

scripts/backup-postgres.sh (nom de la v2) est gardé et appelle backup-db.sh : un cron existant continue de fonctionner tel quel.

Restauration :

docker compose stop app
gunzip -c backups/beammp-panel-20260101-030000.sqlite.gz > /tmp/panel.db
docker compose cp /tmp/panel.db app:/app/data/panel.db
docker compose start app

Testez périodiquement une restauration réelle — une sauvegarde jamais restaurée n'est qu'une hypothèse.

---

Passage de la v2 à la v3

Depuis le dossier d'une installation v2 en place :

git fetch origin && git show origin/v3-python:scripts/upgrade-to-v3.sh | sh -s

Le script fait une sauvegarde pg_dump fraîche (avec la v2 encore en marche), bascule le code, construit l'image, importe la sauvegarde dans SQLite (comptes et mots de passe, joueurs connus, mods, configs, mêmes identifiants), démarre la v3 et vérifie qu'elle répond. Avec le même JWT_SECRET, les sessions ouvertes restent valides.

Le volume postgres_data n'est jamais supprimé. Retour arrière :

git checkout v2 && docker compose up -d --build

Import manuel (autre machine, autre sauvegarde) :

python -m beammp_panel.importer --dump backups/beammp-panel-XXXX.sql.gz --db data/panel.db

---

Migration depuis la V1 (MariaDB)

Ce script fait partie de la branche v2 (il écrit dans PostgreSQL) : pour une installation V1, migrer d'abord vers la v2, puis passer en v3.

scripts/migrate-v1-to-v2.mjs reprend les données de l'ancien panel (PHP + MariaDB) une fois les mods déjà enregistrés en V2 via Scan & Import. Mode aperçu par défaut (aucune écriture sans --apply).

Prérequis — le site V1 (dossier contenant son .env et DATA/images/ + DATA/descriptions/) doit être accessible en lecture depuis la machine qui lance le script, et sa base MariaDB démarrée et joignable (DB_HOST/ DB_NAME/DB_USER/DB_PASSWORD sont lus directement depuis le .env du site V1, pas besoin de les ressaisir).

# Aperçu (rien n'est modifié)
node scripts/migrate-v1-to-v2.mjs --v1-root=/var/www/mon-ancien-site

# Application réelle
node scripts/migrate-v1-to-v2.mjs --v1-root=/var/www/mon-ancien-site --apply

Ce qui est repris

Donnée V1	Effet côté V2	Détail
Cartes officielles BeamNG (map_officielle = 1)	mods (nouvelle ligne, is_official=true)	Ces cartes du jeu de base (sans .zip) n'ont aucun chemin de création côté V2 en dehors de ce script — absentes du catalogue tant qu'elles n'ont pas été importées ainsi. Créées inactives ; jamais activées automatiquement.
Images (beammp_Officiel.image)	mods.image	Pour chaque mod déjà présent en V2 (même filename), l'image V1 remplace l'image actuelle (l'extraction automatique depuis le zip donne souvent un résultat de moins bonne qualité qu'une image choisie à la main).
Descriptions (beammp_Officiel.description)	mods.description	Ne remplit que les descriptions V2 actuellement vides (jamais d'écrasement — contrairement aux images, c'est du texte éditorial qui a pu être réécrit côté V2). Les descriptions V1 auto-générées ("Description non fournie.", "Description pour X") sont ignorées.
Joueurs (beammp_users_Officiel)	known_players	Fusionné avec les stats V2 existantes plutôt qu'écrasé : connection_count/temps de jeu s'additionnent (périodes disjointes avant/après bascule), les dates prennent la plus ancienne/récente des deux sources. Le rang (🥉🥈🥇💎, visible dans Joueurs) est recalculé automatiquement depuis connection_count — rien à migrer séparément.
Mods sans équivalent V2	(rapport seulement, aucune écriture)	Un mod ne peut pas être recréé sans son .zip — le script liste ceux qui n'ont pas de ligne V2 correspondante, à traiter via Scan & Import si le fichier est toujours dans Resources/.

Non repris, volontairement : les comptes admin V1 (users) — schéma de mot de passe différent, et V2 a son propre flux de compte (demande + approbation). Créer les comptes nécessaires depuis Administration.

Idempotent pour les images (une resynchronisation écrase avec la même valeur) et les descriptions (ne touche jamais une ligne déjà remplie), mais pas pour les joueurs si relancé avec les mêmes données V1 — la fusion additionne les compteurs à chaque exécution. Ne lancer l'import joueurs qu'une fois par site V1 source.

---

Variables d'environnement

Application

Variable	Défaut	Obligatoire	Description
APP_PORT	3000		Port d'écoute du panel (côté hôte — voir aussi PORT ci-dessous)
JWT_SECRET	—	Oui	Clé secrète JWT — min 32 chars (openssl rand -hex 32)
COOKIE_SECURE	false		Mettre true derrière un reverse proxy HTTPS
ALLOWED_ORIGIN	—		URL du panel pour CORS si domaine différent
TRUST_PROXY	—		Adresse/CIDR du reverse proxy en amont (ex. 127.0.0.1), ou true. Laisser vide si le panel est exposé directement — sinon le rate-limit de login peut être contourné en forgeant X-Forwarded-For
SUPERADMIN_USERNAME	—		Login du superadmin (premier démarrage uniquement)
SUPERADMIN_PASSWORD	—		Mot de passe min 8 chars (premier démarrage uniquement)
PORT	3000		Avancé — port interne au conteneur. Ne pas confondre avec APP_PORT
HOST	0.0.0.0		Adresse d'écoute
DATA_DIR	/app/data		Dossier des données : base SQLite, images par défaut
DB_PATH	DATA_DIR/panel.db		Chemin de la base SQLite
IMAGES_PATH	/app/images		Images de mods
INSTANCE_NAME	BeamMP Server		Nom affiché en mode instance unique
TZ	Europe/Paris		Fuseau horaire de l'hôte (Docker) : BeamMP écrit Server.log en heure locale, le panel doit lire les mêmes heures

Base de données

SQLite, un seul fichier (DB_PATH) : rien à configurer. Les variables POSTGRES_* de la v2 ne servent plus, sauf à l'outil d'import (--dsn) ; elles peuvent rester dans le .env.

Instance BeamMP

Variable	Défaut	Description
BEAMMP_SERVER_IP	—	IP publique du serveur (statut temps réel)
BEAMMP_SERVER_PORT	—	Port UDP du serveur BeamMP
BEAMMP_RESOURCES_PATH	—	Chemin hôte vers Resources/
BEAMMP_LOG_DIR	—	Chemin hôte vers le dossier contenant Server.log (pas le fichier — voir note plus haut)
BEAMMP_CONFIG_PATH	—	Chemin hôte vers ServerConfig.toml
BEAMMP_INFO_HOST	host.docker.internal	Hôte interrogé en direct sur le port de jeu (BEAMMP_SERVER_PORT, défaut 30814) pour le statut : joueurs, carte, mods, même en serveur privé. Vide = désactivé
BEAMMP_API_HOST	localhost	Host de l'API HTTP BeamMP (optionnel)
BEAMMP_API_PORT	4444	Port de l'API HTTP BeamMP

Agent de redémarrage (optionnel — voir Redémarrage du serveur)

Variable	Défaut	Description
BEAMMP_AGENT_URL	—	URL de beammp-agent sur l'hôte (IP de la passerelle Docker, pas 0.0.0.0/IP LAN)
BEAMMP_AGENT_TOKEN	—	Doit correspondre à RESTART_TOKEN dans /etc/beammp-agent.env
BEAMMP_AGENT_SERVICE	—	Nom du service systemd à redémarrer (doit être dans ALLOWED_SERVICES côté agent)
BEAMMP_AGENT_ASSET	—	Suffixe de l'asset BeamMP-Server à installer (ex. debian.13.x86_64) — active la mise à jour du binaire

Côté hôte, l'agent lit RESTART_TOKEN (dans /etc/beammp-agent.env), ALLOWED_SERVICES, AGENT_HOST, AGENT_PORT (défaut 4445) et BEAMMP_BINARY_PATH (dans le unit systemd).

Discord (optionnel)

Le plus simple : Configuration → Discord dans le panel (superadmin). On y colle un webhook par salon et par serveur, on le teste, et on peut réécrire le texte de chaque message (variables entre accolades, ex. {player}, {map}). Un champ vide reprend les variables ci-dessous, puis le texte par défaut.

Variable	Défaut	Description
DISCORD_WEBHOOK_URL	—	Webhook global (fallback)
DISCORD_WEBHOOK_RESTART	—	Webhook redémarrages
DISCORD_WEBHOOK_PLAYERS	—	Webhook connexions joueurs
DISCORD_WEBHOOK_MODS	—	Webhook uploads mods et changements de carte
DISCORD_SERVER_URL	—	Lien invitation Discord dans le panel
DISCORD_NOTIFY_JOIN	true	Notifier connexions (avec rang par ancienneté — Bronze/Argent/Or/Platine)
DISCORD_NOTIFY_LEAVE	true	Notifier déconnexions
DISCORD_NOTIFY_MOD_UPLOAD	true	Notifier uploads de mods
DISCORD_NOTIFY_MAP_CHANGE	true	Notifier les changements de carte active
DISCORD_NOTIFY_RESTART	true	Notifier redémarrages, mises à jour et plantages

Public

Variable	Description
SERVER_DESCRIPTION	Description affichée sur la page publique
KOFI_URL	Lien Ko-fi affiché dans le panel

---

Rôles et comptes

Rôle	Permissions
superadmin	Tout — gestion utilisateurs, validation de comptes, réinitialisation de mot de passe, import
admin	Mods, maps, configuration, logs, cohérence BDD, import, redémarrage serveur
moderator	Consultation uniquement — pas d'accès aux logs serveur, aucune action de mutation

Un changement de rôle ou une suppression de compte prend effet immédiatement sur les sessions déjà ouvertes (le rôle est revérifié en base à chaque requête, pas seulement lu depuis le cookie de session) — pas besoin d'attendre l'expiration du cookie (7 jours) ni de déconnecter l'utilisateur.

Création de compte joueur

1. Le joueur se connecte au serveur BeamMP → enregistré automatiquement
2. Il visite le panel → "Demander un compte" → saisit son pseudo BeamMP exact
3. Le SuperAdmin valide la demande dans Administration → définit un mot de passe initial. Le compte est créé en rôle moderator par défaut (moindre privilège) ; promotion en admin via une action explicite du SuperAdmin.
4. Le joueur peut se connecter

Mot de passe

Tout utilisateur connecté peut changer son propre mot de passe via l'icône clé à côté du bouton de déconnexion (mot de passe actuel requis).

Un SuperAdmin peut aussi réinitialiser le mot de passe de n'importe quel compte existant depuis Administration → Utilisateurs (icône clé), sans avoir à supprimer puis recréer le compte — utile en cas de perte, ou pour fixer un mot de passe temporaire à un compte nouvellement créé.

---

Sécurité

• Sessions httpOnly + SameSite=Strict (pas de token en localStorage), rôle revérifié en base à chaque requête (pas de session périmée après un changement de rôle ou une suppression de compte)
• Cookie Secure activé via COOKIE_SECURE=true derrière HTTPS
• Mots de passe bcrypt coût 12 — migration transparente depuis les anciens hashes scrypt
• Uploads validés par magic bytes (signature ZIP PK\x03\x04)
• Conteneur non-root (UID 1000)
• Headers de sécurité identiques à la v2 (CSP sans unsafe-inline sur les scripts, X-Frame-Options, nosniff…)
• Rate limiting par IP : /api/auth/login et /api/auth/request-account (5 req/min chacun), redémarrage serveur (3 req/min) — voir TRUST_PROXY si le panel est derrière un reverse proxy, sinon le rate-limit reste basé sur l'IP directe
• Toutes les opérations fichier (upload, cohérence, import) sanitisent les noms de fichiers et vérifient que le chemin résolu reste dans le dossier attendu
• beammp-agent (redémarrage) : token dans un fichier dédié en 600 (jamais dans le unit systemd, lisible par défaut), lié à l'IP de la passerelle Docker du projet (pas 0.0.0.0 ni l'IP LAN), aucun endpoint fichier exposé au-delà du strict nécessaire

---

Licence

Elastic License 2.0 — vous pouvez utiliser, copier, modifier et redistribuer le panneau, y compris pour une communauté ou un club qui encaisse des inscriptions. Il est interdit de le proposer à des tiers comme service hébergé ou géré et de retirer les mentions de licence. © 2026 Florian Praturlon. Même licence que AC EVO Server Panel.