README

Vigilant Joomla Healthchecks

A Joomla plugin that provides a healthcheck endpoint for any site and integrates seamlessly with Vigilant.

Features

• Exposes health information and metrics on POST /index.php?option=io_govigilant&task=health.check.
• Default checks for Joomla included
• Allows registration of custom checks and metrics

Installation

Install the package via Composer inside your Joomla project root:

composer require govigilant/joomla-healthchecks

Copy the plugin files to plugins/system/vigilanthealthchecks and enable the System - Vigilant Healthchecks plugin in the Joomla administrator.

Configuration

Set a bearer token in the plugin options. Requests must include the header:

Authorization: Bearer YOUR_TOKEN

Usage

Once enabled, the health endpoint is reachable at:

POST /index.php?option=io_govigilant&task=health.check

Example request:

curl -X POST "https://your-site.test/index.php?option=io_govigilant&task=health.check" \
  -H "Authorization: Bearer $VIGILANT_HEALTHCHECK_TOKEN" \
  -H "Content-Type: application/json"

Extending

Use the Vigilant\JoomlaHealthchecks\HealthCheckRegistry service to register additional checks and metrics. A simple example inside a custom Joomla extension:

use Vigilant\HealthChecksBase\Checks\Metrics\DiskUsageMetric;
use Vigilant\JoomlaHealthchecks\HealthCheckRegistry;

$registry = $container->get(HealthCheckRegistry::class);

$registry->registerMetric(DiskUsageMetric::make());

Checks extend Vigilant\HealthChecksBase\Checks\Check and metrics extend Vigilant\HealthChecksBase\Checks\Metric.

Available Checks

Available Metrics

Development Environment

A ready-to-use Docker Compose setup lives in devenv/. Start the stack: docker compose -f devenv/docker-compose.yml up --build.

This provisions Joomla 5 and Joomla 6, MariaDB, and mounts this package as System - Vigilant Healthchecks.The admin credentials are admin / Admin1234!@# and a default bearer token is set to testing.

Joomla 5 is reachable on port 8000 and Joomla 6 on port 8001.

Stop everything with docker compose -f devenv/docker-compose.yml down -v when you're finished.

Quality

Run the quality checks locally:

composer quality

Packaging for the Joomla Extension Directory

Build an installable ZIP (with production dependencies) via:

scripts/package-jed.sh

The script assembles the plugin in a temporary directory, runs composer install --no-dev, and writes dist/plg_system_vigilanthealthchecks.zip for upload to the JED.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Vincent Boon
• All Contributors

License

The MIT License (MIT). Please see License File for more information.