# PHP-FPM Runtime Baseline

This directory contains the application-specific PHP-FPM pool used by the production Nginx template. It avoids relying on global PHP defaults that may be too small for contract, document, branding, and other private-file workflows.

## Baseline

`microfinance.conf.example` configures a dedicated `microfinance` pool with:

- socket: `/run/php/php8.3-fpm-microfinance.sock`;
- upload limit: 20 MB;
- POST body limit: 25 MB;
- PHP memory limit: 256 MB;
- PHP execution limit: 120 seconds;
- FPM hard request timeout: 180 seconds;
- slow-request logging after 10 seconds;
- a conservative four-worker starting point.

The Nginx template uses `client_max_body_size 25m` and the same dedicated socket. Keep the three body-size limits coherent: Nginx must be at least as large as `post_max_size`, and `post_max_size` must be at least as large as `upload_max_filesize`.

Worker counts are capacity settings, not application requirements. Measure available memory and real traffic before increasing `pm.max_children`; each worker can approach the configured PHP memory limit during expensive document work.

## Install on Ubuntu / PHP 8.3

From the deployed release:

```bash
sudo install -m 0644 deploy/php-fpm/microfinance.conf.example \
  /etc/php/8.3/fpm/pool.d/microfinance.conf

sudo install -m 0644 deploy/nginx/microfinance.conf.example \
  /etc/nginx/sites-available/microfinance
sudo ln -sfn /etc/nginx/sites-available/microfinance \
  /etc/nginx/sites-enabled/microfinance
```

Adapt the domain, certificate paths, application path, PHP version, user/group, and socket path when the target server differs from the template.

Validate both services before restart/reload:

```bash
sudo php-fpm8.3 -tt
sudo nginx -t
sudo systemctl restart php8.3-fpm
sudo systemctl reload nginx
```

Confirm that the dedicated socket exists after PHP-FPM restarts:

```bash
sudo test -S /run/php/php8.3-fpm-microfinance.sock
```

## Runtime preflight

Run the repository preflight against the installed files:

```bash
PHP_FPM_POOL_FILE=/etc/php/8.3/fpm/pool.d/microfinance.conf \
NGINX_SITE_FILE=/etc/nginx/sites-enabled/microfinance \
bash deploy/scripts/php-runtime-preflight.sh
```

The command fails when the PHP-FPM/Nginx sockets do not match, upload/body limits are below the production baseline, PHP memory is below 256 MB, or request timeouts are too short.

After the preflight passes, perform a staging upload using a representative large PDF/DOCX near the application's allowed maximum and verify upload, document review, contract generation, and download complete successfully. Repository CI validates the templates and preflight logic, but only the target host can prove the effective service configuration and available capacity.
