Grav CMS on your server

BOA runs Grav 2 sites under the same Ægir control panel as your Drupal and Backdrop sites: panel-driven install, verify, backup, restore and one-click core upgrades, platforms that always track the newest official Grav release, and Grav's own command line (bin/grav, bin/gpm) wrapped for safe shell use — clients included.

Grav is a flat-file CMS: serving a site needs no database at all, so a Grav site node attaches to a database-less server entry and the panel's database machinery simply stays out of the way.

Opt-in, off by default

The switch is _GRAV_SUPPORT, mirrored in two control files (each program reads its own), and it defaults to NO in both:

1. /root/.<user>.octopus.cnf — the Grav platform, the panel module and the per-instance staging of official release archives.
2. /root/.barracuda.cnf — the system layer (the grav CLI wrapper and its shell exposure).

Set _GRAV_SUPPORT=YES in both files, then run your normal upgrade pair, for example:

barracuda up-lts system
octopus up-lts o1

(Use up-pro on PRO instances — whichever tree your server already follows.)

That enables the Grav frontend module, stages the newest official release archive for upgrades, and puts grav on the command line.

Asking for the platform itself

Which platforms an instance carries is a separate switch, and it lives in the instance's own control folder rather than in the config file. Put the GRV symbol into platforms.info — upper-case, space- or newline-separated, alongside any other symbols that instance should carry:

echo "GRV" > /data/disk/<user>/static/control/platforms.info

Then run the Octopus upgrade for that instance, and the Grav platform trio (prod, stage and dev) is built and registered in the control panel.

Two things worth knowing about that file: it replaces the default platform list, so pinned symbols mean the instance skips distributions added in future releases — use the keyword ALL if you would rather never skip anything. And the account owner can do all of this without root: editing platforms.info and then touch ~/static/control/run-upgrade.pid has a background agent start the same upgrade within a few minutes. The cheat sheet in ~/static/control/README.txt on every instance lists the full symbol set.

One platform, whole-install sites

Grav's own upgrade tooling refuses to operate on split or symlinked installs, so Grav sites do not share a platform codebase the way Drupal sites do. Instead:

• The platform is a pristine seed: the official Grav admin bundle (core plus the admin, API, login, email, forms and error plugin set), built automatically from the newest official release.
• Each site is a complete, self-contained Grav install placed inside the platform's sites/ directory, seeded from the platform at install time. The web root of the site's vhost is the site's own directory — every site upgrades, backs up and restores as one unit.

One platform node therefore serves any number of sites, and deleting the platform is refused while sites still live on it.

What you get

• A platform that maintains itself. The platform tree builds from the newest official Grav admin-bundle release — there is no version pin to bump. Only official releases are ever used, delivered through the BOA mirrors; your server never fetches from third-party channels at task time.
• The site lifecycle. Install, Verify, Backup, Restore, Import, Clone, Enable, Disable, Reset login and Delete behave as they do for Drupal sites, adjusted for a database-less site: backups use the file-tree mode and say so honestly (database-only backup modes are refused rather than silently doing nothing), the archive carries the site's own security keys (the panel seeds them, so a backup is never missing a file the web server created), and Restore rebuilds the whole install from the archive with sessions and nonces intact. Clone copies the whole capsule to the new domain and makes the copy its own site: fresh nonce and API signing keys, pending password-reset links cleared, every contact address pointed at the copy's own admin address, the per-host environment overlay renamed to the new domain, error display switched off. The copy keeps the None (flat-file sites) database server; the clone dialog does not offer another. Migrate is not offered for Grav sites: Rename moves a site to a new domain on its own platform, and Upgrade a copy places an upgraded copy on another Grav platform.
• The database server. Enabling Grav support creates a None (flat-file sites) database server on the panel; every Grav site must be attached to it (the site form refuses a real database server for a Grav site while the None server exists). A Grav site attached to MySQL installs with a warning and cannot be restored or cloned until it is moved.
• One-click core upgrades. The site's Upgrade Grav task installs the newest staged official release over that site in place, and refuses when nothing newer than the site is staged. The dialog names the version the site is running now (run a Verify first if it has not been recorded yet), so you can see what the upgrade replaces. Site content, accounts and configuration survive by construction: the release replaces only the files it ships. The admin bundle's plugins and theme are refreshed in the same task, from the same official archive, wherever the release carries a newer version than the site has, and never the other way round. A safety backup is taken first and a verify runs after.
• Upgrade a copy. Try a release before your visitors do. This task builds the whole site again at a new domain, on whichever Grav platform you choose, upgrades that copy to the newest staged official release and verifies it. The original keeps serving at its own domain throughout, from an install that is never opened for writing. The copy is the same site under a temporary name: it keeps the original's content, accounts, configuration and security keys, so what you test is what you keep. It starts with encryption switched off and the panel's cron disabled, which is what you want for a site nobody has been sent to yet; both stay off until you turn them on deliberately, Cutover included.
• Rename. Moves a site to a new domain on the same platform, with a safety backup first. Nothing is copied and nothing is rebuilt: the install moves, and its content, accounts and configuration go with it. The old domain stops serving as soon as the rename completes, custom aliases are not carried over, and encryption ends up disabled for the new name, because certificates are bound to the name. Switch encryption back on deliberately once the new domain is the one you want certified.
• Cutover. The deliberate final step after Upgrade a copy: make this site answer at a domain another site currently holds, normally the original domain of the site the copy came from. The site holding that domain is backed up and then deleted, and this site is renamed onto the freed domain. The domain is unserved between the two, for as long as the rename takes. Choose the domain with that in mind, and note that you can only take over a domain held by a site your account may retire: the panel refuses a cutover onto a site guarded against deletion or one you may not administer. Encryption ends up disabled for the new name here too.
• The grav CLI. The wrapper at /opt/local/bin/grav runs Grav's own console (grav), package manager (gpm <args>) and plugin commands (plugin <args>) against whichever install your shell is inside. Client shell accounts get the everyday verbs — including gpm install and gpm update, so the long tail of plugins and themes stays in your hands — while install-mutating verbs (self-upgrade, direct-install, sandbox, clean) are reserved for the panel and admin identities, keeping every site on the panel's managed upgrade path.
• Enforced modern PHP. Grav sites always run the server's default modern PHP (8.4, with 8.5 or the 8.3 floor as fallbacks) for both web and CLI. Unlike Drupal sites there is no per-site PHP selection — Grav's own floor is 8.3 and the version is part of the hosting contract.

Plugins, themes and email

The admin bundle's plugin set upgrades with core through the panel task. Everything else installs and updates through gpm under your site account — official GPM releases only:

cd ~/platforms/<platform>/sites/<your-site>
grav gpm install some-plugin
grav gpm update

Outbound email (password resets, form notifications) uses Grav's email plugin; point it at your relay in the site's user/config/plugins/email.yaml with mailer: engine: smtp. The whole password-reset round trip works out of the box once a mailer is configured.

The security posture

A Grav site's vhost is rendered with a contract built for a flat-file CMS on a shared box:

• Only /index.php executes — every other PHP path, Grav's internal trees (system/, vendor/, cache/, logs/, bin/), YAML sources, dotfiles, SQL dumps and root metadata are denied outright.
• Account files, configuration and environment overrides carry no world-readable bits on disk, and the hosting tasks re-assert that on every verify.
• The fleet's request classification (bans, scanner probes, crawler and AI-fetcher policy, TLS-on-plain-port) applies to Grav vhosts exactly as it does to Drupal vhosts, and the per-site user_admin_access allow-list covers Grav's /admin the same way it covers Drupal's /user.
• Capacity is bounded by concurrency caps that never throttle a logged-in editor or an API client; a capacity shed answers with a retryable 503, never a dropped connection.

Grav's Admin 2 panel and its REST API (/api/v1/…, JWT authenticated) work normally behind all of this.

The fine print

• Grav's own scheduled-backup feature stays off (its shipped default), and the site's backup/ directory is excluded from panel backups — the panel's Backup task is the one place backups happen, so archives never nest older archives.
• The panel's cron scheduling does not apply to Grav sites in this wave; Grav's scheduler integration is a later addition.
• A site's drushrc.php and .env at the install root are hosting artefacts (the panel writes and protects them); leave them be — they survive upgrades and restores by construction.