#Installation
#1. Deploy the code
From the development machine:
./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 hereThe target defaults to root@167.233.113.136:/etc/aegis and can be overridden:
AEGIS_HOST=203.0.113.10 AEGIS_PORT=22 AEGIS_USER=root AEGIS_PASS='secret' ./bin/deploy.shstorage/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:
cd /etc/aegis./bin/aegis-prepare # or: ./bin/aegis-prepare --forceThis 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:
./bin/thor runtime status#3. Run the installer
./bin/aegis install # checks -> one form -> builds everything selected./bin/aegis install nginx # one application and its libraries onlyThe flow:
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 linksetup/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
already installed: …);content changed and restarts only the daemons that need it;
.aegis-installed (profile fingerprint) or.aegis-failed next to the prefix; a failed one is rebuilt automatically;
so that application rebuilds on the next run.
#5. First-run expectations
| Step | Typical duration (4 vCPU) |
|---|---|
| verification + core | 2 s |
| openssl | 2–4 min |
| pcre2, zlib, beanstalkd, redis | seconds |
| mariadb | 10–20 min |
| postgresql | 1–2 min |
| nginx | 1 min |
| php (with PECL) | 3–5 min |
| dovecot, postfix, bind | 1–3 min each |
#6. Unsupported hosts
verification/server stops before writing anything when:
app/modules/uapi/platforms/;1.1.1.1:443 fails;#7. After the install
A finished run already configured every service and installed the boot hook, so nothing has to be started by hand:
./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:
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.
http://<server-ip>:9981aegis 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:
./bin/aegis configure # every selected application + keeper./bin/aegis configure nginx # one application onlyThat 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:
./bin/aegis keeper enable # /etc/init.d/aegis-keeper + update-rc.d./bin/aegis keeper disable