Aegis documentation

#Architecture

#Layers

text
aegis/            public facade (aegis install, aegis cubes, …)app/├── core/         aegis.system, aegis.storage, hardware, network, sys├── helpers/      cli, config, files, process, template, toml, geoip, result├── modules/│   ├── thor/     catalog, downloads, runtime, build engine, installer│   ├── keeper/   process supervision, heartbeats, scheduled jobs│   ├── tasker/   the task queue: one row per action, and its daemon│   ├── pulse/    area samplers for the live feed│   ├── bird/     WebSocket transport (publish side)│   ├── collector/ counters and their storage│   ├── monitor/  realtime connections, requests and deliveries│   ├── web_admin/ the panel: routes, templates, JSON endpoints│   ├── web/      vhost model, rendering, apply│   ├── dns/      zones, records, repairs, state│   ├── ssl/      certificate resolution and generation│   ├── uapi/     one API for OS operations (packages, users, services…)│   ├── db/       SQLite lifecycle, migrations, seeders│   ├── geoip/    MaxMind database download and status│   ├── net/      interfaces, addresses, peers, ports│   ├── health/   the checks behind `aegis check`│   └── docs/     Markdown → HTML documentation site└── cubes/        one management module per application (bind, nginx, …)

aegis is only a facade: implementations live under app/, and call sites — including the CLI — import through aegis where a public entry point exists.

#The root is never hardcoded

app/core/system.py resolves the project root from its own file location:

text
app/core/system.py  →  parents[2]  →  /etc/aegis   (or wherever it was copied)

Everything else is relative to that root:

python
aegis.system.path("config", "aegis.toml")     # <root>/config/aegis.tomlaegis.system.vendor_path("apps")              # <root>/vendor/appsaegis.storage.data.app("nginx").templates_dir # <root>/storage/data/apps/nginx/templates

Destination paths for installed software come from configuration, with fallbacks derived from the root as well:

toml
aegis  root = "/aegis"                           install root for apps/data/logsapps   install_path = "/aegis/apps"nginx  config_dir = "/aegis/config/nginx"

Remove those keys and the defaults become <root>/apps, <root>/config/nginx and so on — the tree stays self-contained wherever it lives.

#Storage, split by purpose

aegis.storage is a package with one submodule per data area:

text
storage/├── data/       shipped with the panel: build profiles, templates, patches│   └── apps/<name>/{build.toml,templates/,patches/}├── temp/       scratch: extracted sources, downloads (safe to delete)├── apps/       installer state (state.json)└── media/      user media (future)
python
from app.core import aegisaegis.storage.data.app("bind").templates_diraegis.storage.data.app("bind").build_profileaegis.storage.temp("build", "nginx-1.30.6", create=True)aegis.storage.data.apps()          # ["bind", "nginx", …]

Adding cache/ later means adding storage.cache, never a path spelled by hand at a call site.

#Installer steps

A step is a named container of tasks with a failure policy:

python
class ServerInfo(Step):    def name(self) -> str: return "verification/server"    def tasks(self) -> Sequence[Task]: ...    def on_fail(self) -> Failure: return Failure.BREAK

A task is one unit that returns a TaskResult. Failure is either BREAK (stop the run) or CONTINUE. Tasks can post a live status line through context.report(...), which the console renderer shows in the spinner instead of printing a new line (a printed line would break the in-place header rewrite).

#Build engine

text
plan.resolve(app)        depth-first over [dependencies] libs, dependencies firstplan.prefix(config, app) the one place that knows <apps>/<group>/<name>/<series>Builder                  resolve libs, extract, configure, compile, installVerifier                 [verify] rules: binaries, libraries, commandsmodules                  third-party sources added with --add-modulepatches                  profile patches applied once after extraction

Builder._env() gives every build the same view of the world:

text
CPPFLAGS / LDFLAGS           every declared libraryPKG_CONFIG_PATH              their pkgconfig directoriesCMAKE_PREFIX_PATH            CMake ignores CPPFLAGSPATH                         runtime bin first, then librariesLD_LIBRARY_PATH              only for verification and tools

#Cubes

A cube owns the runtime side of one application: configuration files, the validation command, the reload path, and (optionally) a service() definition for the keeper. Building belongs to the installer; a cube never compiles.

python
class Nginx(Cube):    def name(self) -> str: return "nginx"    def configure(self) -> str: ...    def validate(self) -> str: ...    def reload(self) -> str: ...    def service(self) -> keeper.Service: ...

Discovery is from disk: every app/cubes/<name>/cube.py with a Cube subclass is mounted under aegis cubes <name>, and appears in keeper services when it exposes service().

#Where a write happens

A request never changes the host. The panel validates the form, stores a task in database/storage/tasker/tasker.db, and returns; the tasker daemon executes it in a worker and records the outcome. The same row is what the task window, the task page and the CLI read, so there is one history instead of one log per section.

That matters for operations that are slow or dangerous: a vhost render runs nginx -t and reloads, a mail domain also writes a DKIM key and a DNS record, a DNS change rewrites a zone file. Each of them needs a place where the failure stays readable afterwards, and a rollback step when the second half fails.

See tasker.md and panel.md.

#Keeper

text
keeper service.py    Service(name, command, pid_file, log_file, environment)keeper manager.py    start / stop / restart / statuskeeper registry.py   collects service() from the installed cubeskeeper daemon.py     loop that restarts whatever is down (10 s)keeper boot.py       /etc/init.d/aegis-keeper

No systemd: the platform supervises its own processes. A pid file and a log file per service live under <root>/run and <root>/logs.

#uapi

app/modules/uapi is the only place that talks to the distribution. Domains: commands, packages, services, users, groups, host, network. Platforms: ubuntu, debian (both delegating to debian_family), with run_<version> overrides resolved automatically.