Aegis documentation

#web-admin

aegis web-admin runs the Aegis panel: a FastAPI application served by uvicorn. It is not supervised by the keeper; start detaches one process, and status trusts the pid file only while that process is alive. aegis restart still stops the panel first and starts it last, so it never answers requests while the other services are half-restarted.

bash
aegis web-admin setup     # configuration, dependencies, aegis.db, first accountaegis web-admin start     # start in the backgroundaegis web-admin stopaegis web-admin restartaegis web-admin run       # foreground; this is what start launchesaegis web-admin statusaegis web-admin passwd    # change a panel account password

Defaults come from config/web_admin.toml: web_admin.host is 0.0.0.0 and web_admin.port is 9981. Flags win over the file; the file wins over the defaults.

pathcontent
/aegis/run/web-admin.pidpid of the running panel, written by run
/aegis/logs/web-admin.logstdout and stderr of the background process
/aegis/database/storage/aegis/aegis.dbaccounts, sessions and settings
/aegis/config/web_admin.tomlhost, port, session TTL, cookie name, assets

Output is human-formatted; the group does not consult the global --json flag. Exit codes are 0 for a completed command, 1 for a reported failure and 2 for an argparse error.

#Commands

#aegis web-admin setup

Prepares everything the panel needs on a host, then prints one line per step. It is idempotent: dependencies already importable are not installed again, the database is migrated only when needed, and the first account is created only while the users table is empty.

bash
aegis web-admin setup --name=<display> --username=<login>                      --email=<address> --password=<secret>                      --non-interactive
argumentdefaultmeaning
--namethe usernamedisplay name of the first account
--usernameemptylogin name; prompted for when omitted
--emailemptyaddress of the first account
--passwordemptyprompted twice when omitted
--non-interactiveoffrefuse to prompt; --username and --password become required

What it does, in order:

  • checks that /aegis/config/web_admin.toml exists — a missing file is an
  • error, not something the command writes;

  • imports fastapi, uvicorn, jinja2, python-multipart and tomlkit. If
  • any is missing, it runs pip install for the pinned versions: fastapi==0.163.1, uvicorn==0.54.0, jinja2==3.1.6, python-multipart==0.0.33, tomlkit==0.15.2;

  • creates aegis.db and applies the migrations under
  • database/migrations/core/aegis;

  • when no panel account exists, creates the first one from the flags or the
  • prompts;

  • prints the address the panel will listen on.
  • bash
    aegis web-admin setupaegis web-admin setup --username=admin --password='s3cret'     --name='Platform Admin' --email=ops@example.com --non-interactive

    Fresh host:

    text
    ✔ configuration: /aegis/config/web_admin.toml✔ dependencies: fastapi 0.163.1, uvicorn 0.54.0, jinja2 3.1.6, python-multipart 0.0.33, tomlkit 0.15.2✔ /aegis/database/storage/aegis/aegis.db (0001_init.sql, 0002_cron.sql, 0003_cron_orphans.sql applied)✔ created account admin (id 1)✔ panel on http://0.0.0.0:9981

    Second run:

    text
    ✔ configuration: /aegis/config/web_admin.toml✔ dependencies: fastapi 0.163.1, uvicorn 0.54.0, jinja2 3.1.6, python-multipart 0.0.33, tomlkit 0.15.2✔ /aegis/database/storage/aegis/aegis.db (up to date)✔ accounts: 1 already present✔ panel on http://0.0.0.0:9981

    When dependencies had to be installed, step 2 reads dependencies installed: … instead. With --non-interactive and no --username/--password it stops with ✖ --username and --password are required, exit 1. The prompts are Name:, Username:, Email: and Password:; the password is read twice, and a mismatch aborts with ✖ passwords do not match.

    #aegis web-admin start

    Starts the panel in its own session, writes the pid file and waits up to 20 seconds for it to appear. Logs go to /aegis/logs/web-admin.log.

    bash
    aegis web-admin start --host=<address> --port=<number>
    argumentdefaultmeaning
    --hostweb_admin.hostaddress to bind; 0.0.0.0 when the file says nothing
    --portweb_admin.portport to bind; 9981 when the file says nothing; 0 means "use the file"
    bash
    aegis web-admin startaegis web-admin start --host=127.0.0.1 --port=8443
    text
    ✔ started (pid 48122) on 127.0.0.1:8443

    With no flags the line names the configured values, 0.0.0.0:9981 by default.

    Other outcomes, all printed as a success line with exit 0:

    text
    ✔ already running (pid 48122)✔ exited immediately, see /aegis/logs/web-admin.log✔ started (pid 48122), still initialising, see /aegis/logs/web-admin.log

    exited immediately means the child died before writing its pid file; the log holds the reason. A missing dependency gets a hint, and any other exception ends the command with exit 1:

    text
    ✖ No module named 'uvicorn'; run `aegis web-admin setup` first

    #aegis web-admin stop

    Asks the panel to exit with SIGTERM and waits up to 15 seconds for the pid file to disappear. A stale pid file is removed rather than reported.

    bash
    aegis web-admin stop
    argumentdefaultmeaning
    --host, --port—accepted for symmetry with start and ignored by this command
    bash
    aegis web-admin stopaegis web-admin stop   # a second call reports that nothing runs
    text
    ✔ stopped (pid 48122)
    text
    ✔ not running

    If the process ignores the signal:

    text
    ✔ pid 48122 did not stop within 15s; check /aegis/logs/web-admin.log

    That line is a message, not a failure: the exit code is still 0.

    #aegis web-admin restart

    Runs stop, then start, and prints both results in order.

    bash
    aegis web-admin restart --host=<address> --port=<number>
    argumentdefaultmeaning
    --hostweb_admin.hostaddress for the new process
    --portweb_admin.portport for the new process; 0 means "use the file"
    bash
    aegis web-admin restartaegis web-admin restart --port=8080
    text
    ✔ stopped (pid 48122)✔ started (pid 48210) on 0.0.0.0:8080

    When nothing was running, the first line is ✔ not running and the second still starts the panel.

    #aegis web-admin run

    Runs uvicorn in the foreground. This is the command start launches in the background, with the same host and port; the child writes the pid file itself and removes it on exit.

    bash
    aegis web-admin run --host=<address> --port=<number>
    argumentdefaultmeaning
    --hostweb_admin.hostaddress to bind
    --portweb_admin.portport to bind; 0 means "use the file"
    bash
    aegis web-admin runaegis web-admin run --host=127.0.0.1 --port=9982

    The output is uvicorn's own log, which is also what lands in /aegis/logs/web-admin.log when start runs it:

    text
    INFO:     Uvicorn running on http://0.0.0.0:9981 (Press CTRL+C to quit)

    Ctrl+C stops the server; the finally block removes the pid file and the process exits 0. Requests are logged (access_log=True), and X-Forwarded-Proto is trusted only from web_admin.forwarded_allow_ips (default 127.0.0.1), which is what marks the session cookie Secure behind a TLS-terminating proxy.

    #aegis web-admin status

    Prints where the panel listens and what it has stored. It takes no options; the address comes from web_admin.toml and the defaults.

    bash
    aegis web-admin status
    argumentdefaultmeaning
    ——the command takes no options
    bash
    aegis web-admin statusaegis web-admin status   # what to check before a deploy

    Running:

    text
    ℹ Web admin  state         running (pid 48122), up 3h 12m  address       0.0.0.0:9981  log           /aegis/logs/web-admin.log  database      /aegis/database/storage/aegis/aegis.db (212.0 KiB)  tables        schema_migrations, sessions, settings, users  accounts      1  sessions      2  dependencies  ok: fastapi 0.163.1, uvicorn 0.54.0, jinja2 3.1.6, python-multipart 0.0.33, tomlkit 0.15.2

    Stopped:

    text
    ℹ Web admin  state         stopped  address       0.0.0.0:9981  log           /aegis/logs/web-admin.log  database      /aegis/database/storage/aegis/aegis.db (212.0 KiB)  tables        schema_migrations, sessions, settings, users  accounts      1  sessions      0  dependencies  ok: fastapi 0.163.1, uvicorn 0.54.0, jinja2 3.1.6, python-multipart 0.0.33, tomlkit 0.15.2ℹ start it with `aegis web-admin start`

    state is running (pid N), up <time> or stopped; uptime is read from /proc. database shows the file size in binary units. tables lists what exists in aegis.db, or none. dependencies is ok: <versions> or incomplete: missing: <names>.

    #aegis web-admin passwd

    Changes the password of one panel account and closes every session of it.

    bash
    aegis web-admin passwd <username>
    argumentdefaultmeaning
    <username>adminthe panel account to update
    bash
    aegis web-admin passwdaegis web-admin passwd ops

    The password is read twice without echo; an empty answer aborts, and three mismatches in a row abort with a message:

    text
    New password: Repeat password: ✔ password changed for admin; sessions closed
    text
    ✖ empty password; nothing changed
    text
    ⚠ passwords do not match, try again

    Failures exit 1 and change nothing: no such account: ops, cannot read the accounts: no such table: users. Every session row of that account is deleted, so a browser holding the old cookie is logged out on its next request.