Aegis documentation

#Cube: php

PHP 8.5 with PHP-FPM, built by the installer (including the PECL extensions).

In the panel: Web → PHP, and the PHP pools a vhost can use. Every write there is a task.

#Configuration

toml
[php]version = "8.5"user = "aegis-www"group = "aegis-www"config_dir = "/aegis/config/php"fpm_config_dir = "/aegis/config/php/fpm"log_dir = "/aegis/logs/php"run_dir = "/aegis/run/php"socket = "/aegis/run/php/php-fpm.sock"error_log = "/aegis/logs/php/php-error.log"memory_limit = "512M"upload_max_filesize = "128M"post_max_size = "128M"max_execution_time = 120read_timeout = "300s"pm_max_children = 50pm_start_servers = 8pm_min_spare_servers = 4pm_max_spare_servers = 16pm_max_requests = 500
KeyDefaultMeaning
version8.5informational; --php= on a vhost must match it
user, groupaegis-wwwaccount the pool runs as; created if missing
config_dir/aegis/config/phpphp.ini and the FPM tree
fpm_config_dir…/fpmglobal FPM block plus pools.d/
log_dir/aegis/logs/phpFPM, error and slow logs
run_dir/aegis/run/phppid file and sockets
socket…/php-fpm.sockdefault pool socket; extra pools get <pool>.sock
error_log/aegis/logs/php/php-error.logPHP error log from php.ini
memory_limit512Mphp.ini memory limit
upload_max_filesize128Mper-file upload limit
post_max_size128Mwhole request limit
max_execution_time120seconds per script
read_timeout300sfastcgi_read_timeout in the nginx snippet
pm_max_children50maximum FPM workers
pm_start_servers8workers started immediately
pm_min_spare_servers4minimum idle workers
pm_max_spare_servers16maximum idle workers
pm_max_requests500requests before a worker respawns

#Files

text
<php.config_dir>/├── php.ini                        main configuration└── fpm/    ├── aegis-php-fpm.conf         global FPM block, includes the pools    ├── aegis-pool.conf            default pool [www]    └── pools.d/*.conf             additional pools<php.log_dir>/├── php-fpm.log├── php-error.log└── php-fpm-slow.log<php.run_dir>/├── php-fpm.pid└── php-fpm.sock

#Commands

bash
aegis cubes php configure        # php.ini, FPM config, default pool, validateaegis cubes php validate         # php-fpm -taegis cubes php reload           # SIGUSR2: reload poolsaegis cubes php start|stop|restart|statusaegis cubes php extensions       # compiled extensions with a countaegis cubes php expose           # paths, pid, pools; publishes the commands

#expose

bash
aegis cubes php exposecube           phpinstalled      /aegis/apps/web/php/8.5configuration  /aegis/config/phpstate          running pid 738755pid            738755log            /aegis/logs/php/php-fpm.logversion        8.5php.ini        /aegis/config/php/php.inifpm config     /aegis/config/php/fpm/aegis-php-fpm.confsocket         /aegis/run/php/php-fpm.sockpools          1published      /aegis/bin/php /aegis/bin/php-fpm /aegis/bin/php-cgi 

expose writes wrapper scripts into <aegis.bin_dir> (/aegis/bin), not plain symlinks: the built binaries carry RUNPATH, which glibc applies only to direct dependencies, so indirect libraries (ICU data, for example) need LD_LIBRARY_PATH. With /aegis/bin in PATH:

bash
php -vPHP 8.5.12 cli built:  NTSphp-fpm -vPHP 8.5.12 fpm-fcgi built:  NTS

Published: php, php-fpm, php-cgi, php-config, phpize, pecl.

#Pools

bash
aegis cubes php pools listaegis cubes php pools create --name=app --max-children=20# listens on /aegis/run/php/app.sock — one socket per pool by defaultaegis cubes php pools create --name=other --socket=/aegis/run/php/custom.sockaegis cubes php pools show appaegis cubes php pools delete app
  • the default pool is [www], rendered by configure into aegis-pool.conf;
  • additional pools live in pools.d/<name>.conf and are included by glob;
  • create and delete validate the configuration and, when php-fpm is running,
  • reload it with SIGUSR2 (graceful pool reload, no dropped connections);

  • --user, --group, --socket, --max-children override the values from
  • [php] in the configuration.

    Example pool file:

    ini
    [app]user = aegis-wwwgroup = aegis-wwwlisten = /aegis/run/php/app.socklisten.owner = aegis-wwwlisten.group = aegis-wwwlisten.mode = 0660pm = dynamicpm.max_children = 20pm.start_servers = 8pm.min_spare_servers = 4pm.max_spare_servers = 16pm.max_requests = 500

    #Wiring a site to FPM

    nginx's PHP snippet uses php.socket (the default pool). A site with its own pool points at it explicitly:

    bash
    aegis cubes nginx vhosts create --domain=app.example.com --location=php-mvc# then edit the vhost and change fastcgi_pass to unix:/aegis/run/php/app.sock

    Per-vhost pool selection (--php-pool) is not implemented yet.

    #End-to-end example

    bash
    cd /etc/aegis./bin/aegis cubes php configure./bin/aegis cubes php start./bin/aegis keeper start                 # keep it running./bin/aegis cubes php expose             # php becomes available in PATHphp -m | head./bin/aegis cubes nginx vhosts create --domain=app.example.com --location=php-mvc./bin/aegis cubes nginx reload

    Verify:

    bash
    curl -s -o /dev/null -w "%{http_code}\n" https://app.example.com/aegis cubes php statusaegis --json cubes php expose