Jabali Panel architecture: Go API, React UI, reconciler, agent

Last updated

The full inventory of moving parts.

Process model

ProcessLanguageRuns asListens onPurpose
jabali-panel.serviceGo (Gin)jabaliunix /run/jabali-panel/api.sock, /run/jabali-panel/sso.sockThe panel API plus the embedded SPA. nginx serves it on :8443.
jabali-agent.serviceGorootunix /run/jabali/agent.sock (group jabali, 0660), /run/jabali/agent-pty.sockThe only thing that performs privileged host ops.
jabali-webmail.serviceNode (Next.js standalone)jabali-webmailunix /run/jabali-bulwark/bulwark.sockBulwark webmail, plus the SSO and autoconfig bridge.
jabali-kratos.serviceGo (Ory)jabaliunix /run/jabali-kratos/public.sock, /run/jabali-kratos/admin.sockIdentity (login, 2FA, recovery). Sockets only.
nginx.serviceCroot master, www-data workers:80, :443, :8443 (panel) (+ admin pool IPs)Reverse-proxies the panel and serves every vhost.
jabali-fpm@<user>.serviceCthe panel userunix /run/php/jabali-<user>/fpm.sockOne PHP-FPM master per panel user, on that user’s PHP version. The distro php<ver>-fpm units are masked.
mariadb.serviceCmysqlunix /run/mysqld/mysqld.sock, 127.0.0.1:3306Panel DB and tenant DBs. Loopback TCP only because Stalwart’s SQL directory cannot use a socket.
postgresql.serviceCpostgresunix /run/postgresql, 127.0.0.1:5432Tenant DBs only; optional.
pdns.serviceC++pdnspublic IPs :53, 127.0.0.1:5300Authoritative DNS for hosted zones, MariaDB backend.
pdns-recursor.serviceC++pdns127.0.0.1:53Local recursive resolver.
jabali-stalwart.serviceRustjabali-mail:25, :465, :587, :993, :995, :4190; JMAP 127.0.0.1:8446, internal 127.0.0.1:18181SMTP, submission, IMAP, POP3, ManageSieve, JMAP and the mailbox store.
jabali-mailhook.serviceGojabali127.0.0.1:8462Mail disclaimer hook Stalwart calls.
jabali-webdav-auth.serviceGorootunix /run/jabali-webdav/auth.socknginx auth_request check for WebDAV.
redis-server.serviceCredisunix /run/redis/redis.sockNotifications dispatcher stream, panel cache.
crowdsec.service + bouncersGoroot127.0.0.1:8081 (LAPI), 127.0.0.1:7422 (AppSec), unix /run/crowdsec/api.sockIP-trust source + AppSec WAF.
jabali-aide-check.timershellroot—Daily host-integrity scan (04:30 UTC).

The AIDE check is one of about 20 scheduled jobs Jabali installs as systemd timers. Admin → Cron Jobs → System jobs lists all of them with their status, last and next run, and log (see Cron Jobs).

Data model

  • Panel DB (MariaDB): single DB, ~150 tables. Every domain, user, mailbox, DNS record, audit row, backup job, etc. is here.
  • Stalwart store: mailbox blobs + metadata; opaque to the panel.
  • Kratos store: identity DB; opaque to the panel except for the user FK.
  • PowerDNS DB: zones + records. The agent syncs from the panel DB (DB-as-truth).

Reconciler

The single in-process loop inside jabali-panel. Wakes on:

  • A 60 s timer.
  • Any panel-side write that schedules itself (Reconciler.Schedule(<domain-id>)).

What it does (per tick):

  1. Diffs DB intent vs. host state for: domains (vhosts, SSL, DNSSEC, listen IPs), per-user resource limits, mail accounts, DNS zone files, cron timers, backup destinations + schedules, PHP pool files, SSH key files, CrowdSec allowlists, IP pool, panel-cert state.
  2. For each diff, calls the agent over UDS to converge.
  3. Records the result in the audit log if it was a real change.

Idempotency rule: every converger compares before/after and skips side-effects on no-change. Tracked by the “per-tick idempotent loops” audit checklist.

Agent contract

jabali-agent accepts a small set of typed JSON RPCs over UDS. Each handler is a single Go file under panel-agent/internal/commands/. Examples:

domain.create       { domain_id, username, domain, doc_root, has_php, php_version, fpm_socket, cache_enabled, … }
ssl.issue           { domain, webroot, email, hostnames, staging }
ssl.panel.issue     { hostname, extra_hostnames, email, staging }
mailbox.create      { id, email, display_name, … }
db.config.apply     { settings, restart_required }
nginx.reload        {}
nginx.cache.purge   { domain, paths }
dns.dnssec_enable   { domain_name }

Wire-contract drift is caught by golden tests (mirror security_crowdsec_geoblock_golden_test.go): JSON tags on domainCreateParams must match the panel side. The “verify wire contract against handler” rule is mandatory whenever a new field is added.

Why this shape

  • DB-as-truth prevents host-edit drift; restart-safe.
  • Reconciler-converged means anything you change in the DB shows up on host within ≤60 s; restart of the agent doesn’t lose state.
  • Single agent over UDS keeps privilege boundary one process; no setuid binaries, no sudoers.d expansion.
  • Sockets or loopback only for internal services. Kratos, the panel and the agent listen on unix sockets; MariaDB, Stalwart’s JMAP and internal listeners, and the mail hook bind to loopback. Only nginx, Stalwart’s mail ports and PowerDNS face the network.

ADRs covering the major decisions live under docs/adr/.