servico

Home > Colocar no ar > Serviço e daemon 🚧

Rodar como serviço do Windows ou daemon do Linux

Important

Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.

Vale para a 2.0 · Delphi XE em diante e Lazarus/FPC 3.2 em diante · Nível: intermediário

Em uma frase: o TRALServiceHost faz o mesmo executável se instalar e rodar como serviço do Windows ou como daemon do systemd, e parar com calma: os pedidos em curso terminam, os novos recebem 503.

Você vai precisar: o pacote RALHostingPackage e um motor de servidor. Não usa SvcMgr nem VCL/LCL: funciona num programa de console e também dentro de um app com janela.

O programa

uses RALServer, RALIndyServer, RALServiceHost, RALSystemLog, RALConfig;

Servidor := TRALIndyServer.Create(nil);
Servidor.CreateRoute('ping', Ping);

Log := TRALSystemLog.Create(nil);       // Event Log ou syslog/journal
Log.Ident := 'minhaapi';

Host := TRALServiceHost.Create(nil);
Host.ServiceName := 'MinhaAPI';
Host.DisplayName := 'Minha API';
Host.Description := 'API REST da empresa';
Host.Server := Servidor;
Host.ShutdownTimeout := 30000;          // quanto esperar os pedidos em curso
Host.OnLog := Log.WriteText;
Host.StartArgs := 'run';
Host.Run;

Run lê o primeiro parâmetro:

parâmetro	faz
install	Windows: cria o serviço (como administrador). Linux: grava MinhaAPI.service em UnitDir (padrão /etc/systemd/system)
uninstall	remove o serviço ou a unidade
start, stop	pede ao sistema (SCM ou systemctl)
console (ou run)	roda aqui até Ctrl+C, SIGTERM ou SIGINT
nenhum	Windows: roda como o serviço que o SCM iniciou (Run devolve False se ninguém iniciou: um app com janela abre a janela). Linux: roda como o daemon

No Linux (systemd)

sudo ./minhaapi install
sudo systemctl daemon-reload
sudo systemctl enable --now MinhaAPI
systemctl reload MinhaAPI     # SIGHUP: OnReload (recarregar a configuração)
systemctl stop MinhaAPI       # SIGTERM: Shutdown, os pedidos em curso terminam
journalctl -u MinhaAPI        # as linhas do TRALSystemLog

A unidade é Type=notify: o RAL avisa READY=1 quando o servidor está no ar, STOPPING=1 ao parar e, se a unidade pedir WatchdogSec=, manda o WATCHDOG=1 sozinho. Para uma unidade de usuário (~/.config/systemd/user), aponte UnitDir para lá.

Parar com calma

Qualquer servidor tem Shutdown:

Servidor.Shutdown(10000);   // espera até 10 s pelos pedidos em curso

Durante a espera IsShuttingDown é verdadeiro, ActiveRequests diz quantos faltam, e quem chega recebe 503 com Retry-After (ShutdownRetryAfter) e Connection: close - o /health/ready do plugin de saúde também, e o balanceador tira o servidor da roda. OnShutdown avisa no começo (ssDraining) e no fim (ssStopped). Parar o serviço, systemctl stop e Ctrl+C passam por aqui.

Porta 0

Port := 0 pede ao sistema uma porta livre ao ligar; BoundPort diz qual. Útil em testes e quando um orquestrador escolhe a porta.

Log do sistema

TRALSystemLog escreve no Event Log (Windows) ou no syslog, que o systemd guarda no journal. Com LogPlugin apontando para um TRALLogPlugin, as linhas dos pedidos vão para lá também (5xx como erro, 4xx como aviso).

Erros comuns

sintoma	causa
install não faz nada no Windows	o prompt não é de administrador
[RAL 6402] ao rodar	Server do TRALServiceHost não foi ligado
Active := True do fpHTTP levanta	a porta já está em uso (o servidor fica parado)
o serviço inicia e para em seguida	exceção ao ligar (porta ocupada?): veja o Event Log
systemctl start fica em "activating"	o programa não chama Host.Run (sem READY=1)
no Event Viewer aparece "a descrição não foi encontrada"	a origem (Ident) não está registrada: a linha vem depois desse aviso, e o resto funciona

Veja também

• Configuração externa
• Agendador
• Colocar no ar
• Exemplo: ServiceExample no repositório de exemplos (Delphi e Lazarus)