10

SITE_MONITORING

Jonathan Miller edited this page 2026-05-20 01:26:15 +00:00

Table of Contents

• Site Monitoring
• Architecture
• sites.json
• Supported Site Types
• Multiple Endpoints per Client
• Adding a New Client
• Via MCP (after restart)
• Manual
• Auto-Deploy with --deploy
• Metrics Exposed
• Blackbox Exporter (Prometheus)
• Joomla Monitor (textfile collector)
• Backup Monitoring
• Grafana Dashboard
• Table Layout
• Alerting
• Dashboard Generation
• Files
• Cron Jobs
• Related

← Back to Home

Site Monitoring

Endpoint monitoring for MokoWaaS (Joomla) and MokoCRM (Dolibarr) client sites using Prometheus, Grafana, and the Joomla Web Services API.

---

Architecture

sites.json (source of truth)
    │
    ├── generate-targets.sh
    │       ├── blackbox-http.json  → Prometheus file_sd (uptime, SSL, response time)
    │       ├── blackbox-ssl.json   → Prometheus file_sd (certificate expiry)
    │       ├── joomla-monitor.conf → joomla-monitor.sh (Joomla API metrics)
    │       └── Grafana dashboards  → MokoWaaS / MokoCRM dashboards
    │
    ├── joomla-monitor.sh (cron every 30m)
    │       └── joomla-sites.prom   → node-exporter textfile collector
    │
    ├── site-uptime-alert.sh (cron every 5m)
    │       └── ntfy alert-critical → DOWN/RECOVERED notifications
    │
    └── Grafana Dashboard (MokoWaaS)
                ├── Site Health table
                ├── Joomla Core & Extensions table
                ├── Backup Status table
                ├── Performance (response time + duration)
                └── Uptime History (30d availability)

---

sites.json

Central definition file at moko-platform/monitoring/sites.json. Defines all monitored endpoints with their type, client, and API tokens.

{
    "grafana": {
        "baseUrl": "https://bench.mokoconsulting.tech",
        "apiKey": "glsa_...",
        "dashboardFolder": "Endpoints",
        "dashboardFolderUid": "..."
    },
    "sites": [
        {
            "name": "clientname-live",
            "url": "https://example.com",
            "type": "mokowaas",
            "client": "ClientName",
            "joomlaToken": "...",
            "akeebaSecret": "",
            "tlsVerify": true
        },
        {
            "name": "clientname-dev",
            "url": "https://clientname.dev.mokoconsulting.tech",
            "type": "mokowaas-dev",
            "client": "ClientName",
            "joomlaToken": "...",
            "tlsVerify": false
        }
    ]
}

Supported Site Types

Type	Description
mokowaas	MokoWaaS — Joomla CMS (uses Joomla Web Services API)
mokowaas-dev	MokoWaaS development instance
mokowaas-demo	MokoWaaS demo instance
mokocrm	MokoCRM — Dolibarr ERP
mokocrm-dev	MokoCRM development instance
mokocrm-demo	MokoCRM demo instance
other	HTTP probe only (gitea, grafana, etc.)

Multiple Endpoints per Client

Each client can have multiple entries (live, dev, staging) sharing the same client label. Grafana dashboard dropdowns auto-populate from Prometheus labels.

---

Adding a New Client

Via MCP (after restart)

monitor_site_add(name, url, type, client, joomlaToken, akeebaSecret, tlsVerify)

Manual

1. Edit monitoring/sites.json — add site entries
2. Run monitoring/generate-targets.sh
3. Copy generated files to server:
   • generated/blackbox-http.json → /opt/.../monitoring/targets/
   • generated/blackbox-ssl.json → /opt/.../monitoring/targets/
   • generated/joomla-monitor.conf → /etc/joomla-monitor/sites.conf
4. Prometheus auto-discovers new targets within 5 minutes
5. joomla-monitor.sh picks up on next cron run (30 min)

Auto-Deploy with --deploy

monitoring/generate-targets.sh --deploy

The --deploy flag auto-pushes generated targets to the server AND creates/updates Grafana dashboards via the Grafana API. Dashboard UIDs are stable — they are derived from a hash of the client name, so re-running --deploy updates existing dashboards rather than creating duplicates.

---

Metrics Exposed

Blackbox Exporter (Prometheus)

Metric	Description
probe_success	1=site responded with 2xx, 0=failed
probe_http_status_code	HTTP status code
probe_http_duration_seconds	Response time by phase
probe_ssl_earliest_cert_expiry	SSL cert expiry timestamp

Joomla Monitor (textfile collector)

Metric	Description
joomla_site_api_reachable	1=API responds, 0=unreachable
joomla_site_online	1=online, 0=offline/maintenance
joomla_core_version_info	Info metric with version label (always 1)
joomla_core_version	Numeric version value (e.g. 6.01 for Joomla 6.1.0)
joomla_core_update_available	1=update exists, 0=current
joomla_extensions_total	Total installed extensions
joomla_extensions_enabled	Enabled extensions
joomla_extensions_disabled	Disabled extensions
joomla_backup_status	1=last backup complete, 0=other
joomla_backup_age_seconds	Seconds since last backup
joomla_backup_records_total	Number of backup records

Backup Monitoring

Backup status is collected via the Akeeba Backup JSON API v2:

Parameter	Value
Auth parameter	_akeebaAuth (not key)
Method parameter	method=listBackups (not action)
Endpoint	/index.php?option=com_akeebabackup&view=Api&format=raw
Config field	akeebaSecret in sites.json maps to the Akeeba Frontend Secret Word

---

Grafana Dashboard

Dashboard: MokoWaaS (UID: mokowaas) in the Endpoints folder.

Table Layout

Section	Columns
Site Health	Endpoint (clickable → front page), Online, Status, HTTP (→ Wikipedia), API, SSL days, Last Scrape
Joomla Core & Extensions	Endpoint (clickable → /administrator/), Version, System update, Ext Updates, Total, Enabled, Disabled
Backup Status	Endpoint (clickable → Akeeba Manage), Status (OK/FAILED), Age, Records
Performance	Response time chart (transfer + processing), Total duration gauge
Uptime History	30-day availability timeline

Alerting

<<<<<<< Updated upstream

Folder	Contents
Clients/	Per-client dashboards (auto-generated by generate-targets.sh --deploy)
Moko Server/	Infrastructure dashboards (provisioned from filesystem)

Dashboard Generation

generate-targets.sh generates Grafana dashboards automatically (one per client). Dashboard UIDs are stable (derived from a hash of the client name), so dashboards are updated in place on re-deploy. Use --deploy to auto-push to Grafana.

---

Files

File	Location	Purpose
sites.json	moko-platform/monitoring/	Central site definition
generate-targets.sh	moko-platform/monitoring/	Target + dashboard generator
joomla-monitor.sh	/usr/local/bin/ on Moko server	Joomla API metrics collector
joomla-monitor.sites.conf	/etc/joomla-monitor/sites.conf	Monitor site config (generated)
blackbox-http.json	/opt/.../monitoring/targets/	Prometheus file_sd targets
client-joomla-dashboard.json	Client template repo monitoring/grafana/	Dashboard template

Cron Jobs

Schedule	Script	Purpose
*/30 * * * *	joomla-monitor.sh	Query Joomla APIs, write .prom metrics

---

Related

• ARCHITECTURE -- Platform scripts architecture
• JOOMLA_SYNC -- Joomla extension sync between servers
• MCP-Servers -- MCP server fleet overview

---

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	joomla
Applies To	Joomla and Dolibarr client sites

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version

======= site-uptime-alert.sh runs every 5 minutes and sends to ntfy alert-critical when any mokowaas.* site goes DOWN, with a recovery notification when it comes back UP.

Stashed changes