MokoWaaS/docs/guides/operations-guide.md

MokoWaaS Operations Guide (VERSION: 02.01.22)

Introduction

The MokoWaaS Operations Guide defines how the plugin is managed across WaaS governed Joomla environments. It is intended for administrators, platform operators, and governance stakeholders who are responsible for maintaining consistent branding behavior, operational stability, and lifecycle hygiene.

This document focuses on day to day responsibilities, monitoring expectations, and coordination points with other parts of the WaaS platform.

Operational Scope

The MokoWaaS plugin operates as a system level extension that enforces WaaS branding, terminology, and identity across administrative user interfaces. Because it runs early in the request lifecycle, it requires explicit operational oversight to ensure:

• Consistent behavior after template or core updates
• Stable interaction with other system plugins
• Alignment with WaaS branding policy and governance

Roles and Responsibilities

WaaS Platform Administrators

• Maintain the plugin at the approved version for each environment
• Validate branding consistency following platform or template changes
• Coordinate with development teams on rollout of new features or terminology

Governance and Brand Owners

• Approve changes to WaaS terminology or visible branding
• Review that the plugin’s behavior aligns with documented brand guidelines
• Provide input for configuration changes that affect end user perception

Development and Release Teams

• Implement and test changes to the plugin
• Prepare release artifacts and update documentation
• Coordinate rollout sequencing with templates, modules, and language packs

Routine Operational Tasks

Branding Consistency Reviews

Performed when:

• Joomla core is updated
• Templates or overrides change
• Language packs are updated or replaced

Administrators should verify that:

• Branding remains consistent across key administrator views
• No reverted or legacy Joomla labels reappear

Cache Management

To avoid stale UI output:

• Clear Joomla cache after plugin updates
• Clear CDN or reverse proxy cache where applicable
• Encourage administrators to hard refresh their browsers after major changes

Change Logging

For each operational change involving the plugin:

• Record the change type (configuration, version, dependency)
• Record the timestamp and operator
• Capture any observed side effects during or after the change

Monitoring and Alerts

Operational logging and monitoring should focus on:

• Plugin initialization or load order errors
• Warnings related to language strings or missing constants
• UI rendering anomalies reported by administrators
• Health endpoint status changes (degraded/error transitions)

Recommended monitoring sources:

• Joomla Administrator logs
• Web server and PHP error logs
• Centralized WaaS logging and observability tools where available
• Grafana — via the MokoWaaS health endpoint (see below)

Grafana Health Endpoint Integration

MokoWaaS provides a built-in health check endpoint at /?mokowaas=health for integration with Grafana or similar monitoring platforms. This follows the Akeeba Panopticon pattern of exposing system diagnostics via a lightweight, token-authenticated JSON API.

Automatic setup:

1. Enable the health endpoint in plugin config — a unique API token is auto-generated.
2. Enter your Grafana URL and API key (service account token with Editor role).
3. Save the plugin — the datasource and a 14-panel dashboard are auto-provisioned in Grafana.
4. Configure alerting rules on status transitions to degraded or error.

Manual setup (if auto-provisioning is not used):

1. Enable the health endpoint and copy the generated token.
2. In Grafana, install the Infinity datasource plugin and create a datasource pointing to the site URL.
3. Set the Authorization: Bearer <token> header.
4. Build dashboard panels from the structured JSON response.

Operational considerations:

• The health endpoint bypasses Joomla routing and sessions — minimal server overhead per poll.
• HTTPS is always enforced on health requests.
• The API token is independent of Joomla user accounts — it does not expire with sessions.
• Token regeneration: disable then re-enable the health endpoint in plugin config.
• If the endpoint returns 503, at least one system check has failed — investigate immediately.

Maintenance Lifecycle

Scheduled Maintenance

During planned maintenance windows:

• Validate that branding and terminology still match WaaS standards
• Confirm that newly deployed templates or components do not conflict with plugin output
• Review configuration settings to ensure they align with current policy

Emergency Maintenance

If the plugin negatively affects platform stability or administrator usability:

1. Temporarily disable the plugin in the Joomla Plugin Manager.
2. Clear Joomla and application caches.
3. Validate that core navigation and access remain functional.
4. Engage development or governance teams to determine remediation steps.

Dependency and Compatibility Considerations

• Template overrides may change how or where branding appears.
• Joomla updates may introduce new strings that require plugin or language updates.
• Third party system plugins may alter the same UI surfaces and require coordination.

Administrators should factor these dependencies into maintenance and upgrade planning.

Revision History

Date	Author	Description
2025-12-11	Jonathan Miller (@jmiller-moko)	Rewrite for version 01.03.00
2026-05-21	Claude Code (@claude-code)	Added Grafana health endpoint monitoring section for 02.01.22