Skip to content

Updates

Mikhail Deynekin edited this page Nov 14, 2026 · 4 revisions

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.

Check

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.

Dry run

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.

Apply

ALLOW_UPDATE = true is required for the panel button; the machine API treats the key as the credential.

  1. Resolve the release asset and download it once.
  2. Refuse any archive entry with an absolute path, .. or control characters.
  3. Verify each file against the archive's own sha256 manifest — the first mismatch refuses the whole update.
  4. Back up every file about to be replaced to storage/backups/app-<timestamp>/ with a backup.json describing the run.
  5. Copy only the files that actually changed.
  6. 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.

Restore

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.

After an update

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 reload

php -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 reports

If the tree fingerprint matches the release and x-powered-by does not, the files are right and the bytecode is stale.

Panel or mdscribe-deploy?

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

If it refuses

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

Clone this wiki locally