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

Check	Description
CoreEnvironmentCheck	Checks required PHP extensions, `display_errors`, and pending Joomla core updates.
FilesystemHealthCheck	Validates `configuration.php` permissions, writable directories, installation directory cleanup, and plugin version alignment.
DatabaseHealthCheck	Tests database connectivity, utf8mb4 support, schema alignment with Joomla core, and table integrity.
ExtensionsHealthCheck	Confirms critical plugins are enabled, the debug plugin is disabled, and the default `admin` user is removed.
ConfigurationLanguageCheck	Ensures Joomla's `language` and `metalang` configuration values are set.
SecuritySettingsCheck	Verifies secure settings such as session handler, `force_ssl`, secret length, and admin login notification plugin.
SchedulerHealthCheck	Flags overdue Joomla scheduler tasks whenever the scheduler tables exist.
CacheCheck	Runs a read/write probe against the configured cache store.
DiskSpaceCheck	Monitors available disk space.

Available Metrics

Metric	Description
CpuLoadMetric	Reports the current CPU load average.
MemoryUsageMetric	Reports overall system memory usage.
DiskUsageMetric	Reports disk space utilization percentages.

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

govigilant / joomla-healthchecks

Maintainers

Details