Aegis documentation

#Installation

#1. Deploy the code

From the development machine:

bash
./bin/deploy.sh                       # code + vendor, keeps the server runtime./bin/deploy.sh --full                # also ships the local runtime tree./bin/deploy.sh --delete              # remove files that no longer exist here

The target defaults to root@167.233.113.136:/etc/aegis and can be overridden:

bash
AEGIS_HOST=203.0.113.10 AEGIS_PORT=22 AEGIS_USER=root AEGIS_PASS='secret' ./bin/deploy.sh

storage/data is shipped (build profiles, templates, patches). The mutable parts of storage/ (apps, temp, media) and database/storage are not.

#2. Prepare the runtime

bin/aegis runs on a bundled CPython, so it cannot exist before the first run:

bash
cd /etc/aegis./bin/aegis-prepare              # or: ./bin/aegis-prepare --force

This extracts the pinned CPython build for the current architecture and installs the packages declared in config/thor/runtime.json — certbot, certbot-dns-rfc2136, meson, cmake. Using the runtime's own meson and cmake is deliberate: distribution versions are often too old (Ubuntu 26.04 ships meson 0.61.2, which cannot parse BIND 9.21).

Check it:

bash
./bin/thor runtime status

#3. Run the installer

bash
./bin/aegis install            # checks -> one form -> builds everything selected./bin/aegis install nginx      # one application and its libraries only

The flow:

text
verification/server   support, hardware, network, internet, osverification/vendor   catalog + checksums of all pinned artifactscore/requirements     base tools, CA store, directories, writabilitysetup/config          one form: IP, hostname, timezone, domain, e-mail,                      applications, database backends, panel adminbase/toolchain        compiler, build tools, C headers (only when building)apps/<name>           requirements, prepare, configure, compile, install,                      extensions (PECL), verifyconfigure/<name>      the cube of each selected app: configuration files,                      accounts, database bootstrap, startservices/keeper       boot hook, keeper daemon, every service verified up finish/platform       domain/SSL certificate and the /bin/aegis link

setup/config merges its answers into /etc/aegis/config/server.toml — it never replaces the file, so generated values such as the mail database password survive a re-run. Both the build and the configure phase re-read it, so a single invocation installs and configures exactly what was selected.

The configure phase runs in dependency order: bind (before certbot and OpenDKIM), postgresql, mariadb, redis, beanstalkd, vsftpd, php, nginx, supervisor, postfix (bootstraps the mail database), dovecot, mail (registers the primary domain), opendkim (keys for those domains), postsrsd (re-renders Postfix). The next step enables the boot hook, starts the keeper and fails if any supervised service is not running.

finish/platform closes the run: with a primary domain it issues a Let's Encrypt certificate through the BIND DNS-01 challenge (the zone already exists from the bind step), falling back to a local certificate when issuance fails; without a domain it generates a local certificate for the primary IP. It also links the launcher as /bin/aegis, and the closing report lists the installed application count, the zone and certificate paths, the timezone and the primary IP.

#4. Reruns are cheap

  • an application whose prefix exists is skipped (already installed: …);
  • the configure phase is idempotent: it re-renders files only when their
  • content changed and restarts only the daemons that need it;

  • verification writes .aegis-installed (profile fingerprint) or
  • .aegis-failed next to the prefix; a failed one is rebuilt automatically;

  • changing a profile (options, patches, dependencies) changes the fingerprint,
  • so that application rebuilds on the next run.

    #5. First-run expectations

    StepTypical duration (4 vCPU)
    verification + core2 s
    openssl2–4 min
    pcre2, zlib, beanstalkd, redisseconds
    mariadb10–20 min
    postgresql1–2 min
    nginx1 min
    php (with PECL)3–5 min
    dovecot, postfix, bind1–3 min each

    #6. Unsupported hosts

    verification/server stops before writing anything when:

  • the distribution has no module in app/modules/uapi/platforms/;
  • there is no public IPv4;
  • outbound TCP to 1.1.1.1:443 fails;
  • hardware is below the configured minimum.
  • #7. After the install

    A finished run already configured every service and installed the boot hook, so nothing has to be started by hand:

    bash
    ./bin/aegis keeper services         # every service, with its pid./bin/aegis cubes nginx expose      # paths, state, published commands./bin/aegis cubes mail domains list # mail domains known to the server

    #The panel

    The same run also installs the panel and creates aegis.db. The administrator is asked at the start, in the same form as everything else — username and password, both required, typed twice and never written to server.toml.

    A scripted host answers the form with flags instead:

    bash
    aegis install --yes --admin-password '…'   --domain example.com --timezone Europe/Bucharest

    --yes skips every question and trusts config/server.toml; a fresh panel needs --admin-password on the same line.

    text
    http://<server-ip>:9981

    aegis web-admin passwd changes an account password later, and aegis web-admin restart is what a deploy needs — the process keeps the code it started with.

    The tasker, pulse and Bird start with the keeper like every other daemon, so a finished install already has a working queue and a live dashboard. See panel.md, tasker.md and live.md.

    To re-render configuration later — after editing aegis.toml, server.toml or a profile — run the same phase again:

    bash
    ./bin/aegis configure               # every selected application + keeper./bin/aegis configure nginx         # one application only

    That command is idempotent and safe to repeat; it is also what to run after a git pull that changes templates. It finishes with services/keeper, which enables the boot hook, starts the daemon and fails when a supervised service is down.

    To manage the boot hook by hand:

    bash
    ./bin/aegis keeper enable           # /etc/init.d/aegis-keeper + update-rc.d./bin/aegis keeper disable