MokoWaaS/docs/guides/configuration-guide.md

MokoWaaS Configuration Guide (VERSION: 02.01.22)

1. Objective

This guide outlines the configuration parameters available within the MokoWaaS system plugin and establishes recommended defaults for WaaS governed environments. Proper configuration ensures consistent branding behavior across templates, modules, and administrative surfaces.

2. Accessing Plugin Configuration

1. Log in to Joomla Administrator.
2. Navigate to System > Plugins.
3. Search for MokoWaaS.
4. Select the plugin name to open the configuration panel.

3. Plugin Parameters

3.1 Enable Branding

Property	Value
Field name	enable_branding
Type	Radio (Yes/No)
Default	Yes

Master switch for all branding overrides. When disabled, no language overrides are applied and the Joomla interface reverts to its default strings.

3.2 Brand Name

Property	Value
Field name	brand_name
Type	Text
Default	MokoWaaS

The brand name that replaces "Joomla" throughout the interface. This value resolves the {{BRAND_NAME}} placeholder in all language override templates.

Affected areas:

• Admin and site footer ("Powered by …")
• Control panel greetings
• Quick icon status messages
• System info and version labels
• Installer and update component text
• Error pages and system messages
• Privacy component headings

3.3 Company Name

Property	Value
Field name	company_name
Type	Text
Default	Moko Consulting

Your company name, used in support links and attribution. Resolves the {{COMPANY_NAME}} placeholder.

Affected areas:

• Admin login support links (forum, documentation, news)
• Frontend login support links

3.4 Support URL

Property	Value
Field name	support_url
Type	URL
Default	https://mokoconsulting.tech

URL for support and documentation links. Resolves the {{SUPPORT_URL}} placeholder.

Affected areas:

• Dashboard welcome message links
• Documentation and support links

4. How Overrides Work

MokoWaaS uses a two-layer override system:

4.1 Runtime Resolution (Primary)

On every page load, the plugin reads override template files shipped with the plugin, resolves {{BRAND_NAME}}, {{COMPANY_NAME}}, and {{SUPPORT_URL}} from plugin params, and injects the resolved strings into Joomla's Language object.

Effect: Changing the brand name in plugin config takes effect on the next page load — no reinstall needed.

4.2 Install-time Resolution (Fallback)

During install/update, the install script resolves placeholders and writes the result into Joomla's global language override files inside a sentinel block:

; ===== BEGIN MokoWaaS Overrides (do not edit this block) =====
; Auto-generated on 2026-04-07 — do not edit manually.
TPL_ATUM_POWERED_BY="Powered by MokoWaaS"
...
; ===== END MokoWaaS Overrides =====

Existing overrides outside this block are never touched. On uninstall, only the MokoWaaS block (and any legacy stray keys) are removed.

5. WaaS Access Control (fieldset: waas_access)

5.1 Enforce Master User

Property	Value
Field name	enforce_master_user
Type	Radio (Yes/No)
Default	Yes

Ensures a persistent super admin account exists. If deleted, blocked, or removed from the Super Users group, it is automatically restored on the next admin page load.

5.2 Master Username / Master Email

Field	Default
master_username	mokoconsulting
master_email	webmaster@mokoconsulting.tech

5.3 Emergency Access

Property	Value
Field name	emergency_access
Type	Radio (Yes/No)
Default	Yes

Two-factor emergency login using the database password from configuration.php:

1. Login with master username + DB password
2. Plugin creates /mokowaas-verify.php in site root
3. Delete the file via FTP/SSH
4. Login again — access granted

All attempts are logged to both the mokowaas log file and Joomla Action Logs (#__action_logs), including blocked IPs, wrong passwords, and file verification steps. Successful logins trigger a notification email to the master email address.

5.4 IP Whitelist Display

A live info panel shows:

• Number of IPs configured (or "Not configured" if empty)
• List of allowed IPs with "your IP" badge when matching
• Your current IP address
• Instructions for setting $mokowaas_allowed_ips in configuration.php

Important: Emergency access is blocked when no IPs are configured. An explicit whitelist is required.

6. Maintenance (fieldset: maintenance)

One-shot actions that execute when set to Yes and saved. Auto-reset to No after execution.

Field	Action
reset_hits	Sets all #__content.hits to zero
delete_versions	Purges all #__history records

Both actions are logged to the mokowaas log category.

7. Visual Branding (fieldset: visual_branding)

7.1 Shipped Media Assets

Logos and favicon are shipped in the plugin media folder (/media/plg_system_mokowaas/). Replace files to change:

File	Used for
logo.png	Atum sidebar (expanded) + login page logo
favicon_256.png	Atum sidebar (collapsed)
favicon.svg	Browser tab (modern browsers)
favicon.ico	Browser tab (legacy browsers)
favicon_256.png	Apple/Android touch icon

The plugin enforces Atum template style params (logoBrandLarge, logoBrandSmall, loginLogo) both at install time and on every admin request. All logo alt text is suppressed.

7.2 Color Scheme

Field	CSS Variable
color_primary	--atum-bg-dark, --template-bg-dark-80
color_sidebar	--atum-sidebar-bg, --template-bg-dark-70
color_header	--atum-bg-dark-90, --template-bg-dark-90
color_link	--template-link-color, --atum-link-color

7.3 Custom CSS

Property	Value
Field name	custom_css
Type	Textarea

Injected into admin pages via addStyleDeclaration(). </style> sequences are stripped for XSS prevention.

8. Tenant Restrictions (fieldset: tenant_restrictions)

All restrictions apply to non-master users only. The master user always has full access.

Field	Blocks
restrict_installer	Extensions > Install/Manage
hide_sysinfo	System > System Information
restrict_global_config	System > Global Configuration (component config still accessible)
restrict_template_editing	Template code editor (styles manager still accessible)
disable_install_url	Install from URL — blocks ALL users including master
hidden_menu_items	Components hidden from admin menu (one per line, e.g., com_installer)

Restricted components are automatically hidden from the admin menu via onPreprocessMenuItems.

9. Diagnostics & Monitoring (fieldset: diagnostics)

This fieldset configures a lightweight JSON health check endpoint designed for external monitoring systems such as Grafana. The endpoint follows patterns similar to Akeeba Panopticon, providing system diagnostics without requiring Joomla authentication.

9.1 Enable Health Endpoint

Property	Value
Field name	enable_health_endpoint
Type	Radio (Yes/No)
Default	No

Exposes a JSON health check endpoint at /?mokowaas=health. When enabled for the first time, a 64-character API token is automatically generated and stored in health_api_token. When disabled, the token is cleared.

9.2 Health API Token

Property	Value
Field name	health_api_token
Type	Text (read-only)
Default	(empty — auto-generated on enable)

The bearer token used to authenticate health check requests. This is a dedicated API key separate from Joomla user API tokens. Generated automatically using random_bytes(32) when the health endpoint is enabled.

Authentication methods (either works):

• HTTP header: Authorization: Bearer <token>
• Query parameter: ?mokowaas=health&token=<token>

9.3 Endpoint Behavior

URL: https://<site>/?mokowaas=health

The endpoint intercepts requests in onAfterInitialise(), before Joomla routing. This minimizes overhead for monitoring probes. HTTPS is always enforced (the enforceHttps() handler runs first).

HTTP responses:

• 200 — All checks pass or only degraded warnings
• 401 — Invalid or missing API token
• 503 — One or more checks report error status

9.4 Health Check Payload

The endpoint returns a JSON payload with the following structure:

{
  "status": "ok|degraded|error",
  "timestamp": "2026-05-21T12:00:00Z",
  "checks": {
    "database": {
      "status": "ok",
      "latency_ms": 5.12,
      "driver": "mysqli",
      "users": 3
    },
    "filesystem": {
      "status": "ok",
      "tmp_writable": true,
      "log_writable": true,
      "cache_writable": true,
      "free_disk_mb": 12345
    },
    "cache": {
      "status": "ok",
      "enabled": true,
      "handler": "file"
    },
    "extensions": {
      "status": "ok|degraded",
      "counts": { "plugin": 25, "component": 12 },
      "pending_updates": 0
    }
  },
  "meta": {
    "brand": "MokoWaaS",
    "plugin_version": "02.01.22",
    "joomla_version": "5.1.0",
    "php_version": "8.2.0",
    "server_name": "My Site",
    "server_time": "2026-05-21T12:00:00Z"
  }
}

Overall status logic:

• ok — All individual checks report ok
• degraded — At least one check is degraded (e.g., low disk space, pending updates)
• error — At least one check is error (e.g., database unreachable, unwritable directories)

9.5 Grafana URL

Property	Value
Field name	grafana_url
Type	URL
Default	(empty)

Base URL of the Grafana instance (e.g., https://grafana.mokoconsulting.tech). When provided together with an API key, the plugin auto-provisions an Infinity datasource and a MokoWaaS dashboard in Grafana.

9.6 Grafana API Key

Property	Value
Field name	grafana_api_key
Type	Text
Default	(empty)

A Grafana service account token or API key with at least Editor role. Required for the plugin to create/update datasources and dashboards via Grafana's REST API.

9.7 Auto-Provisioning Behavior

When the health endpoint is enabled and both Grafana URL and API key are set, saving the plugin config triggers automatic provisioning:

1. Datasource creation — An Infinity datasource (yesoreyeram-infinity-datasource) is created in Grafana, configured with the site URL and the health API bearer token. The datasource UID is deterministic: mokowaas-<md5(siteUrl)>.

2. Dashboard creation — A MokoWaaS dashboard is created with 14 panels across three rows:

   • Row 1 (Status Overview): Health Status (stat), DB Latency (gauge, ms), Free Disk Space (gauge, MB), Pending Updates (stat)
   • Row 2 (System Info): Joomla Version, PHP Version, Plugin Version, Cache Status
   • Row 3 (Detail): /tmp Writable, /logs Writable, /cache Writable, DB Driver, User Count, DB Status

3. Idempotent updates — Re-saving the plugin config updates the existing datasource and dashboard (PUT with overwrite: true). No duplicates are created.

4. Deprovisioning — When the health endpoint is disabled, both the datasource and dashboard are deleted from Grafana.

Prerequisites: The Grafana Infinity plugin must be installed on the Grafana instance. Install via: grafana cli plugins install yesoreyeram-infinity-datasource.

9.8 Manual Grafana Setup (Alternative)

If auto-provisioning is not desired (leave Grafana URL and API key empty), you can set up Grafana manually:

1. Enable the health endpoint — a token is generated automatically.
2. In Grafana, add an Infinity datasource pointing to the site URL.
3. Set the Authorization: Bearer <token> header.
4. Create panels querying /?mokowaas=health and extracting values from the JSON paths documented in section 9.4.

10. Security Hardening (fieldset: security)

Field	Default	Description
force_https	No	301 redirect HTTP → HTTPS (supports reverse proxy via X-Forwarded-Proto)
admin_session_timeout	0	Minutes of idle time before admin session expires (0 = Joomla default). Master user is exempt.
password_min_length	12	Minimum password characters
password_require_uppercase	Yes	At least one uppercase letter
password_require_number	Yes	At least one digit
password_require_special	Yes	At least one special character
upload_allowed_types	jpg,jpeg,png,gif,webp,svg,pdf,doc,docx,xls,xlsx	Comma-separated allowed extensions
upload_max_size_mb	10	Maximum upload size in MB

11. Configuration Change Workflow

1. Document the change request.
2. Apply updates in a staging environment.
3. Validate branding, restrictions, and security settings.
4. Promote changes to production following WaaS change controls.

12. Troubleshooting

• Branding not appearing: Clear Joomla and browser cache. Verify enable_branding is Yes.
• Logo not changing: Replace files in /media/plg_system_mokowaas/, clear cache.
• Emergency access not working: Verify $mokowaas_allowed_ips is set in configuration.php and includes your IP.
• Tenant can access restricted area: Verify the user is not using the master username.
• Password rejected: Check password policy settings — all rules must pass.
• Health endpoint returns 401: Verify the API token matches. Regenerate by disabling then re-enabling the health endpoint.
• Health endpoint not responding: Confirm enable_health_endpoint is Yes and the URL includes ?mokowaas=health.

13. Validation Checklist

• Brand name appears consistently across all admin screens
• Company name appears in login support links
• Support URL points to correct destination
• Login support URLs point to mokoconsulting.tech/support, /kb, /news
• Atum logo shows custom logo.png in sidebar and login page
• Favicon shows custom icon in browser tab
• No "Joomla" identifiers remain in overridden locations
• Master user has full access to all restricted areas
• Non-master users are blocked from restricted components
• Emergency access works with correct IP + DB password + file verification
• Emergency access attempts visible in System > Action Logs
• Existing site language overrides are preserved
• Health endpoint returns 200 with valid token and 401 without
• Grafana datasource successfully polls the health endpoint

Revision History

Version	Date	Author	Description
01.02.00	2025-12-11	Jonathan Miller (@jmiller-moko)	Initial standalone configuration guide created
02.01.08	2026-04-07	Jonathan Miller (@jmiller-moko)	Full rewrite: WaaS access, visual branding, tenant restrictions, security, maintenance, action logs
02.01.22	2026-05-21	Claude Code (@claude-code)	Added Diagnostics & Monitoring fieldset: health endpoint, auto-token generation, Grafana integration