Aegis documentation

#The panel

The panel is a FastAPI application that reads the same configuration and databases as the command line, renders them with Jinja2, and turns every write into a task. It is the operator's view of the host, not a second source of truth: nothing exists in the panel that aegis cannot show.

bash
aegis web-admin setup         # dependencies, accounts, first adminaegis web-admin start         # background, default 0.0.0.0:9981aegis web-admin statusaegis web-admin restart       # what a deploy needsaegis web-admin passwd        # change an account password

web_admin.host and web_admin.port in aegis.toml decide where it listens.

#Sections

SectionWhat it answers
Dashboardkeeper, core daemons, applications, scheduled jobs, host, live charts
Monitorrealtime connections, nginx requests, mail deliveries
Networkinterfaces, addresses, peers, ports
Webnginx vhosts, cache, guards, PHP pools
DNS ManagerBIND, zones, records, repairs, history
Maildomains, mailboxes, aliases, forwards, relays, hooks, service settings
FTP Managervsftpd, virtual users, limits
DatabaseMariaDB, PostgreSQL, Redis: settings, databases, accounts, sessions
Storagedisks, usage, the two trees
SSLcertificates, issuance, renewal
Collectorthe sampling daemons and their storage
Managementplatform operations, one tab per subsystem (below)
Settingsconfiguration files and panel preferences
Appsthe catalog

Evocati is not a sidebar row: the top bar carries it as a shield icon, next to the task bell, because it is opened while working elsewhere rather than as a destination of its own.

Management tabs: Overview, Keeper, WebSocket, Supervisor, Queue, SSH, Permissions, Cron, GeoIP, Tasker, Tools.

#Every write is a task

A form post validates what it can and stores a task; the tasker daemon does the work. That is true for vhosts and locations, mail domains, mailboxes, aliases, forwards, relays, hooks, the mail service settings, DNS zones, records and repairs, FTP users and settings, database objects and engine commands, and the permissions page.

The page redirects with task 42 queued, and the floating window reports the outcome. Nothing is written inside the request that asked for it, so a slow nginx -t or a database restart never blocks a browser tab. See tasker.md.

Pages that only read — dashboards, listings, one task's detail — stay synchronous. Check, Preview and similar read-only buttons also answer in the request; they queue nothing because they change nothing.

#Live updates

Pages that show moving numbers do not poll the database: the panel subscribes to the platform's WebSocket transport and re-renders what arrives. The browser asks /api/live for the connection details after it is authenticated, so the private token is never baked into a page. See live.md.

Pages that do not need a socket still refresh: the task window polls one small endpoint every 1.2 s.

#Authentication

  • Accounts live in the panel's own SQLite database.
  • A successful login sets an aegis_session cookie; sessions have an expiry and
  • are pruned, and every request resolves the account behind the cookie.

  • Unsafe requests from another origin are rejected before they reach a route.
  • /assets/ is served no-cache on purpose: the panel is a set of ES modules
  • with no version query, and a deploy must be visible after a plain reload.

    #Assets and templates

    PathContent
    app/modules/web_admin/templatesJinja2 layouts and pages
    public/assets/web-admin/jscomponents, one file each, registered in app.js
    public/assets/web-admin/cssprebuilt CSS; a new utility class has no effect until it is added there
    config/aegis.toml plus one file per area, overlay server.toml

    CSS is compiled on a development machine and shipped; the panel does not build Tailwind at run time. A new utility class that is not already in app.css does nothing — use the existing classes or add plain CSS in both css/app.css and src/app.css.

    #Sections that deserve their own page

  • tasker.md — the queue behind every button, its window and the bell.
  • permissions.md — why a document root needs ACLs, and the page
  • that applies them.

  • live.md — Bird and pulse, the two halves of the realtime feed.
  • #After a deploy

    bash
    aegis web-admin restart      # loads new routes, services and templates

    A tasker action change additionally needs Management → Tasker → Restart tasker (or aegis keeper restart), because the daemon imports the action modules once, at start.