PHP Apps

App runtime configuration and vhost provisioning.

Host vars (per app):

apps:
  - name: shop                 # required
    type: php                  # required
    domain: "demo.example.com www.demo.example.com"  # required
    user: deploy               # optional, defaults to first in users
    php_version: "8.3"         # required
    subtype: shopware6         # optional
    web_root: /var/www/deploy/shop  # optional
    acme_root: /var/www/letsencrypt  # optional
    cert: letsencrypt          # optional
    letsencrypt_email: admin@example.com  # required if cert=letsencrypt
    database:                  # optional
      name: shop_db
      user: shop_user
    php_fpm:                   # optional
      max_children: 40
      start_servers: 20
      min_spare_servers: 10
      max_spare_servers: 20
      max_requests: 500
    backup_dirs:               # optional — directories to include in file backups
      - /var/www/deploy/shared
    cronjobs:                  # optional
      - name: "Run scheduler"
        job: "php /var/www/shop/artisan schedule:run >> /var/log/shop-cron.log 2>&1"
        schedule: "* * * * *"

Defaults:

user: first entry in users
web_root: /var/www//<app.name>
acme_root: /var/www/letsencrypt
cert: unset
php_fpm.max_children: 40
php_fpm.start_servers: 20
php_fpm.min_spare_servers: 10
php_fpm.max_spare_servers: 20
php_fpm.max_requests: 500

Notes:

subtype: shopware6 installs Shopware CLI on the server.
Database user passwords are generated automatically and stored in /etc/ploy/password.json.
backup_dirs lists directories to archive as .tar.gz during daily file backups. Archives are stored in /var/www/<appname>/backups/web/ and kept for 3 days locally.

PHP-FPM Status & Ping

Enable the FPM status and ping endpoints via php_fpm:

apps:
  - name: shop
    type: php
    php_fpm:
      status_path: /php-fpm-status  # optional, omit to disable
      ping_path: /php-fpm-ping      # optional, omit to disable

To expose the endpoints via nginx, add a file like ~/.config/nginx/20status.conf as the app user:

location = /php-fpm-status {
  access_log off;
  allow 127.0.0.1;
  allow 1.2.3.4;        # your monitoring IP (IPv4)
  allow 2001:db8::1;    # your monitoring IP (IPv6)
  deny all;

  include fastcgi_params;

  fastcgi_param SCRIPT_FILENAME /dev/null;
  fastcgi_param SCRIPT_NAME /php-fpm-status;

  fastcgi_pass fastcgi_backend_<appname>;
}

location = /php-fpm-ping {
  access_log off;
  allow 127.0.0.1;
  allow 1.2.3.4;        # your monitoring IP (IPv4)
  allow 2001:db8::1;    # your monitoring IP (IPv6)
  deny all;

  include fastcgi_params;

  fastcgi_param SCRIPT_FILENAME /dev/null;
  fastcgi_param SCRIPT_NAME /php-fpm-ping;

  fastcgi_pass fastcgi_backend_<appname>;
}

Replace <appname> with the app name as configured in apps[].name.