Configure the Craft plugin

The plugin works without any configuration beyond LEDGE_SECRET_KEY. Everything else has a default you can change, either with an environment variable or in config/ledge.php. There are no settings in the control panel.

How settings resolveCopy Anchor Link

Each setting is read in this order:

1. The key in config/ledge.php, if you've set it.
2. The matching environment variable: the key in SCREAMING_SNAKE_CASE with a LEDGE_ prefix. diskUnhealthyAt reads LEDGE_DISK_UNHEALTHY_AT.
3. The default.

Environment variables are the easiest way to vary settings between staging and production. To start a config file with every option listed and commented out, run:

./craft ledge/publish-config

It won't overwrite an existing config/ledge.php unless you pass --force.

<?php

return [
    'diskDegradedAt' => 85,
    'diskUnhealthyAt' => 95,
    'queueStaleAfter' => 600,
    'enabledChecks' => [
        'failedLogins' => false,
    ],
];

LEDGE_SECRET_KEY="…"
LEDGE_DISK_DEGRADED_AT=85
LEDGE_DISABLED_CHECKS=failedLogins,freeform

Thresholds and statusesCopy Anchor Link

• Thresholds come in pairs. …DegradedAt and …UnhealthyAt. A check trips a tier when the measured value is at or above it.
• Turn off a tier by setting it to null in the config file, or its environment variable to empty or off. With diskDegradedAt off, the disk check only reports Healthy or Unhealthy.
• Status settings take healthy, degraded or unhealthy. Setting one to healthy keeps the condition in the check's data without affecting the site's status.
• Invalid values are logged and replaced with the default, so a typo never takes the endpoint down.

Every check reports the thresholds it used, so Ledge can show why a site tripped.

Turn checks offCopy Anchor Link

All checks run by default. Turn one off with either:

• LEDGE_DISABLED_CHECKS, a comma-separated list of check names, or
• enabledChecks in config/ledge.php, setting a check to false. Checks you don't list stay on.

If the config file sets enabledChecks, LEDGE_DISABLED_CHECKS is ignored. Check names are listed in Health checks.

To keep a check running but stop one known result from affecting the site, ignore it in Ledge instead. Ignoring applies to one check on one site and leaves the rest of your fleet alone.

Endpoint and authenticationCopy Anchor Link

If you change a path, update the health check URL in Ledge to match.

Check thresholdsCopy Anchor Link

Each setting has a matching LEDGE_* environment variable, for example LEDGE_QUEUE_STALE_AFTER.

Status levelsCopy Anchor Link

These decide how serious a condition is. Each takes healthy, degraded or unhealthy.

ignoredEnvVars (LEDGE_IGNORED_ENV_VARS, comma-separated) lists environment variables the environment check shouldn't report as missing.

Update runs and backupsCopy Anchor Link

The copy runs as a queue job, so the site needs a working queue runner. See Install for the full list of requirements.