Repository navigation
Updates
The updater installs the release archive — the .zip asset attached to a GitHub release, which
ships vendor/. It never uses a branch tarball: a branch tarball cannot contain vendor/, so it can
never satisfy the manifest inside it, and the update would refuse itself.
GET /admin.php?action=update.check (or the Updates page) reads the GitHub releases API with a
15-minute cache and reports the version delta, release notes, and whether the release carries an
installable archive (archive, installable). The panel disables Apply when it does not.
POST updater.php?api_key=<key>&action=install&format=json&dry_run=1
The dry run downloads the release archive, refuses entries with unsafe paths, verifies every file
against the manifest embedded in the archive, and reports the files that would be replaced (to,
asset, verified, unchanged, steps). It writes nothing to the project — the archive lives in a
temporary directory under storage/state/ and is removed before the answer. It fails loudly when the
release has no archive instead of reporting success.
Because it judges the release and not the local manifest, "nothing to replace" means the release matches this installation, not merely the files match themselves.
ALLOW_UPDATE = true is required for the panel button; the machine API treats the key as the
credential.
- Resolve the release asset and download it once.
- Refuse any archive entry with an absolute path,
..or control characters. - Verify each file against the archive's own sha256 manifest — the first mismatch refuses the whole update.
- Back up every file about to be replaced to
storage/backups/app-<timestamp>/with abackup.jsondescribing the run. - Copy only the files that actually changed.
- Install the archive's own
config/manifest.json. This is not bookkeeping: the manifest is excluded from its own file list, so the copy step above can never carry it. Without it the tree holds the new release's files while describing the old one, and every later status check reports the files it just wrote as locally modified.
content/, storage/ and .md.ini are never touched. The updater does not run migrations,
does not change the database (there is none), does not touch services, cron, the firewall, DNS or the
PHP configuration.
ALLOW_RESTORE = true enables restoring application files from an app-* backup
(?restore=latest or ?restore=app-YYYYmmdd-HHMMSS), and restoring content from a content backup in
the panel. A restore always writes a …-pre-restore snapshot first.
The new files are on disk, but PHP may still execute the old bytecode, and the page keeps
naming the previous version. Measured on a PHP-FPM host on 2026-11-14: after switching a
release the site reported the old version for minutes, and systemctl reload did not
help — a graceful reload sends SIGUSR2 and the shared opcache segment survives it.
The reason is worth knowing, because it is not the usual "validate_timestamps" story:
opcache keys a script by the path it was asked for, not by the target of the symlink.
When the request path (public/mdscribe/index.php) is stable and the symlink moves, the
cached entry keeps its key with ts=0 — no timestamp to compare — and the old bytecode
keeps running.
What actually clears it:
systemctl restart php8.5-fpm # restart, not reloadphp -r 'opcache_reset();' does not help: the CLI has its own (here disabled) opcache
segment, so it clears nothing the web pool sees. If a restart of a shared pool is not
acceptable, call opcache_reset() from inside the pool — a temporary script in the document
root that runs it and is deleted immediately, which is what mdscribe-deploy does.
mdscribe-deploy does this for you through a one-shot token-scoped endpoint in the site
document root that calls opcache_reset() and is removed immediately. Measure before and
after rather than trusting the footer:
php /usr/local/lib/mdscribe/verify-tree.php <site-path> --fingerprint # what is on disk
php /usr/local/lib/mdscribe/page-fingerprint.php https://host/path/ # what is served
curl -sI https://host/path/ | grep -i x-powered-by # what PHP reportsIf the tree fingerprint matches the release and x-powered-by does not, the files are right
and the bytecode is stale.
| You want | Use |
|---|---|
| Click once, keep the current directory layout | Admin → Updates (needs ALLOW_UPDATE = true and the PHP zip extension) |
| Place a release as a unit, switch atomically, roll back with one command |
mdscribe-deploy <version> on the host |
| A value to quote next to a release tag |
mdscribe-deploy prints the tree and page fingerprints; the panel does not |
No ALLOW_UPDATE on a production box |
mdscribe-deploy — it does not read .md.ini for permission and never touches runtime state |
mdscribe-deploy is a bash script shipped in the repository under tools/deploy/, installed
with --install-tools next to verify-tree.php and page-fingerprint.php. It keeps releases
side by side:
<site>/mdscribe -> mdscribe.releases/<version> (swapped with mv -T)
<site>/mdscribe.releases/<v>/ the release tree, exactly as published
<site>/mdscribe-data/ content/ storage/ .md.ini — the only runtime state
| Message | Cause |
|---|---|
| "The latest release has no .zip archive attached" | the release was published without the asset — attach MD.Scribe-<version>.zip
|
| "Integrity check failed for …" | the archive does not match its embedded manifest; refused by design, retry or install manually |
| "ALLOW_UPDATE is false in .md.ini" | the flag is off |
| "The PHP zip extension is required" | install php8.5-zip and reload the pool |
MD.Scribe 3.6.3 "Errata" · PHP 8.5 (verified on 8.5.12) · MIT · repository · releases