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. 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.
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.
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 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 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 reportsIf 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.iniIf 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.
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 rowpresent; -
action=install&dry_run=1(POST) → downloads the release, verifies it against the manifest inside the archive, and reportswould replace: 0on an up-to-date tree; -
action=install(POST, no dry run) withALLOW_UPDATE = false→ refused withALLOW_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
| 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