FireFlo SMS/SMPP Gateway

Lo que fireflo-install automatiza. Lee esto si estás empaquetando FireFlo por tu cuenta, o si un paso del instalador falló y necesitas saber qué estaba haciendo.

Los requisitos previos de abajo están automatizados en un script. setup.sh instala PostgreSQL, RabbitMQ y Node en Ubuntu y Debian, y Java detrás de --with-java. Esta página es el camino largo — léela para saber qué hace ese script, o para hacerlo en una distribución que él rechaza.

Requisitos previos

Java 25. La compilación apunta al release 25 y no funciona en 21.
PostgreSQL 14 o superior. Opcional solo para el gateway en modo archivo; obligatorio para el panel de control, el crédito prepago, el whitelisting y los registros de llamadas en tabla.
RabbitMQ, únicamente si los mensajes enviados deben sobrevivir a un reinicio del gateway. Sin él la cola está en memoria y un reinicio descarta todo lo que no había llegado a un proveedor.
Un usuario de servicio sin shell de inicio de sesión.

La parte incómoda de esta plataforma

Dos de los tres runtimes no son los que Ubuntu incluye:

Necesitas	Ubuntu 24.04 trae	Haz
Java 25	`openjdk-21`	Añade Adoptium
Node 22	`nodejs` 18	Añade NodeSource
PostgreSQL 14+	PostgreSQL 16	`apt install postgresql`

Paquetes base

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

Java 25 desde 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        # debe imprimir 25

Node 22 desde NodeSource

Next.js 16 no funciona con el Node 18 de Ubuntu — esto es para el panel de control.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version       # debe imprimir v22 o posterior

Usuario de servicio y directorios

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 datos

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

Mantén la contraseña fuera del historial del shell — escríbela directamente en el archivo de entorno.

Distribución de directorios

La configuración se mantiene fuera del directorio del artefacto, para que una actualización pueda reemplazar el artefacto por completo sin tocar nada de lo que hayas editado.

/opt/fireflo/            propiedad de fireflo, REEMPLAZADO en la actualización
  quarkus-run.jar
  lib/  app/  quarkus/
  bin/fireflo            el CLI del operador, fuera de lo que reemplaza una actualización

/etc/fireflo/            propiedad de fireflo, NUNCA se reemplaza en la actualización
  fireflo.env            entorno, incluida la contraseña de la base de datos. chmod 600
  smsg.properties        workers y ajustes         \
  credentials.yml        logins                     |  solo modo archivo
  routingTable.conf      enrutamiento               |
  rates.conf             tarifas                   /

/var/lib/fireflo/        el almacén de recibos, y los CDR cuando no hay base de datos
/var/log/fireflo/        logs

Si compilaste el empaquetado JVM, el artefacto es un directorio, no un archivo. quarkus-run.jar no se ejecuta sin los directorios lib/, app/ y quarkus/ junto a él. Copiar solo el jar produce un proceso que arranca y luego falla al no encontrar sus clases.Una compilación nativa es lo contrario: un ejecutable, nada junto a él, y sin Java en el host. Eso es lo que contiene un tarball de release, y el instalador acepta cualquiera de los dos.

El archivo de entorno

chmod 600. Contiene la contraseña de la base de datos y ambos tokens operacionales.

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

Establece FIREFLO_CONF_DIR como una ruta absoluta. Un valor relativo — incluido el conf por defecto — se resuelve contra el directorio de trabajo del proceso, así que una unidad con WorkingDirectory=/opt/fireflo lee /opt/fireflo/conf/, que no es donde editaste nada.

Puertos

Puerto	Transporta	Exponer a
8080	La API REST	Clientes
27777	Enlaces SMPP	Clientes
9000	`/ops/*` y `/q/metrics`	Loopback, o solo tu propia red
3000	El panel de control	Detrás de TLS

systemd

Dos ajustes importan más que el resto:

# una sesión SMPP enlazada es la conexión de un cliente, así que detén deliberadamente en lugar de bruscamente
KillSignal=SIGTERM
TimeoutStopSec=30

# un descriptor de archivo por sesión de cliente enlazada, más las conexiones a proveedores
LimitNOFILE=65535

SIGTERM en lugar de SIGKILL no es una amabilidad. Un apagado limpio devuelve el crédito prepago reservado no gastado; un kill -9 lo deja atrapado hasta que se ejecute fireflo credit release.

Retención de logs, de la que ahora te haces cargo

Nada dentro del gateway elimina httpapi.log. Quarkus lo rota diariamente y conserva cada archivo para siempre. fireflo-install escribe una regla de tmpfiles.d exactamente para esto; instalar a mano implica escribir una tú, o aceptar un crecimiento sin límites. Consulta Logging.

Verificar

scripts/fireflo verify

Y comprueba que los dos tokens realmente son independientes — leer con el token de admin debe devolver 404:

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

Start here

The control panel

Install and run

Connections

Routing

Customers and approvals

Billing

Operations

Troubleshooting

Migrating

Project

Instalar a mano

Requisitos previos

La parte incómoda de esta plataforma

Distribución de directorios

El archivo de entorno

Puertos

systemd

Retención de logs, de la que ahora te haces cargo

Verificar

​Requisitos previos

​La parte incómoda de esta plataforma

​Distribución de directorios

​El archivo de entorno

​Puertos

​systemd

​Retención de logs, de la que ahora te haces cargo

​Verificar

Requisitos previos

La parte incómoda de esta plataforma

Distribución de directorios

El archivo de entorno

Puertos

systemd

Retención de logs, de la que ahora te haces cargo

Verificar