Aegis documentation

#web

aegis web owns the two things nginx and PHP read from the panel's database: the rendered vhost files and the php.ini and pool files. It has three commands — setup, apply and status — and apply is the only way to publish a change made in web.db to the running services.

bash
aegis web setup     # create web.db and apply its migrationsaegis web apply     # render every vhost and php.ini, validate, reloadaegis web status    # nginx, PHP and vhost summary

This group does not create vhosts. A vhost row is created by aegis account <account> sites create, which also stamps its owner; apply only turns rows into files.

Output is human-formatted throughout. The commands print their own lines and tables and never consult the global --json flag, so aegis --json web status prints exactly the same text as aegis web status.

exit codemeaning
0every step it attempted succeeded
1at least one step failed; the message says which
2argparse rejected the arguments

#Commands

#aegis web setup

Creates the web database when it is missing and applies every pending migration, in filename order. The file lives at /aegis/database/storage/web/web.db; the migrations are the SQL files under database/migrations/core/web, recorded in schema_migrations so each one runs once. The command is idempotent.

bash
aegis web setup
argumentdefaultmeaning
——the command takes no options
bash
aegis web setupaegis web setup   # safe to repeat

First run, with every migration pending:

text
✔ web: /aegis/database/storage/web/web.db (0001_init.sql, 0002_vhost_rate.sql, 0003_cache_zones.sql, 0004_guards.sql, 0005_bots.sql, 0006_vhost_php_socket.sql, 0007_account.sql)

Second run:

text
✔ web: /aegis/database/storage/web/web.db (up to date)

A migration that fails leaves its transaction rolled back and the command prints the error on stderr and exits 1. Run it again after fixing the cause; the migrations already recorded are skipped.

#aegis web apply

Reloads live services. Every enabled vhost is rewritten, nginx is validated and reloaded, then php.ini and the pool files are rewritten and php-fpm is reloaded. Traffic is not stopped, but a configuration error in the database becomes an error here, at the reload, not silently later.

Runs two phases, one after the other. A failure in the first does not skip the second: the command reports both and exits 1 if either failed.

Phase 1 — nginx:

  • reads every vhost row with enabled set and renders
  • <nginx.config_dir>/sites/<vhost>.conf (default /aegis/config/nginx/sites);

  • writes the cache-zone file and the guard map under conf.d, plus the
  • challenge page under html/;

  • keeps the previous text of every file it may change in memory, then runs
  • nginx -t;

  • on a rejected configuration, restores every file and stops, so the running
  • server keeps its last good configuration;

  • on success, removes the files the previous run wrote and this one no longer
  • renders (the list is in aegis-rendered.json one level above sites/), then reloads nginx.

    Phase 2 — PHP:

  • renders <php.config_dir>/<version>/php.ini for every enabled version
  • (default /aegis/config/php);

  • writes the same text to the active php.ini the cube publishes and creates
  • the panel marker in the PHP config directory, which tells aegis php configure to stop writing that file;

  • renders one pool file per pool into <php.fpm_config_dir>/pools.d and
  • deletes pool files that no longer exist in the database;

  • runs php-fpm -t and reloads FPM. A stopped FPM is reported as
  • saved but not applied (php-fpm is not running) instead of failing the write.

    bash
    aegis web apply
    argumentdefaultmeaning
    ——the command takes no options
    bash
    aegis web applyaegis web apply   # after any change made in the panel
    text
    ✔ 3 vhosts written, configuration is valid; configuration reloaded✔ 2 php.ini files written, 1 pool files, configuration is valid; pools reloaded

    A rejected nginx render:

    text
    ✖ nginx -t failednginx: [emerg] unknown directive "proxy_passs" in /aegis/config/nginx/sites/john-shop.conf:42

    The file restore happens before that message is printed, so the site keeps answering. A PHP render that finds nothing to write still reloads:

    text
    ✔ 3 vhosts written, configuration is valid; configuration reloaded✔ 0 php.ini files written, 0 pool files, nothing written to validate; saved but not applied (php-fpm is not running)

    #aegis web status

    Read-only. Prints the nginx process state, its version and file counts, the active PHP version and the socket state of every version row, then the database path and the number of vhost rows.

    bash
    aegis web status
    argumentdefaultmeaning
    ——the command takes no options
    bash
    aegis web statusaegis web status   # after a deploy, to confirm nginx picked the new build
    text
    ✔ nginx: running, nginx version: nginx/1.30.0  config   /aegis/config/nginx/nginx.conf  sites    4  vhosts   3 total, 2 enabled, 0 proxy, 1 with TLS✔ php: active 8.5, 2 installed  8.5    active  socket ok  8.4          no socket  database /aegis/database/storage/web/web.db  vhosts   3 rows

    What each line means:

    linesource
    nginx: runningthe pid file belongs to a live process
    configthe main nginx.conf the cube published
    sites*.conf files in the nginx sites directory
    vhosts … total, enabled, proxy, with TLScounts over the vhost rows
    php: active …php.version from the configuration, and how many versions are installed
    per-version lineactive marks the served series; socket ok or no socket is a real file test
    databasepath of web.db, whether it exists or not
    vhosts … rowsrows in nginx_vhosts

    When nginx is not running the first line reads ✔ nginx: not running, nginx version: nginx/1.30.0; when the binary cannot report a version it reads unknown version. A version that exists in php_versions but whose directory is gone still gets a row.