FireFlo SMS/SMPP Gateway

O que o fireflo-install automatiza. Leia isto se você mesmo estiver empacotando o FireFlo, ou se uma etapa do instalador falhou e você precisa saber o que ela fazia.

Os pré-requisitos abaixo estão automatizados em um script. O setup.sh instala PostgreSQL, RabbitMQ e Node no Ubuntu e no Debian, e Java atrás de --with-java. Esta página é a versão por extenso — leia-a para saber o que aquele script faz, ou para fazer isso em uma distribuição que ele recusa.

Pré-requisitos

Java 25. O build tem como alvo o release 25 e não roda no 21.
PostgreSQL 14 ou mais recente. Opcional para o gateway sozinho em modo de arquivo; necessário para o painel de controle, crédito pré-pago, whitelist e registros de chamadas em uma tabela.
RabbitMQ, apenas se as mensagens submetidas precisarem sobreviver a um reinício do gateway. Sem ele, a fila fica em memória e um reinício descarta o que ainda não chegou a um fornecedor.
Um usuário de serviço sem shell de login.

A parte estranha desta plataforma

Dois dos três runtimes não são o que o Ubuntu fornece:

Necessário	Ubuntu 24.04 fornece	Faça
Java 25	`openjdk-21`	Adicione o Adoptium
Node 22	`nodejs` 18	Adicione o NodeSource
PostgreSQL 14+	PostgreSQL 16	`apt install postgresql`

Pacotes básicos

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

Java 25 do 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        # deve imprimir 25

Node 22 do NodeSource

O Next.js 16 não roda no Node 18 do Ubuntu — isto é para o painel de controle.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version       # deve imprimir v22 ou mais recente

Usuário de serviço e diretórios

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

Banco de dados

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

Mantenha a senha fora do histórico do shell — escreva-a diretamente no arquivo de ambiente.

Layout

A configuração fica fora do diretório do artefato, para que uma atualização possa substituir o artefato inteiro sem tocar em nada que você editou.

/opt/fireflo/            de propriedade do fireflo, SUBSTITUÍDO na atualização
  quarkus-run.jar
  lib/  app/  quarkus/
  bin/fireflo            a CLI do operador, mantida fora do que a atualização substitui

/etc/fireflo/            de propriedade do fireflo, NUNCA substituído na atualização
  fireflo.env            ambiente, incluindo a senha do banco. chmod 600
  smsg.properties        workers e configurações   \
  credentials.yml        logins                     |  apenas modo de arquivo
  routingTable.conf      roteamento                 |
  rates.conf             tarifas                   /

/var/lib/fireflo/        o armazenamento de recibos, e CDRs quando não há banco
/var/log/fireflo/        logs

Se você construiu o empacotamento JVM, o artefato é um diretório, não um arquivo. O quarkus-run.jar não roda sem os diretórios lib/, app/ e quarkus/ ao seu lado. Copiar apenas o jar produz um processo que inicia e depois falha ao não encontrar suas classes.Um build nativo é o oposto: um executável, nada ao seu lado, e nenhum Java no host. É isso que um tarball de release contém, e o instalador aceita qualquer um dos dois.

O arquivo de ambiente

chmod 600. Ele contém a senha do banco de dados e ambos os tokens operacionais.

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

Defina FIREFLO_CONF_DIR como um caminho absoluto. Um valor relativo — incluindo o padrão conf — é resolvido em relação ao diretório de trabalho do processo, portanto uma unidade com WorkingDirectory=/opt/fireflo lê /opt/fireflo/conf/, que não é onde você editou nada.

Portas

Porta	Transporta	Expor para
8080	A API REST	Clientes
27777	Binds SMPP	Clientes
9000	`/ops/*` e `/q/metrics`	Loopback, ou apenas sua própria rede
3000	O painel de controle	Atrás de TLS

systemd

Duas configurações importam mais do que o resto:

# uma sessão SMPP vinculada é a conexão de um cliente, então pare deliberadamente em vez de abruptamente
KillSignal=SIGTERM
TimeoutStopSec=30

# um descritor de arquivo por sessão de cliente vinculada, mais as conexões dos fornecedores
LimitNOFILE=65535

SIGTERM em vez de SIGKILL não é uma cortesia. Um desligamento limpo devolve crédito pré-pago reservado não gasto; um kill -9 o deixa preso até que fireflo credit release seja executado.

Retenção de logs, que agora é sua responsabilidade

Nada no gateway remove httpapi.log. O Quarkus faz sua rotação diariamente e mantém todos os arquivos para sempre. O fireflo-install escreve uma regra tmpfiles.d exatamente para isto; instalar manualmente significa escrever uma você mesmo, ou aceitar crescimento ilimitado. Veja Logging.

Verificar

scripts/fireflo verify

E confira que os dois tokens realmente são separados — a leitura com o token admin deve retornar 404:

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

Start here

The control panel

Install and run

Connections

Routing

Customers and approvals

Billing

Operations

Troubleshooting

Migrating

Project

Instalar manualmente

Pré-requisitos

A parte estranha desta plataforma

Layout

O arquivo de ambiente

Portas

systemd

Retenção de logs, que agora é sua responsabilidade

Verificar

​Pré-requisitos

​A parte estranha desta plataforma

​Layout

​O arquivo de ambiente

​Portas

​systemd

​Retenção de logs, que agora é sua responsabilidade

​Verificar

Pré-requisitos

A parte estranha desta plataforma

Layout

O arquivo de ambiente

Portas

systemd

Retenção de logs, que agora é sua responsabilidade

Verificar