FireFlo SMS/SMPP Gateway

What fireflo-install automates. Read this if you are packaging FireFlo yourself, or if an installer step failed and you need to know what it was doing.

The prerequisites below are scripted. setup.sh installs PostgreSQL, RabbitMQ and Node on Ubuntu and Debian, and Java behind --with-java. This page is the long hand — read it to know what that script does, or to do it on a distribution it refuses.

Prerequisites

Java 25. The build targets release 25 and will not run on 21.
PostgreSQL 14 or newer. Optional for the gateway alone in file mode; required for the control panel, prepaid credit, whitelisting, and call records in a table.
RabbitMQ, only if submitted messages must survive a gateway restart. Without it the queue is in memory and a restart drops whatever had not reached a vendor.
A service user with no login shell.

The awkward part of this platform

Two of the three runtimes are not what Ubuntu ships:

Need	Ubuntu 24.04 ships	Do
Java 25	`openjdk-21`	Add Adoptium
Node 22	`nodejs` 18	Add NodeSource
PostgreSQL 14+	PostgreSQL 16	`apt install postgresql`

Base packages

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

Java 25 from 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        # must print 25

Node 22 from NodeSource

Next.js 16 does not run on Ubuntu’s Node 18 — this is for the control panel.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version       # must print v22 or newer

Service user and directories

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

Database

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

Keep the password out of shell history — write it straight into the environment file.

Layout

Configuration is kept out of the artefact directory, so an upgrade can replace the artefact wholesale without touching anything you edited.

/opt/fireflo/            owned by fireflo, REPLACED on upgrade
  quarkus-run.jar
  lib/  app/  quarkus/
  bin/fireflo            the operator CLI, kept out of what an upgrade replaces

/etc/fireflo/            owned by fireflo, NEVER replaced on upgrade
  fireflo.env            environment, including the database password. chmod 600
  smsg.properties        workers and settings      \
  credentials.yml        logins                     |  file mode only
  routingTable.conf      routing                    |
  rates.conf             tariffs                   /

/var/lib/fireflo/        the receipt store, and CDRs when there is no database
/var/log/fireflo/        logs

If you built the JVM packaging, the artefact is a directory, not a file. quarkus-run.jar will not run without the lib/, app/ and quarkus/ directories beside it. Copying the jar alone produces a process that starts and then fails to find its classes.A native build is the opposite: one executable, nothing beside it, and no Java on the host. That is what a release tarball contains, and the installer takes either.

The environment file

chmod 600. It holds the database password and both operational tokens.

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

Set FIREFLO_CONF_DIR to an absolute path. A relative value — including the conf default — resolves against the process working directory, so a unit with WorkingDirectory=/opt/fireflo reads /opt/fireflo/conf/, which is not where you edited anything.

Ports

Port	Carries	Expose to
8080	The REST API	Customers
27777	SMPP binds	Customers
9000	`/ops/*` and `/q/metrics`	Loopback, or your own network only
3000	The control panel	Behind TLS

systemd

Two settings matter more than the rest:

# a bound SMPP session is a customer's connection, so stop deliberately rather than abruptly
KillSignal=SIGTERM
TimeoutStopSec=30

# one file descriptor per bound customer session, plus the vendor connections
LimitNOFILE=65535

SIGTERM rather than SIGKILL is not a nicety. A clean shutdown returns unspent reserved prepaid credit; a kill -9 strands it until fireflo credit release runs.

Log retention, which you now own

Nothing in the gateway removes httpapi.log. Quarkus rotates it daily and keeps every file forever. fireflo-install installs a daily systemd timer for exactly this; installing by hand means arranging one yourself, or accepting unbounded growth. See Logging.

Verify

scripts/fireflo verify

And check the two tokens really are separate — reading with the admin token must 404:

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

Start here

The control panel

Install and run

Connections

Routing

Customers and approvals

Billing

Operations

Troubleshooting

Migrating

Project

Install by hand

Prerequisites

The awkward part of this platform

Layout

The environment file

Ports

systemd

Log retention, which you now own

Verify

​Prerequisites

​The awkward part of this platform

​Layout

​The environment file

​Ports

​systemd

​Log retention, which you now own

​Verify

Prerequisites

The awkward part of this platform

Layout

The environment file

Ports

systemd

Log retention, which you now own

Verify