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:
@@ -4,7 +4,16 @@ Single-tenant PHP/SQLite app. Tiny — runs comfortably on the smallest VPS tier
|
|||||||
|
|
||||||
## Requirements
|
## 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.
|
- 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.
|
- 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$ {
|
location ~ \.php$ {
|
||||||
include fastcgi_params;
|
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 SCRIPT_FILENAME $document_root$fastcgi_script_name;
|
||||||
fastcgi_param HTTP_AUTHORIZATION $http_authorization;
|
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
|
## TLS
|
||||||
|
|
||||||
Use Let's Encrypt + certbot. Example:
|
Use Let's Encrypt + certbot. Example:
|
||||||
|
|||||||
Reference in New Issue
Block a user