Aegis documentation

#Working on the panel

The panel is one FastAPI application with Jinja2 templates and a small ES-module front end. This page is the map: where a page, a component and a task action go, and what the surrounding conventions expect.

#Layout

text
app/modules/web_admin/├── app.py            create_app: middleware, routers, exception pages├── cli.py            aegis web-admin setup|start|stop|restart|status|passwd├── db.py             the panel SQLite database and its migrations├── paths.py          templates, assets, brand, logs├── templating.py     Jinja environment, navigation, render()├── auth/             accounts, sessions, guard.require_user├── routes/           one module per section, HTML and JSON├── services/         what the routes read: views, settings, collectors└── templates/        layouts, sections, partialspublic/assets/web-admin/├── js/app.js         registers every component and starts the app├── js/core/          component base, http, live feed, store, router├── js/components/    one file per behaviour├── css/app.css       prebuilt stylesheet (shipped)└── src/app.css       the same rules, for the build on a dev machine

#A page

  • routes/<section>.py:
  • python
       router = APIRouter()   @router.get("/ftp/users")   def users_page(request: Request, user=Depends(guard.require_user)):       """Every virtual user with its FTP root."""       config = request.app.state.config       return templating.render(           request, "ftp/users.html", title="FTP Manager · Users",           user=user, active="ftp", section="users", page=_page(config),       )
  • app.py imports it (from .routes import ftp as ftp_routes) and includes it
  • (app.include_router(ftp_routes.router)); a JSON router is included as ftp_routes.api. routes/__init__.py lists the package members, but the include list is explicit, so a new module is one import and one line there.

  • templates/<section>/<page>.html extends layout.html (or
  • management/layout.html) and fills {% block content %} / {% block section %}.

    templating.render builds the shared context — request, user, title, active, asset, theme, sidebar — and passes the rest through. The environment uses StrictUndefined: a template that reads a key nobody passed is an error, not a blank spot, so every new page has to pass what it shows.

    active matches a key in NAV (templating.py) and decides which sidebar item is highlighted; section is the key of the tab inside a section.

    Partials worth knowing (templates/partials/section.html): section_header, section_tabs, flash. Every page shows message and error from the query string through flash.

    #A write

    A route never changes the host. It validates what it can, queues a task, and redirects:

    python
    from .queue import queue_taskfrom .web_common import back, back_to@router.post("/mail/aliases")async def alias_add(request: Request, user=Depends(guard.require_user)):    form = dict(await request.form())    source = str(form.get("source") or "").strip()    task_id = await queue_task(        name=f"add alias {source or '(unnamed)'}",        action="mail.alias.add",        args={"source": source, "destination": str(form.get("destination") or "")},        actor=user.username,        resource=f"mail:alias:{source}",        group="mail",    )    return back(back_to(form, "/mail/domains"), f"task {task_id} queued")
  • queue_task creates the row in the tasker database and returns its id.
  • group is the section (web, mail, dns, ftp, database, sys).
  • resource says what is touched; two tasks on the same resource still run one
  • at a time because a worker owns one root, but it also makes the queue readable.

  • back(url, message, error=False) answers 303 with ?ok= or ?error=;
  • back_to(form, default) keeps the operator on the page that opened the form, accepting only paths inside the same section.

    The action itself lives in app/modules/tasker/actions/<area>.py and is registered with @registry.action("mail.alias.add"). It receives (context, args) and returns success, failure or partial from app/helpers/result.py. New action module → import it in app/modules/tasker/actions/__init__.py → restart the tasker.

    A read-only button (Check, Preview) stays inline: it changes nothing, so it answers in the request with run_in_threadpool around the blocking call.

    #A component

    javascript
    import { Component } from "../core/component.js";export class Thing extends Component {  mount() {    this.delegate("click", "[data-thing-action]", (event, button) =>      this.run(button),    );  }  async run(button) {    button.disabled = true;    try {      const result = await this.http.post("/api/thing/apply", {});      this.app.toast(result.detail || "done");    } catch (error) {      this.app.toast(error.body?.error || error.message, "error");    }  }}

    Register it once in js/app.js with the selector it mounts on:

    javascript
    .component("thing", Thing, "[data-thing]")

    What the base class gives you: this.el, this.app, this.http (get, post, put, del), this.listen(...) and this.delegate(...) — both removed on unmount — this.bus, this.store, and this.app.liveFeed() for WebSocket topics.

    Rules that keep the panel predictable:

  • no inline <script> and no onclick; behaviour is a component, wired through
  • data attributes;

  • never build HTML from server text: textContent (or escape in
  • tasker.js) — logs, URIs and user agents are attacker-controlled;

  • destructive buttons carry data-confirm, data-confirm-title,
  • data-confirm-action and optionally data-confirm-tone (the confirm component owns the dialog);

  • a component that subscribes to a topic must unsubscribe in unmount().
  • #Styles

    css/app.css is compiled elsewhere and shipped: a utility class that is not already in that file does nothing. When a rule is missing, add plain CSS to both css/app.css and src/app.css — they are kept in step by hand — and prefer the existing variables (--ag-ink, --ag-muted, --ag-line, --ag-surface, --ag-panel, --ag-accent).

    #The panel database

    aegis.db holds accounts, sessions and preferences. Schema changes are .sql files under database/migrations/core/aegis, applied once and recorded in schema_migrations. db.ensure() runs at start-up; a service that needs a table calls it before its first query, exactly like the tasker does.

    #Checklist

  • file ≤ 270 lines; split by responsibility before crossing it;
  • module, class and public function docstrings; type hints on public signatures;
  • English in code, comments and docs; 88 columns everywhere in Python;
  • no print — output goes through app/helpers/cli;
  • every host change is a task, and every task action is registered;
  • aegis web-admin restart after a change; `Management → Tasker → Restart
  • tasker` when an action was added or renamed.