Documentation

Installation#

Deux façons d'héberger Agora. Choisis celle qui correspond à ton infrastructure.

Prérequis

• Une machine avec Docker (VPS, NAS, serveur dédié) ou un panel Pterodactyl / Pelican — 1 Go de RAM minimum, 2 Go conseillés
• Une application Discord (identifiant client et secret) pour la connexion des membres
• Une adresse pour le site : un domaine derrière un reverse proxy, ou simplement http://IP:PORT — aucun nom de domaine n'est obligatoire
• Un accès HTTPS sortant vers le serveur de mises à jour et vers discord.com
• Pour le MDT seulement : la base MySQL / MariaDB de ton serveur FiveM, joignable depuis le conteneur Agora
• Une clé de licence : la clé d'essai gratuite de 14 jours s'obtient dans ton espace client, sans carte bancaire

Docker Compose#

Crée un dossier, télécharge l'amorçage public dedans (curl -fsSL https://agora-app.fasterplayer.ca/boot.mjs -o boot.mjs), puis place ces deux fichiers à côté.

docker-compose.yml

# Agora — déploiement Docker Compose.
#   1. crée .env à partir du modèle ci-dessous et remplis-le — la clé de
#      licence est obligatoire dès le premier démarrage : sans elle, il n'y a
#      rien à télécharger et le conteneur s'arrête en le disant
#   2. télécharge l'amorçage public : curl -fsSL https://agora-app.fasterplayer.ca/boot.mjs -o boot.mjs
#      (seul fichier exécuté depuis l'extérieur ; le produit lui-même arrive
#      au premier démarrage, contre la licence, signature et sha256 vérifiés)
#   3. docker compose up -d
#   4. ouvre le forum (http://IP:PORT, ou SITE_URL si tu as un domaine) : toute
#      adresse mène à l'écran de mise en route, qui demande la clé, le nom du
#      site et les identifiants Discord, et affiche l'URL de redirection exacte
#      à coller dans le portail Discord. Aucun nom de domaine n'est nécessaire.
# Une commande automatise ces quatre étapes :
#   curl -fsSL https://agora-app.fasterplayer.ca/install.sh | sh -s -- TA-CLE-DE-LICENCE
# Administration → Mises à jour indique la version installée et celle qui est disponible.
# Tout l'état (base, application, pièces jointes) vit dans les volumes ci-dessous.

services:
  db:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: agora
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?mot de passe requis dans .env}
      POSTGRES_DB: agora
      LANG: C.UTF-8
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U agora -d agora"]
      interval: 5s
      timeout: 5s
      retries: 20

  agora:
    # Image Node publique et ordinaire : le produit n'a pas d'image à lui,
    # boot.mjs le télécharge au démarrage contre la licence. `ghcr.io/
    # fasterplayer/agora-runtime` n'est PAS publique (pull access denied) :
    # ne pas s'en servir, même en exemple.
    image: node:22-alpine
    restart: unless-stopped
    # PID 1 = docker-init (livré avec Docker) : récolte les processus orphelins
    # (npx, prisma, tar) et relaie l'arrêt. Moteur sans docker-init : retire cette ligne.
    init: true
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://agora:${POSTGRES_PASSWORD}@db:5432/agora?schema=public
      # SITE_URL est FACULTATIVE : sans domaine, le forum s'ouvre par
      # http://IP:PORT et l'adresse de rappel OAuth est déduite de la requête.
      AUTH_URL: ${SITE_URL:-}
      # Sans AUTH_URL, Auth.js refuse toute connexion en production : c'est
      # cette ligne qui rend l'installation par IP utilisable.
      AUTH_TRUST_HOST: "true"
      AUTH_SECRET: ${AUTH_SECRET:-}
      # FACULTATIFS : l'écran de mise en route les demande au premier
      # démarrage, avec l'URL de redirection déjà calculée.
      AUTH_DISCORD_ID: ${AUTH_DISCORD_ID:-}
      AUTH_DISCORD_SECRET: ${AUTH_DISCORD_SECRET:-}
      DISCORD_BOT_TOKEN: ${DISCORD_BOT_TOKEN:-}
      DISCORD_GUILD_ID: ${DISCORD_GUILD_ID:-}
      AGORA_SITE_NAME: ${AGORA_SITE_NAME:-Agora}
      AGORA_SITE_LOCALE: ${AGORA_SITE_LOCALE:-fr}
      AGORA_SEED_ON_BOOT: "true"
      AGORA_LICENSE_KEY: ${AGORA_LICENSE_KEY:-}
      AGORA_UPDATE_CHANNEL: ${AGORA_UPDATE_CHANNEL:-stable}
      # Chemin des données persistantes (application, pièces jointes, identité de licence).
      AGORA_DATA: /data
      TZ: ${TZ:-America/Toronto}
    entrypoint: ["node", "/boot/boot.mjs"]
    volumes:
      - ./boot.mjs:/boot/boot.mjs:ro
      - agora_app:/app
      - agora_data:/data
    ports:
      - "${AGORA_PORT:-3000}:3000"

  # Reverse proxy HTTPS automatique (facultatif : retire ce service si tu as déjà
  # Nginx / Traefik / Cloudflare Tunnel devant le port AGORA_PORT).
  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    profiles: ["caddy"]
    depends_on:
      - agora
    command: caddy reverse-proxy --from ${SITE_ADDRESS:-:80} --to agora:3000
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - caddy_data:/data
      - caddy_config:/config

volumes:
  db_data:
  agora_app:
  agora_data:
  caddy_data:
  caddy_config:

.env

# ── Agora : configuration du déploiement (.env) ──
# URL publique du site (avec https si tu as un reverse proxy / tunnel)
SITE_URL=https://forum.mondomaine.com
# Port publié sur l'hôte (derrière ton reverse proxy)
AGORA_PORT=3000

# Base Postgres (créée automatiquement par docker compose)
POSTGRES_PASSWORD=change-moi

# Secret de session (facultatif : généré et conservé automatiquement si vide)
AUTH_SECRET=

# Application Discord (https://discord.com/developers/applications)
#   OAuth2 → Redirects : SITE_URL/api/auth/callback/discord
AUTH_DISCORD_ID=
AUTH_DISCORD_SECRET=
# Facultatif : bot + serveur Discord pour la synchro des rôles
DISCORD_BOT_TOKEN=
DISCORD_GUILD_ID=

# Identité
AGORA_SITE_NAME=Mon serveur RP
AGORA_SITE_LOCALE=fr
TZ=America/Toronto

# Licence : OBLIGATOIRE dès le premier démarrage. Clé d'essai gratuite (14 jours,
# palier Basic) dans ton espace client → Installation.
AGORA_LICENSE_KEY=
# Canal de mises à jour : stable (défaut) ou beta
AGORA_UPDATE_CHANNEL=stable

# Avec le profil caddy (docker compose --profile caddy up -d) : ton domaine pour le HTTPS auto
SITE_ADDRESS=forum.mondomaine.com

Remplis le fichier .env : seuls POSTGRES_PASSWORD et AGORA_LICENSE_KEY sont obligatoires. SITE_URL, AUTH_DISCORD_ID et AUTH_DISCORD_SECRET sont facultatifs — laissés vides, l'écran de mise en route les demande au premier démarrage.

Démarre, puis ouvre SITE_URL dans ton navigateur. Le premier démarrage télécharge la version courante d'Agora, applique les migrations et crée la structure de départ (groupes, sections du forum, formulaire de whitelist).

docker compose up -d
docker compose logs -f agora

Reverse proxy ou Caddy

Le site écoute sur AGORA_PORT (3000 par défaut). Mets ton reverse proxy devant (Nginx, Traefik, Cloudflare Tunnel), ou active le profil Caddy pour un HTTPS automatique avec SITE_ADDRESS :

docker compose --profile caddy up -d

Données persistantes

Trois volumes contiennent tout : db_data (Postgres), agora_app (l'application — sans lui, tout serait retéléchargé à chaque recréation du conteneur) et agora_data (versions, pièces jointes, identité de licence). Sauvegarde au moins db_data et agora_data ; agora_app se retélécharge tout seul si tu le perds.

Pterodactyl / Pelican#

1. Dans l'administration du panel, va dans Nests (Pterodactyl) ou Eggs (Pelican) → Import, puis importe le fichier de TON panel : /agora-egg.json pour Pterodactyl, /agora-egg-pelican.json pour Pelican. Les deux décrivent la même installation ; seul le format des règles de validation change — se tromper de fichier ne bloque pas l'import, mais met en 500 toute l'API client du panel (console, fichiers, déploiement de la ressource).
2. Crée un serveur avec cet egg : 1 Go de RAM minimum (2 Go conseillés), 2 Go de disque et une allocation de port (le site écoute dessus).
3. Renseigne les variables ci-dessous. DATABASE_URL est obligatoire : indique l'URL complète de ta base Postgres (postgresql://user:motdepasse@hote:5432/agora) — cet egg ne fournit pas de Postgres embarqué, prévois-en un (conteneur séparé ou base externe).
4. Démarre le serveur. La console affiche le téléchargement de l'amorçage puis de l'application, les migrations, puis « Ready in » : c'est cette ligne précise que le panel surveille pour considérer le serveur démarré.

Aucune modification du config.yml de Wings n'est nécessaire.

Variables de l'egg

Première connexion (Discord)#

1. Sur discord.com/developers/applications, crée une application (ou réutilise celle de ton serveur).
2. OAuth2 → Redirects : ajoute l'URL de rappel ci-dessous, en remplaçant le domaine par l'adresse publique de ton site (SITE_URL ou AUTH_URL). Même protocole (http ou https), même domaine et même port.
3. Copie le Client ID et le Client Secret dans ton fichier .env ou dans les variables de l'egg, puis redémarre. Tu pourras aussi les changer plus tard depuis Administration → Paramètres → Discord, sans redémarrage.
4. Ouvre le site et connecte-toi avec Discord. Ton compte est créé — il n'est pas encore administrateur : voir la section suivante.

https://forum.mondomaine.com/api/auth/callback/discord

Bot Discord (facultatif)

Pour synchroniser les rôles Discord avec les groupes du forum et attribuer un rôle lors d'une promotion (candidature acceptée), renseigne DISCORD_BOT_TOKEN et DISCORD_GUILD_ID, active Server Members Intent, invite le bot avec la permission Manage Roles, et place son rôle AU-DESSUS des rôles qu'il doit distribuer.

Devenir administrateur#

Le premier compte connecté ne devient pas administrateur automatiquement : il reçoit le groupe par défaut. Il faut accorder le groupe admin explicitement, une seule fois.

Connecte-toi une première fois avec Discord pour que ton compte existe, puis lance la commande correspondant à ton installation. Déconnecte-toi et reconnecte-toi ensuite : le lien Admin apparaît dans l'en-tête.

Docker Compose

docker compose exec agora sh -c \
  'cd /data/app/versions/$(cat /data/app/current) && node scripts/make-admin.mjs TON_PSEUDO'

Le script accepte aussi ton identifiant Discord ou ton adresse e-mail à la place du pseudo.

Pterodactyl / Pelican

Le panel n'offre pas de shell. Deux chemins : si tu utilises un Postgres externe, exécute la requête ci-dessous ; sinon, remplace temporairement la commande de démarrage du serveur par la commande Docker ci-dessus adaptée à /home/container/data, lis la confirmation dans la console, puis remets node /opt/agora/supervisor.mjs.

INSERT INTO "UserGroupMember" ("userId", "groupId")
SELECT u.id, g.id
FROM "User" u, "UserGroup" g
WHERE u.username = 'TON_PSEUDO' AND g.key = 'admin'
ON CONFLICT DO NOTHING;

Deux niveaux de staff

• Groupe admin : tout — Paramètres, MDT, Licence, Mises à jour, Sauvegardes, Base de données, Console, Webhooks.
• Groupe moderateur : la gestion du forum et les candidatures seulement.
• Case « Apparaît sur la page Staff » : purement décorative, elle n'accorde aucun droit.

Serveur FiveM : base de données et ressource#

Le forum fonctionne sans serveur de jeu. Le MDT, la concession, l'effectif/RH et la carte live lisent la vraie base de ton serveur FiveM (ESX, QBCore, QBox). Tout se règle dans Administration → MDT.

Brancher la base du jeu

• Hôte : depuis un conteneur, localhost désigne le conteneur lui-même. Utilise l'IP locale de la machine (192.168.x.x), le nom du service Docker, ou l'IP publique du serveur de jeu.
• Framework : esx, qbcore ou qbox. ESX lit la table users, QBCore et QBox lisent players.
• Colonne Discord : détectée automatiquement (players.discord, ou users.discord par jointure userId sur QBox). Si ta base n'en a pas, la liaison se fait par identifiant FiveM à la première connexion depuis la tablette.
• Le mot de passe est chiffré au repos (AES-256-GCM) : un dump de la base d'Agora ne le révèle pas.
• Bouton Tester : il affiche la version MySQL, le nombre de personnages trouvés et la source du Discord ID.

L'utilisateur MySQL

N'utilise pas root. Agora lit tes personnages, tes jobs et tes véhicules, et crée ses propres tables préfixées agora_ dans la même base (fiches, mandats, avis de recherche, arrestations, rapports, dossiers médicaux, code pénal, journal des modifications).

-- Remplace 203.0.113.10 par l'IP de la machine qui héberge Agora.
CREATE USER 'agora'@'203.0.113.10' IDENTIFIED BY 'un-mot-de-passe-long';

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX, ALTER, REFERENCES
  ON `nom_de_ta_base`.* TO 'agora'@'203.0.113.10';

FLUSH PRIVILEGES;

Sans le droit CREATE, le MDT ne peut pas créer ses tables et le dit explicitement. Sans droit d'écriture sur tes tables à toi, tout fonctionne sauf la concession, qui doit débiter le joueur et déposer le véhicule.

La ressource in-game

La ressource agora ouvre la tablette en jeu et envoie la présence (qui joue, avec quel personnage). Elle embarque déjà l'URL du site, le secret, la commande, la touche et le framework : aucune convar à ajouter.

1. Administration → Paramètres → In-game : choisis la commande (/agora par défaut) et la touche (F2 par défaut, rebindable par chaque joueur).
2. Déploie-la en un clic via le panel Pterodactyl / Pelican, ou par SFTP, ou télécharge agora.zip et dézippe-le dans resources/ en gardant le nom du dossier.
3. Ajoute ensure agora à server.cfg, APRÈS le framework (qbx_core / qb-core / es_extended), puis refresh + ensure agora.
4. Vérifie dans Administration → MDT : « Dernier signal de la ressource agora » doit dater de moins de 30 secondes.

Coût sur le serveur de jeu : client à 0,00 ms au repos (aucune boucle, aucun export framework), un seul envoi périodique côté serveur (la présence, toutes les 30 s), aucun polling. La carte live n'envoie rien tant que personne ne la regarde.

Permissions et accès#

Agora a deux systèmes de droits indépendants. Les confondre est la première source de confusion.

Le forum : des groupes

• Chaque section déclare les groupes qui peuvent la lire et ceux qui peuvent y écrire. Une liste vide veut dire « ouvert », jamais « fermé à tous ».
• Écrire suppose de pouvoir lire. Les groupes admin et moderateur passent outre lecture, écriture et verrouillage.
• Un membre entre dans un groupe à l'inscription (groupes par défaut), à l'acceptation d'une candidature, ou à la main. Le rôle Discord correspondant suit automatiquement.

Le MDT : job et grade

Personnage joué → job et grade lus dans la base du jeu → département MDT (POLICE, DOJ, EMS ou AUTRE) → permissions accordées à partir d'un grade minimum. Rien n'est saisi deux fois : promeus un agent en jeu, ses droits suivent.

• Douze permissions réglables par grade : accéder au MDT, l'utiliser hors jeu, modifier ou supprimer une fiche, émettre et servir un mandat, enregistrer une arrestation, rédiger un rapport, chercher une plaque, prendre une photo de dossier, créer un dossier médical, gérer le code pénal.
• « Utiliser le MDT hors jeu » est la permission clé : sans elle, le MDT n'est accessible qu'en étant connecté au serveur — dans la tablette, ou dans un navigateur pendant qu'on joue.
• Le département AUTRE donne les mêmes outils avec un thème neutre : utile pour ouvrir la recherche de plaques à un garagiste sans lui donner mandats et arrestations.
• Sans base du jeu configurée, Agora retombe sur les groupes police, doj et ems, avec toutes les permissions et sans notion de grade.
• Mode test administrateur « Voir comme » : tu vois exactement ce que voit un joueur d'un job à un grade donné, refus compris.

Le forum, les candidatures, les dons et les profils ne sont JAMAIS verrouillés par la licence. Le MDT l'est (formule Basic), ainsi que le panel d'hébergement, la console et l'explorateur de base (formule Pro).

Ce que couvre Agora#

Un aperçu des modules. Chacun a son chapitre dans la documentation livrée avec le produit.

Sauvegardes#

Tes données vivent dans deux bases. Une sauvegarde d'Agora ne contient aucun dossier du MDT : ceux-là vivent dans la base de ton serveur de jeu, en tables agora_.

Administration → Sauvegardes crée, liste, restaure et supprime des sauvegardes de la base d'Agora, et accepte aussi un fichier .sql envoyé depuis ton navigateur. Une sauvegarde est faite automatiquement avant chaque mise à jour. Les mêmes fichiers restent lisibles avec les outils PostgreSQL habituels (pg_dump, psql). Sauvegarde aussi le volume de données, qui contient les pièces jointes et l'identité de licence — il n'est dans aucun dump SQL.

• Base d'Agora (membres, forum, candidatures, réglages, licence) : depuis Administration → Sauvegardes, ou pg_dump sur le conteneur Postgres.
• Dossiers du MDT (tables agora_) : avec ta sauvegarde habituelle de la base du serveur de jeu.
• Pièces jointes du forum et des dossiers : des fichiers sur disque, dans le volume de données — ils ne sont dans aucun dump SQL.
• AUTH_SECRET : le perdre rend illisibles les secrets chiffrés (mot de passe MySQL, tokens Discord, secret in-game), qu'il faudra ressaisir.
• Avant une mise à jour, Agora sauvegarde la base tout seul — mais garde quand même tes propres copies hors de la machine : une migration ne se défait pas, et un disque qui meurt emporte les sauvegardes locales avec lui.

Activer la licence#

Agora a besoin d'une clé de licence dès l'installation : c'est elle qui lui permet de télécharger sa version. Prends ta clé d'essai gratuite dans ton espace client (Mon espace → Installation) — 14 jours au palier Basic, forum + MDT, sans carte bancaire — et donne-la au conteneur par la variable AGORA_LICENSE_KEY (ou le champ « Clé de licence » d'un panel). Le décompte des 14 jours ne commence qu'à la première activation. Pour essayer le Pro, la page Tarifs propose 30 jours de Pro pour une somme symbolique (une fois par compte).

Pour continuer après l'essai, achète une clé sur la page Tarifs. Elle se consulte uniquement dans ton espace client (Mon espace → Licence → Afficher la clé) : tu reçois une notification Discord avec le lien, jamais la clé. Depuis Administration → Licence de ton essai, le bouton « Passer au payant » t'amène directement sur la page Tarifs avec −50 % sur ton premier mois (pendant l'essai et jusqu'à 7 jours après). Voir les tarifs

1. Sur une installation neuve : l'écran de mise en route demande la clé au premier lancement, en même temps que le nom du site et les identifiants Discord.
2. Sur une installation qui tourne déjà : ouvre Administration → Licence, colle la clé, enregistre.
3. L'état de la licence et le palier s'affichent immédiatement. La variable d'environnement AGORA_LICENSE_KEY fait la même chose au démarrage, et c'est elle qu'attend le conteneur à la toute première installation.

Sans licence active

Le forum reste toujours ouvert. Le MDT et les fonctions Pro continuent 14 jours de grâce, puis se verrouillent jusqu'à l'activation d'une clé. Aucune donnée n'est supprimée.

Une clé correspond à une installation. Pour déplacer ton installation sur une autre machine, ouvre un billet sur le Discord de support afin de la détacher.

Ce qui est transmis au serveur de licences : identifiant d'installation, empreinte, hôte, version, plateforme, langue. Jamais d'IP locale, de données de membres, ni de secret.

Mises à jour#

Administration → Mises à jour affiche la version installée et celle qui est disponible sur ton canal, avec un bouton pour la poser. La séquence est toujours la même, et son avancement s'affiche à l'écran :

1. Sauvegarde de la base, faite par Agora avant toute autre chose, dans le dossier des sauvegardes.
2. Téléchargement de la nouvelle version, vérifiée par signature du manifeste et empreinte sha256.
3. Migrations de la base, puis redémarrage. Si une migration échoue, l'installation reste sur la version en cours.
4. Contrôle de santé, et retour automatique à la version précédente si la nouvelle ne démarre pas : l'ancienne reste sur le disque jusqu'à ce que la nouvelle ait prouvé qu'elle démarre.
5. Cette séquence vaut pour les installations faites avec notre installeur, l'egg de panel ou l'image de runtime. Une image que tu as bâtie toi-même se met à jour comme n'importe quelle image, et c'est alors ta sauvegarde qui te couvre.

Canal de mises à jour

stable (recommandé) ou beta, via AGORA_UPDATE_CHANNEL. L'accès aux mises à jour suit la licence ou l'essai.

Après une mise à jour, redéploie la ressource FiveM si sa version a changé : celle attendue est affichée dans Administration → MDT.

Dépannage#

Les cas les plus fréquents. Si rien ne correspond, ouvre un billet sur le Discord de support avec tes journaux.