Aegis documentation

#Troubleshooting

Errors already met while bringing Aegis up, with the fix that made them go away.

#Installer

MessageCause and fix
build profile not found: …/storage/data/apps/<app>/build.tomldeploy.sh excluded storage; it now ships storage/data and excludes only storage/{apps,temp,media}
ModuleNotFoundError: app.modules.thor.contextrelative import depth; installer/core/tasks/* needs ...context, not ....context
Can't instantiate abstract class PrepareTaskbuild tasks were missing run()
E: Unable to locate package xempty apt index; install_packages refreshes the index before installing, only when something is missing
named-checkconf / libisc…so not foundtools live in bin/ and need LD_LIBRARY_PATH; the cube handles both
no version information available (libpcre2)cosmetic warning from a locally built pcre2

#Runtime

MessageCause and fix
aegis: bundled Python runtime not foundfresh server: ./bin/aegis-prepare
python.sha256 attribute errorold archive_ready() after the multi-arch change; use python.artifact().sha256 (fixed)
CMake 3.24 or higher is required. You are running 3.22.1distro cmake is too old; the runtime ships cmake 3.31.6
meson.build:2040: ERROR: Expecting endif got stringdistro meson 0.61 cannot parse modern syntax; the runtime ships meson 1.7.2
No CMAKE_CXX_COMPILERg++ was missing from the toolchain
stdio.h / limits.h not foundlibc6-dev missing; the headers task installs it, and packages.installed() now compares the status string instead of searching for “installed”

#Build

MessageApplicationFix
make: No targets specified and no makefile foundredisthe catalog had two entries named redis; catalog.by_name() prefers the standalone one over the PECL module
No targets specifiedvsftpdthe Makefile has no all target; targets = []
undefined reference to cap_initvsftpdlibcap lives in the multiarch dir; patch adds /usr/lib/*/libcap.so
assignment discards const / memchrbeanstalkdmodern-toolchain.patch drops -Werror and fixes the SIGTERM handler signature
long long reliability test 1gmpGCC 15 defaults to C23; profile sets CFLAGS=-O2 -std=gnu17
cannot find install-shopendkimgit snapshot without autotools helpers; pre = [["autoreconf", "-fi"]] + autoconf/automake/libtool
cmilter not foundopendkimlibmilter-dev
no strlcpy/strlcatopendkimlibbsd-dev
dependency "libuv" not foundbindlibuv1-dev
liburcu-cds / lmdb / libcapbindliburcu-dev, liblmdb-dev, libcap-dev
Dependency "cmocka" not foundbind-Ddeveloper=enabled enables tests; removed
No <db.h> include file foundpostfixeither libdb-dev or -DNO_DB; we use -DNO_DB (spelled with the D!)
default_cache_db_type=btreepostfixadd default_database_type=lmdb default_cache_db_type=lmdb
rpcsvc/ypclnt.hpostfix-DNO_NIS
pcre.h not foundpostfix-DHAS_PCRE=2 for PCRE2
passwd file entry for postfixpostfix[system] groups = ["postdrop"] users = ["postfix"]
undefined reference to SharpYuv*imagemagick, phplibwebp 1.6 ships SharpYuv separately: LIBS=-lsharpyuv
expat.h not foundgitlibexpat1-dev
cargo: not foundgitNO_RUST=YesPlease
SSL_get0_group_name@OPENSSL_3.2.0gitgit assigns LDFLAGS; pass LDFLAGS= with our library paths on the command line
No such file or directory: './configure'freetypethe GitHub archive lacks the dlg submodule; use the official release tarball
git submodule update failsfreetypesame cause
aegis-local.conf + zone loopbind--libdir=lib keeps OpenSSL out of lib64
brotli library missingnginxngx_brotli builds brotli sources from its own deps/; module not enabled by default
us->default_portnginxupstream-fair is incompatible with nginx 1.30; dropped
location directive is not allowed herenginxsnippets must not be included at http level
invalid host in upstream "/aegis/run/php/php-fpm.sock"nginxunix sockets need unix: in fastcgi_pass
open() "…/fastcgi_params" failednginxinclude {{nginx_prefix}}/conf/fastcgi_params
getpwnam("aegis-www") failednginxworker account is created by configure
mkdir() "…/nginx/cache" failednginxcache directory is created by configure
unknown geoip2_data_country_codenginxthe variable only exists with a database; the log uses - when it is absent

#Cubes and certificates

MessageFix
no TSIG key at …/keys/tsig.keyrun aegis cubes bind configure first
rndc reload failednamed is not running, or controls/key mismatch
certbot failed with dns_rfc2136 errorszone missing in BIND, TSIG mismatch, or NS not delegated
Aegis reported success but <name> is missingcertbot wrote to another config-dir; check certbot.data_dir and cli.ini
ssl ensure fails with openssl.cnfthe bundled OpenSSL has no ssl/ directory; OPENSSL_CONF falls back to /etc/ssl/openssl.cnf

#Panel, tasker and live feed

MessageCause and fix
no action registered as <name>the tasker is running code from before that action existed: Management → Tasker → Restart tasker
a task stays running after a crashit was marked interrupted on the next start; look at the log, then Retry
aegis-tasker exited immediately in keeper.logtwo starts raced and one lost the lock; the keeper now reports the live pid instead. If it repeats, check for two daemons: pgrep -x aegis-tasker
the task window shows nothing during workthe window was minimised: click the bar; the bell still counts
the dashboard tables blank out after a few secondspulse could not read the keeper registry; aegis pulse status shows what each area published
a page never updatesthe WebSocket is down or unauthorised: check aegis keeper status for aegis-r-bird, reload the page for a fresh token
a vhost answers 403 while the panel looks correctthe web account cannot reach the document root: aegis sys perms --path <root> --check, then --fix
the panel shows old values after a deploy/assets/ is no-cache, so a plain reload is enough; if the data is old, the panel process is old: aegis web-admin restart
a new utility class has no effectthe CSS is prebuilt; add the rule to both css/app.css and src/app.css

#Debugging tips

bash
# what is installed whereaegis thor apps | headaegis keeper services# build output of one appaegis install nginx            # up to 12 lines of the failing command# traces# platform logs: <root>/logs, i.e. aegis.logs_dir/etc/aegis/storage/logs/installer.log   # one line per step/etc/aegis/storage/logs/keeper.log      # supervision actions/etc/aegis/storage/logs/pulse.log       # what the live feed sampled/etc/aegis/storage/logs/tasker.log      # the queue daemon/etc/aegis/storage/logs/web-admin.log   # the panel# application logs: /aegis/logs, written by the daemons themselves/aegis/logs/nginx/error.log             # nginx startup problems

#Deploy quirks

  • deploy.sh needs --full to ship the runtime; without it a fresh server has
  • code and vendor but no interpreter.

  • tar fallback exists for servers without rsync; excludes are anchored
  • (/storage, ./storage) so vendor/apps/runtime still ships.