DEPLOY.md: version-agnostic FPM socket + PHP 8.1+ requirement louder + sites-enabled backup gotcha

Two issues hit during a real deploy:

1. The nginx example pinned fastcgi_pass to /run/php/php8.2-fpm.sock.
   When the target box runs a different PHP-FPM (8.3 here), the socket
   doesn't exist and nginx 502s. Switch to /run/php/php-fpm.sock (the
   alternatives symlink installed by Ondrej Sury's packaging) so the
   default config works against whatever current PHP is installed,
   with a comment explaining the fallback for boxes without the symlink.

2. The PHP version requirement was buried in a one-liner. Promote it to
   a multi-line note that names the specific 8.x features used, says
   loudly that 7.x will not parse the code, and points at Sury's repo
   for boxes stuck on an old default.

Also added a callout warning against cp foo.conf foo.conf.bak inside
sites-enabled/, since nginx loads every file in that directory and the
backup becomes a second vhost claiming the same server_name (silently
shadowed via the "conflicting server name … ignored" warning).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-29 13:41:54 +01:00
parent b1833258b9
commit f6d2573a35

View File

@@ -4,7 +4,16 @@ Single-tenant PHP/SQLite app. Tiny — runs comfortably on the smallest VPS tier
## Requirements
- PHP **8.1+** with `pdo`, `pdo_sqlite`, `json`, `mbstring` (all standard).
- **PHP 8.1+ is required.** The code uses typed properties, `str_starts_with`,
`mixed`/`never` return types, named arguments, and constructor property
promotion. PHP 7.x will not even parse the source files. PHP 7.2 has also
been EOL since November 2020 — don't run a public service on it.
Confirm with `php -v`. If the box is on an older default, install a current
PHP alongside it (Ondrej Sury's repo is the standard on Debian/Ubuntu) and
point this vhost at the new FPM socket.
- PHP extensions: `pdo`, `pdo_sqlite`, `json`, `mbstring` (all standard).
- Apache + `mod_rewrite`, or nginx with a `try_files` fallback.
- HTTPS terminating in front of PHP. Plain HTTP is technically accepted, but the plugin client will refuse to talk to non-`https://` endpoints.
@@ -91,7 +100,11 @@ server {
location ~ \.php$ {
include fastcgi_params;
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
# Version-agnostic — Ondrej Sury's packaging installs this symlink
# pointing at whichever php-fpm is the current "alternative". If the
# symlink doesn't exist on your box, hardcode e.g. php8.3-fpm.sock.
# Check with: ls -la /run/php/
fastcgi_pass unix:/run/php/php-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param HTTP_AUTHORIZATION $http_authorization;
}
@@ -101,6 +114,13 @@ server {
}
```
> **Gotcha:** nginx loads *every* file in `sites-enabled/` regardless of
> extension. Don't `cp healthcheck.conf healthcheck.conf.bak` inside that
> directory — the backup becomes a second vhost claiming the same
> `server_name`, and nginx silently ignores one of them ("conflicting server
> name … ignored" in the error log) which manifests as the new config not
> taking effect. Back up *outside* `sites-enabled/`.
## TLS
Use Let's Encrypt + certbot. Example: