FireFlo SMS/SMPP Gateway

Ce que fireflo-install automatise. Lisez ceci si vous empaquetez FireFlo vous-même, ou si une étape de l’installateur a échoué et que vous avez besoin de savoir ce qu’elle faisait.

Les prérequis ci-dessous sont scriptés. setup.sh installe PostgreSQL, RabbitMQ et Node sur Ubuntu et Debian, et Java derrière --with-java. Cette page est la version longue — lisez-la pour savoir ce que fait ce script, ou pour le faire sur une distribution qu’il refuse.

Prérequis

Java 25. La compilation cible la version 25 et ne fonctionnera pas sur 21.
PostgreSQL 14 ou plus récent. Optionnel pour la passerelle seule en mode fichier ; requis pour le panneau de contrôle, le crédit prépayé, la liste blanche et les enregistrements d’appels dans une table.
RabbitMQ, uniquement si les messages soumis doivent survivre à un redémarrage de la passerelle. Sans lui, la file est en mémoire et un redémarrage perd tout ce qui n’a pas atteint un fournisseur.
Un utilisateur de service sans shell de connexion.

La partie délicate de cette plateforme

Deux des trois runtimes ne sont pas ceux fournis par Ubuntu :

Besoin	Ubuntu 24.04 fournit	À faire
Java 25	`openjdk-21`	Ajouter Adoptium
Node 22	`nodejs` 18	Ajouter NodeSource
PostgreSQL 14+	PostgreSQL 16	`apt install postgresql`

Paquets de base

sudo apt update
sudo apt install -y wget curl gpg apt-transport-https ca-certificates ufw nginx postgresql

Java 25 depuis Adoptium

sudo mkdir -p /etc/apt/keyrings
wget -qO- https://packages.adoptium.net/artifactory/api/gpg/key/public \
  | sudo tee /etc/apt/keyrings/adoptium.asc > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/adoptium.asc] \
https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/adoptium.list
sudo apt update && sudo apt install -y temurin-25-jdk
java -version        # doit afficher 25

Node 22 depuis NodeSource

Next.js 16 ne tourne pas sur le Node 18 d’Ubuntu — c’est pour le panneau de contrôle.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version       # doit afficher v22 ou plus récent

Utilisateur de service et répertoires

sudo useradd --system --home-dir /opt/fireflo --shell /usr/sbin/nologin fireflo
sudo install -d -o fireflo -g fireflo /opt/fireflo /etc/fireflo /var/lib/fireflo /var/log/fireflo
sudo chmod 750 /etc/fireflo

Base de données

sudo -u postgres createuser fireflo --pwprompt
sudo -u postgres createdb fireflo --owner fireflo

Gardez le mot de passe hors de l’historique du shell — écrivez-le directement dans le fichier d’environnement.

Disposition

La configuration est conservée en dehors du répertoire d’artefact, afin qu’une mise à niveau puisse remplacer l’artefact en bloc sans toucher à ce que vous avez édité.

/opt/fireflo/            appartient à fireflo, REMPLACÉ à la mise à niveau
  quarkus-run.jar
  lib/  app/  quarkus/
  bin/fireflo            la CLI opérateur, gardée hors de ce qu'une mise à niveau remplace

/etc/fireflo/            appartient à fireflo, JAMAIS remplacé à la mise à niveau
  fireflo.env            environnement, y compris le mot de passe de la BD. chmod 600
  smsg.properties        workers et paramètres     \
  credentials.yml        identifiants               |  mode fichier seulement
  routingTable.conf      routage                    |
  rates.conf             tarifs                    /

/var/lib/fireflo/        le stockage des accusés, et les CDR quand il n'y a pas de BD
/var/log/fireflo/        journaux

Si vous avez compilé l’empaquetage JVM, l’artefact est un répertoire, pas un fichier. quarkus-run.jar ne s’exécutera pas sans les répertoires lib/, app/ et quarkus/ à ses côtés. Copier le jar seul produit un processus qui démarre puis échoue à trouver ses classes.Un build natif est l’inverse : un seul exécutable, rien à ses côtés, et pas de Java sur l’hôte. C’est ce que contient un tarball de release, et l’installateur accepte les deux.

Le fichier d’environnement

chmod 600. Il contient le mot de passe de la base de données et les deux jetons opérationnels.

export FIREFLO_CONF_DIR=/etc/fireflo
export FIREFLO_DB_URL=jdbc:postgresql://localhost:5432/fireflo
export FIREFLO_DB_USER=fireflo
export FIREFLO_DB_PASSWORD=...
export FIREFLO_CONFIG_SOURCE=file
export QUARKUS_HTTP_PORT=8080
export FIREFLO_OPS_PORT=9000

Définissez FIREFLO_CONF_DIR sur un chemin absolu. Une valeur relative — y compris la valeur par défaut conf — se résout par rapport au répertoire de travail du processus, de sorte qu’une unité avec WorkingDirectory=/opt/fireflo lit /opt/fireflo/conf/, ce qui n’est pas là où vous avez édité quoi que ce soit.

Ports

Port	Transporte	Exposer à
8080	L’API REST	Clients
27777	Liens SMPP	Clients
9000	`/ops/*` et `/q/metrics`	Loopback, ou votre propre réseau uniquement
3000	Le panneau de contrôle	Derrière TLS

systemd

Deux réglages comptent plus que les autres :

# une session SMPP liée est la connexion d'un client, donc arrêter délibérément plutôt que brutalement
KillSignal=SIGTERM
TimeoutStopSec=30

# un descripteur de fichier par session client liée, plus les connexions fournisseurs
LimitNOFILE=65535

SIGTERM plutôt que SIGKILL n’est pas un raffinement. Un arrêt propre restitue le crédit prépayé réservé non dépensé ; un kill -9 le laisse bloqué jusqu’à ce que fireflo credit release s’exécute.

Rétention des journaux, dont vous êtes désormais responsable

Rien dans la passerelle ne supprime httpapi.log. Quarkus le fait tourner quotidiennement et garde chaque fichier indéfiniment. fireflo-install écrit une règle tmpfiles.d précisément pour cela ; installer à la main signifie en écrire une soi-même, ou accepter une croissance illimitée. Voir Journalisation.

Vérifier

scripts/fireflo verify

Et vérifiez que les deux jetons sont bien séparés — une lecture avec le jeton admin doit renvoyer un 404 :

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $FIREFLO_OPS_ADMIN_TOKEN" \
  http://localhost:9000/ops/health      # attendu 404

Start here

The control panel

Install and run

Connections

Routing

Customers and approvals

Billing

Operations

Troubleshooting

Migrating

Project

Installation manuelle

Prérequis

La partie délicate de cette plateforme

Disposition

Le fichier d’environnement

Ports

systemd

Rétention des journaux, dont vous êtes désormais responsable

Vérifier

​Prérequis

​La partie délicate de cette plateforme

​Disposition

​Le fichier d’environnement

​Ports

​systemd

​Rétention des journaux, dont vous êtes désormais responsable

​Vérifier

Prérequis

La partie délicate de cette plateforme

Disposition

Le fichier d’environnement

Ports

systemd

Rétention des journaux, dont vous êtes désormais responsable

Vérifier