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. The reason 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. systemctl reload does not help either: a graceful reload sends SIGUSR2 and the shared opcache segment survives it.

How long the window actually is (measured 2026-11-14)

Read from inside a worker on the live pool — PHP 8.5.12 fpm-fcgi, opcache.enable=1, opcache.validate_timestamps=1, opcache.revalidate_freq=60:

Situation When a reader sees the new file
File replaced, opcache untouched 61 s — polled once a second, the flip came at 61 s; three trials confirmed the first response after a rewrite is still the previous version
Same, then a token-scoped opcache_reset() first request — 0.06 s after the reset call
Real deploy (mdscribe-deploy 3.6.1) switch at 15:10:26, reset at 15:10:26, the page named 3.6.1 at 15:10:27 (a poller on the live URL, once a second)

So the deadline is the ini value, not "minutes": a shared pool without a reset serves the previous code for up to revalidate_freq seconds, which is why the deploy resets it in the same second as the switch.

What shortening the window would cost (measured 2026-11-14)

opcache.revalidate_freq=0 re-checks every compiled file on every request. Two measured components, on the same host:

Component Measured
PHP files compiled by one page request (get_included_files() after a full render) 41
one stat() of such a file, with PHP's stat cache cleared 4.2 µs (2.2 µs when the cache answers)
live latency today, revalidate_freq=60 mean 39 ms, p95 46 ms (n=30)

So the added cost of revalidate_freq=0 is about 0.17 ms per request, well under one percent of the response time: the window can be shortened for the sake of freshness without touching latency. The direct A/B (same pool, different values) was not run — it needs a second pool or a temporary nginx block on a host that serves 25 sites — so the number above is arithmetic over two measurements, not a measured delta.

Trap when reading the settings: on this host php -i | grep opcache.revalidate_freq prints 2, because it describes the CLI binary and the CLI ini — not the pool. The pool's effective values have to be read from a worker (a temporary script that echoes ini_get('opcache.revalidate_freq')), or inferred from the measurement above.

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 through a one-shot token-scoped endpoint.

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.

Where the settings live. The layout above puts the only runtime state in mdscribe-data/: content/, storage/ and .md.ini, and the deploy symlinks all three into every release. Until 3.6.2 the application's own settings write replaced the .md.ini symlink with a regular file, so settings silently moved into the release directory — and the next deploy seeded the new release from mdscribe-data/.md.ini, which by then held an older, much smaller file. Every panel setting (the admin password hash included) would have been discarded. Measured before the fix: mdscribe.releases/3.6.1/.md.ini was a 1 125-byte regular file while mdscribe-data/.md.ini was an 18-byte seed.

Check it in one line; a symlink is the healthy state:

readlink /var/www/<site>/mdscribe/.md.ini     # -> …/mdscribe-data/.md.ini
stat -c '%F %s %a' /var/www/<site>/mdscribe-data/.md.ini

If a release holds a regular .md.ini instead of a link (any release from 3.6.1 or older), copy it back into mdscribe-data/.md.ini, keep mode 0640 and the ozon:ozon owner, then replace the regular file in the release with a link to that path — and upgrade to 3.6.2, where the write keeps the link.

Panel or mdscribe-deploy?

There are three ways to update an installation, and they differ in who authorises the change and what evidence they leave behind.

You want Use Needs
Click once, keep the current directory layout Admin → Updates ALLOW_UPDATE = true, the PHP zip extension, an admin session
Drive it from a script, read the result as JSON updater.php?api_key=…&action=… the API_KEY from .md.ini; install additionally needs ALLOW_UPDATE — status, conflicts and install&dry_run=1 never write
Place a release as a unit, switch atomically, roll back with one command mdscribe-deploy <version> on the host shell access; it does not read .md.ini for permission and never touches runtime state
A value to quote next to a release tag mdscribe-deploy prints the tree and page fingerprints; the panel and the machine API do not

The machine API is the one that is easiest to get wrong, so its measured behaviour on a live host (2026-11-14) is worth recording:

  • action=status → ok: true, one row per manifest entry, every row present;
  • action=install&dry_run=1 (POST) → downloads the release, verifies it against the manifest inside the archive, and reports would replace: 0 on an up-to-date tree;
  • action=install (POST, no dry run) with ALLOW_UPDATE = false → refused with ALLOW_UPDATE is false in .md.ini — updates are disabled, nothing written.

So a key on its own does not arm remote replacement: the flag does, and it stays off until an operator turns it on. Turning it on is one line in .md.ini (ALLOW_UPDATE = true, or Admin → Settings → Security), and it should be turned off again afterwards on a host where nothing else needs it.

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