Aegis documentation

#Supervisor

The Supervisor cube gives operator programs their own control plane next to the platform daemons: workers, bots and long-running scripts, with restarts, log rotation and a status command. It renders supervisord.conf under supervisor.config_dir (/aegis/config/supervisor) and one programs/<name>.conf per program, keeps logs in supervisor.log_dir and the control socket plus pid in supervisor.run_dir. Each program logs to <log_dir>/<name>.log and <log_dir>/<name>-error.log, capped at 20 MB.

Programs are files, not database rows. supervisord runs in the foreground as the keeper service aegis-supervisor (supervisord -n -c <main conf>), and reload performs reread + update so running programs are not bounced.

#Common commands

Cube operations share one wrapper: ✔ supervisor: <detail> on success, ✖ <message> on failure (exit 1), and {"ok": true, "cube": "supervisor", "result": "<detail>"} with global --json.

expose is the only verb that prints a block instead of that line.

VerbEffect
configurerender supervisord.conf, then restart or start the daemon, validate
validaterun supervisorctl status; exit code 3 (a stopped program) is not an error
reloadsupervisorctl reread then update: new and changed programs are applied
statusread run/supervisor/supervisord.pid: running (pid N) or stopped
startstart supervisord through the keeper
stopSIGTERM, then SIGKILL after 15 seconds
restartstop, then start; every program is restarted
exposeprint config, program count and socket, then publish the Supervisor tools
helpprint the command list with examples

#configure

bash
aegis cubes supervisor configureaegis --json cubes supervisor configure

The main file is rewritten only when its content changed, but a running daemon is restarted regardless, because a configuration change must reach it.

text
✔ supervisor: configuration is valid, 3 programs{"ok": true, "cube": "supervisor", "result": "configuration is valid, 3 programs"}

#validate

bash
aegis cubes supervisor validateaegis --json cubes supervisor validate

Asks supervisorctl status for the program list. A program in STOPPED makes supervisorctl exit 3, which is accepted; a broken socket or configuration is reported with the last eight lines.

text
✔ supervisor: configuration is valid, 3 programs{"ok": true, "cube": "supervisor", "result": "configuration is valid, 3 programs"}

#reload

bash
aegis cubes supervisor reloadaegis --json cubes supervisor reload

Applies the configuration without a restart: unchanged programs keep running, new programs are added and removed ones are dropped from Supervisor.

text
✔ supervisor: configuration reloaded{"ok": true, "cube": "supervisor", "result": "configuration reloaded"}

#status

bash
aegis cubes supervisor statusaegis --json cubes supervisor status

This is the state of supervisord itself, not of the individual programs.

text
✔ supervisor: running (pid 2101){"ok": true, "cube": "supervisor", "result": "running (pid 2101)"}

#start

bash
aegis cubes supervisor startaegis --json cubes supervisor start
text
✔ supervisor: started (pid 2101){"ok": true, "cube": "supervisor", "result": "started (pid 2101)"}

#stop

bash
aegis cubes supervisor stopaegis --json cubes supervisor stop

Stopping the daemon stops every supervised program with it.

text
✔ supervisor: stopped (pid 2101){"ok": true, "cube": "supervisor", "result": "stopped (pid 2101)"}

#restart

bash
aegis cubes supervisor restartaegis --json cubes supervisor restart
text
✔ supervisor: stopped (pid 2101), started (pid 2133){"ok": true, "cube": "supervisor", "result": "stopped (pid 2101), started (pid 2133)"}

#expose

bash
aegis cubes supervisor exposeaegis --json cubes supervisor expose
text
cube           supervisorinstalled      /aegis/apps/system/supervisor/4.3configuration  /aegis/config/supervisorstate          running (pid 2101)pid            2101log            /aegis/logs/supervisor/supervisord.logconfig         /aegis/config/supervisor/supervisord.confprograms       3socket         /aegis/run/supervisor/supervisor.sockpublished      /aegis/bin/supervisord, /aegis/bin/supervisorctl
text
{"ok": true, "cube": "supervisor", "installed": "/aegis/apps/system/supervisor/4.3", "configuration": "/aegis/config/supervisor", "state": "running (pid 2101)", "pid": "2101", "log": "/aegis/logs/supervisor/supervisord.log", "config": "/aegis/config/supervisor/supervisord.conf", "programs": "3", "socket": "/aegis/run/supervisor/supervisor.sock", "published": "/aegis/bin/supervisord, /aegis/bin/supervisorctl"}

#help

bash
aegis cubes supervisor helpaegis cubes help supervisor
text
ℹ Supervisor — Operator programs under SupervisorCommands  validate   Check the configuration  reload     Reload the running daemon  configure  Write the configuration and validate it  start      Start supervisord  stop       Stop supervisord  status     Show whether supervisord runs  restart    Restart supervisord  expose     Show where it is installed and how it runs  programs   Manage supervised programs  help       Show every command with examples

The examples block follows.

#Programs

text
aegis cubes supervisor programs  Manage supervised programsCommands  list    List programs  add     Create a program  remove  Delete a programRun 'aegis cubes supervisor programs <command> --help' for the options of one command.

#programs list

bash
aegis cubes supervisor programs listaegis --json cubes supervisor programs list

Lists the programs/*.conf files by name; it does not ask Supervisor for their state. It takes no options.

text
✔ supervisor: worker, bot{"ok": true, "cube": "supervisor", "result": "worker, bot"}

#programs add

bash
aegis cubes supervisor programs add worker --command="/usr/bin/php worker.php" --directory=/aegis/www/appaegis cubes supervisor programs add bot --command="/aegis/bin/python3 bot.py" --user aegis --no-autostart
OptionMeaning
nameprogram name: lowercase, letters, digits, -, _
--commandrequired; stored exactly as typed, because Supervisor does not use a shell
--directoryworking directory for the program
--usersystem account to run as; default aegis, must exist
--allow-rootrequired confirmation when --user root
--no-autostartdo not start the program with supervisord

Writes programs/<name>.conf with autorestart=true, startsecs=5, stopasgroup=true, killasgroup=true and both log files. When the daemon runs, reread/update is executed so the program appears immediately.

text
✔ supervisor: program worker written{"ok": true, "cube": "supervisor", "result": "program bot written"}

The command is not replaced: an existing name is an error. Change the file under programs/ and run reload, or remove and add it again.

#programs remove

Destructive. Deletes programs/<name>.conf and applies the change; a running instance is stopped by update. The program's log files stay.

bash
aegis cubes supervisor programs remove workeraegis --json cubes supervisor programs remove bot
ArgumentMeaning
namethe program to remove
text
✔ supervisor: program worker removed{"ok": true, "cube": "supervisor", "result": "program bot removed"}