mojointeractive / craft-observer
mojo observer's connector for Craft CMS: signed status endpoints, deploy markers and form tests.
Package info
github.com/mojointeractive/craft-observer
Type:craft-plugin
pkg:composer/mojointeractive/craft-observer
Requires
- php: ^8.2
- craftcms/cms: ^5.11
Requires (Dev)
None
Suggests
- verbb/formie: Formie 4 forms (4.0.0 or later) appear in observer's inventory and can be tested
- webhubworks/craft-backup: The Backup plugin's targets, runs and retention appear in observer's backups report
Provides
None
Conflicts
None
Replaces
None
README
The connector between a Craft CMS 5 site and mojo observer, mojo's monitoring tool. It answers
observer's signed requests about the install (versions, pending updates, the queue, backups, admins, the
craftly doctor where there is one, an Oh Dear health report, the Formie inventory), reports deploys with
php craft observer/deploy-marker, and lets observer's form tests pass through real forms.
It is configured by environment variables only and does nothing until OBSERVER_KEY is set.
Requirements
Craft CMS 5.11 or later, PHP 8.2 or later. Forms: Formie 4.0.0 or later (not its betas). Backups: the
Backup plugin (webhubworks/craft-backup) where observer should watch them.
The site must answer at its domain root with Craft's default actionTrigger (actions): observer signs
the paths /actions/observer/api/<action> and the Patrol bypass matches exactly those. Nonces, the rate
counter and the form tests' mail routing live in Craft's data cache, so web requests and queue workers must
share it (Redis on a host with several nodes; the default file cache is fine on one host). The queue figures
come from Craft's queue table; a site on another queue driver reports zeros there.
On a craftly site
Nothing to install: craftly requires this plugin from plugins/observer and installs it with
php craft up. craftly's docs/observer.md has the details.
On any other Craft 5 site
-
composer require mojointeractive/craft-observer(the package is on Packagist, fromgithub.com/mojointeractive/craft-observer), thenphp craft plugin/install observer, and commitcomposer.json,composer.lockandconfig/project(the install is a project config change, applied on the servers byphp craft up). Updates arecomposer update mojointeractive/craft-observer. -
In observer, open the site → Craft → Generate connection key, and put the lines it shows into the host's
.env. -
If the site has a maintenance mode, let observer's requests through and tell the plugin when it is on, so observer sees the maintenance instead of an outage (craftly does both by itself):
use mojo\observer\security\MaintenanceBypass; use mojo\observer\security\MaintenanceState; // where the maintenance mode decides: this request passes MaintenanceBypass::applies((string)($_SERVER['REQUEST_URI'] ?? '')); // once, at start-up: how to ask MaintenanceState::$resolver = static fn (): bool => $myMaintenance->isActive();
Without a resolver the plugin reports the
MAINTENANCEenvironment variable. -
To record deploys, run
php craft observer/deploy-markeron the server right after each release goes live (--releasenames it; by default the directory thecurrentsymlink points at). It never fails: without its variables, or with observer unreachable, it says so and exits 0. -
php craft observer/check --pingsays what observer will find here: the configuration, which plugins it can report on (the Backup plugin, Formie), the data cache, and whether a signed request topinggets through the web server (--url=<base url>when the primary site's URL is not reachable from the server itself). It exits 1 while a line is not ok.
The source of truth is craftly's plugins/observer; this repository is published from it read-only
(scripts/publish-observer-plugin.sh in craftly), one tag per version.
Environment
| Variable | Meaning |
|---|---|
OBSERVER_KEY |
The site's key from observer (observer generates 64 hex characters; anything of 32 or more counts). The switch: without it every endpoint answers 404. |
OBSERVER_ENABLED |
false turns the plugin off with the key still set. Default true. |
OBSERVER_SITE_ID |
observer's id for the site, for deploy markers. |
OBSERVER_HOOK_URL |
observer's deploy hook, for deploy markers. |
OBSERVER_HEALTH_SECRET |
The secret of Oh Dear's application-health check, so Oh Dear may read health without a signature. |
What observer asks
Every request to /actions/observer/api/<action> is signed with OBSERVER_KEY (HMAC-SHA256 over method,
path, timestamp, nonce and body hash; five minutes of clock skew, no nonce twice, 60 requests a minute).
The actions: ping, vitals, backups, doctor, health, formie-forms, packages, form-test-run, form-test-cleanup.
No recipient address leaves the site.
vitals is one entry per provider: the platform (versions, environment, the settings observer watches), the
updates Craft knows of, the queue, system (free space under storage/, pending migrations, project-config
drift), the newest local backup files, the admin accounts, and the craftly doctor's lines where there is
one. health is the same in Oh Dear's application-health format: storage, migrations, project config and
the queue on every site, then the doctor's lines; Oh Dear reads it with OBSERVER_HEALTH_SECRET.
backups reports what the Backup plugin (webhubworks/craft-backup) knows: each target with its backups
(time and size), whether it could be listed, free disk where the driver says, the last run and its errors
per target, the retention config and the monitor_backups rules. Target hosts, users, passwords, keys and
paths stay on the site. The answer is cached 10 minutes; SFTP targets are listed with a 10 s timeout. Without
the Backup plugin it answers {"installed": false}.
packages lists the install's Composer packages (name, installed version, development requirement or not)
from vendor/composer/installed.json. observer matches them against published security advisories; only
names and versions leave the site. A package from a path repository (the project's own code) is left
out; one from a private repository is listed by name.
Form tests
observer submits a tested form like a visitor, with an X-Observer-Test token signed for one run, one
form and at most ten minutes. With a valid token only: the page renders uncached and the form renders and
validates without its captchas (with Blitz installed, Craft neither serves that request from Blitz's
cache nor stores it; a file cache served by a server rewrite never reaches Craft, so there the page's
?observer-run=<id> must not be cached as the same page: craft observer/check warns when it would be),
Formie's honeypot and minimum-time guards are off for the request, its
integrations do not run, and its notification mail goes to observer's probe inbox (or the probe is added as
Bcc), each message with X-Observer-Run. A request whose token does not verify, or names a form plugin the
site does not run, submits nothing (409). The routing waits in Craft's data cache for the queue jobs, so
the queue workers must share it; a test notification without routing is held back, never sent to the
form's recipients. observer deletes the test submission afterwards.
Other form plugins
Forms reach observer through form adapters (mojo\observer\forms\FormAdapter). The plugin brings one for
Formie; another form plugin adds its own with a class-level listener,
Event::on(Observer::class, Observer::EVENT_REGISTER_FORM_ADAPTERS, …), that appends to the event's
adapters. Two adapters with the same handle: the last one counts.