Craft CMS
DocsAdd ledge-craft to a Craft CMS site and connect it to Ledge.
The ledge-craft plugin gives Ledge a secured health endpoint on your site. Ledge polls it for check results, versions and pending updates. Update runs and backups use the same plugin once you turn them on.
| Craft 5 | Craft 4 | |
|---|---|---|
| Plugin version | 5.x | 4.x |
| PHP | 8.2 or later | 8.0.2 or later |
Composer picks the right version for your Craft install, so the command is the same for both.
composer require ledgehq/ledge-craft./craft plugin/install ledge./craft ledge/generate-keyThis writes a random 32-character key to your .env as LEDGE_SECRET_KEY and prints it. On environments where you don't keep a .env file, copy the printed value into your host's environment settings instead.
In Ledge, add the site. The health check URL fills in as the site's URL followed by /_ledge/health, for example https://example.com/_ledge/health. Change it only if you've moved the endpoint.
Paste the key from the previous step into Secret key and save. Ledge sends the key in a request header on every poll, and queues the first poll straight away.
Request the endpoint with your key. A healthy site returns 200 with a JSON body listing every check:
curl -H "X-Ledge-Key: $LEDGE_SECRET_KEY" https://example.com/_ledge/health| Response | What it means |
|---|---|
200 | The site is healthy or degraded. |
503 | At least one check is unhealthy. The body says which. |
401 with Unauthorized | The key doesn't match LEDGE_SECRET_KEY on the site. |
401 with LEDGE_SECRET_KEY is not configured | The site has no key set. Run ./craft ledge/generate-key. |
The endpoint sends no-cache headers. If you still get a cached or blocked response, make sure your CDN or firewall passes /_ledge/* through to Craft with request headers intact. For Cloudflare, see Sites behind Cloudflare.
Update runs and backups need Ledge to take a copy of the site's database. That part of the plugin is off by default. Turn it on with one environment variable:
LEDGE_ACQUIRE_ENABLED=trueThe site also needs:
./craft queue/run or a daemon both work.mysqldump or pg_dump on the server, or a custom backupCommand in your Craft config.sodium extension, used to encrypt the copy before it leaves the server.Update runs also need the site's repository linked in Ledge. Before you turn them on, read Security: the sandbox gets a copy of production data and environment variables, and you can choose which variables to leave out. The related settings are in Configuration.