#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.
| Verb | Effect |
|---|---|
configure | render supervisord.conf, then restart or start the daemon, validate |
validate | run supervisorctl status; exit code 3 (a stopped program) is not an error |
reload | supervisorctl reread then update: new and changed programs are applied |
status | read run/supervisor/supervisord.pid: running (pid N) or stopped |
start | start supervisord through the keeper |
stop | SIGTERM, then SIGKILL after 15 seconds |
restart | stop, then start; every program is restarted |
expose | print config, program count and socket, then publish the Supervisor tools |
help | print the command list with examples |
#configure
aegis cubes supervisor configureaegis --json cubes supervisor configureThe main file is rewritten only when its content changed, but a running daemon is restarted regardless, because a configuration change must reach it.
✔ supervisor: configuration is valid, 3 programs{"ok": true, "cube": "supervisor", "result": "configuration is valid, 3 programs"}#validate
aegis cubes supervisor validateaegis --json cubes supervisor validateAsks 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.
✔ supervisor: configuration is valid, 3 programs{"ok": true, "cube": "supervisor", "result": "configuration is valid, 3 programs"}#reload
aegis cubes supervisor reloadaegis --json cubes supervisor reloadApplies the configuration without a restart: unchanged programs keep running, new programs are added and removed ones are dropped from Supervisor.
✔ supervisor: configuration reloaded{"ok": true, "cube": "supervisor", "result": "configuration reloaded"}#status
aegis cubes supervisor statusaegis --json cubes supervisor statusThis is the state of supervisord itself, not of the individual programs.
✔ supervisor: running (pid 2101){"ok": true, "cube": "supervisor", "result": "running (pid 2101)"}#start
aegis cubes supervisor startaegis --json cubes supervisor start✔ supervisor: started (pid 2101){"ok": true, "cube": "supervisor", "result": "started (pid 2101)"}#stop
aegis cubes supervisor stopaegis --json cubes supervisor stopStopping the daemon stops every supervised program with it.
✔ supervisor: stopped (pid 2101){"ok": true, "cube": "supervisor", "result": "stopped (pid 2101)"}#restart
aegis cubes supervisor restartaegis --json cubes supervisor restart✔ supervisor: stopped (pid 2101), started (pid 2133){"ok": true, "cube": "supervisor", "result": "stopped (pid 2101), started (pid 2133)"}#expose
aegis cubes supervisor exposeaegis --json cubes supervisor exposecube 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{"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
aegis cubes supervisor helpaegis cubes help supervisorℹ 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 examplesThe examples block follows.
#Programs
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
aegis cubes supervisor programs listaegis --json cubes supervisor programs listLists the programs/*.conf files by name; it does not ask Supervisor for their state. It takes no options.
✔ supervisor: worker, bot{"ok": true, "cube": "supervisor", "result": "worker, bot"}#programs add
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| Option | Meaning |
|---|---|
name | program name: lowercase, letters, digits, -, _ |
--command | required; stored exactly as typed, because Supervisor does not use a shell |
--directory | working directory for the program |
--user | system account to run as; default aegis, must exist |
--allow-root | required confirmation when --user root |
--no-autostart | do 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.
✔ 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>.confand applies the change; a running instance is stopped byupdate. The program's log files stay.
aegis cubes supervisor programs remove workeraegis --json cubes supervisor programs remove bot| Argument | Meaning |
|---|---|
name | the program to remove |
✔ supervisor: program worker removed{"ok": true, "cube": "supervisor", "result": "program bot removed"}