From 16ebfabd4e7bd6ab4d488a8f2b957093925ea16c Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Sun, 10 May 2026 18:39:21 +0000 Subject: [PATCH] docs: update README from wiki Home --- README.md | 428 ++++++++++-------------------------------------------- 1 file changed, 78 insertions(+), 350 deletions(-) diff --git a/README.md b/README.md index feedae0..04eb0ee 100644 --- a/README.md +++ b/README.md @@ -1,357 +1,85 @@ - - -# MokoWaaS Plugin - -[![Version](https://img.shields.io/badge/version-02.01.18-blue.svg?logo=v&logoColor=white)](https://github.com/mokoconsulting-tech/MokoWaaS/releases/tag/v02) -[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green.svg?logo=gnu&logoColor=white)](LICENSE) -[![Joomla](https://img.shields.io/badge/Joomla-5.x%20%7C%206.x-red.svg?logo=joomla&logoColor=white)](https://www.joomla.org) -[![PHP](https://img.shields.io/badge/PHP-8.1%2B-777BB4.svg?logo=php&logoColor=white)](https://www.php.net) - -MokoWaaS is a Joomla 5.x / 6.x system plugin that provides a configurable white-label identity layer for the MokoWaaS platform. It replaces all visible Joomla branding with your own brand name, company name, and support URLs — configurable from the plugin admin without code changes. - -## Table of Contents - -- [Overview](#overview) -- [Features](#features) -- [System Requirements](#system-requirements) -- [Installation](#installation) -- [Usage](#usage) -- [Configuration](#configuration) -- [Technical Implementation](#technical-implementation) -- [Repository Structure](#repository-structure) -- [Development](#development) -- [Documentation](#documentation) -- [Support](#support) -- [License](#license) -- [Changelog](#changelog) - -## Overview - -The MokoWaaS plugin operationalizes a unified naming convention, brand-controlled visuals, and enforced terminology across all tenant sites. This ensures consistent service delivery within the WaaS (Website as a Service) framework by abstracting all upstream Joomla identifiers behind MokoWaaS-compliant terminology. - -## Features - -- **Template-Based Overrides**: 50+ language keys with `{{BRAND_NAME}}`, `{{COMPANY_NAME}}`, `{{SUPPORT_URL}}` placeholders -- **Configurable Brand**: Change brand name, company, and support URL from plugin config — takes effect immediately -- **Safe Override Merging**: Sentinel-block pattern preserves existing site overrides during install/update -- **Clean Uninstall**: Only MokoWaaS keys are removed; all other overrides are preserved -- **Joomla 5.x / 6.x Compatible**: Built using modern Joomla plugin architecture with dependency injection -- **Multi-Language Support**: en-GB and en-US locales -- **Admin & Frontend Coverage**: Dashboard, footer, login, installer, system info, update component, error pages, and more -- **Governance Compliant**: Aligned with [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards) - -## System Requirements - -- **Joomla**: 5.0+ or 6.x -- **PHP**: 8.1 or higher (8.3+ for Joomla 6) -- **Extensions**: Standard Joomla PHP extensions -- **Permissions**: Write access to language override directories - -## Installation - -### Method 1: Via Joomla Extension Manager (Recommended) - -1. Download the latest release package from the releases page -2. Log into your Joomla Administrator panel -3. Navigate to **System → Extensions → Install** -4. Click **Upload Package File** -5. Select the downloaded `.zip` file -6. Click **Upload & Install** -7. Navigate to **System → Plugins** -8. Search for "MokoWaaS Brand" -9. Enable the plugin -10. Clear Joomla cache - -### Method 2: Manual Installation - -1. Extract the plugin package -2. Upload contents to your Joomla installation's `/tmp` directory -3. Install via Joomla Extension Manager → Install from Folder -4. Enable the plugin as described above - -### Post-Installation - -After installation, verify the branding is active: -- Check the administrator footer for "Powered by MokoWaaS" -- Verify the control panel shows "Welcome to MokoWaaS!" -- Clear browser cache if branding doesn't appear immediately - -### Automatic Updates - -This plugin supports Joomla's automatic update system. Once installed: - -1. Navigate to **System → Update → Extensions** -2. The plugin will automatically check for updates from the MokoWaaS update server -3. When a new version is available, it will appear in the update list -4. Click **Update** to install the latest version - -The update server URL is configured in the plugin manifest and points to: -``` -https://raw.githubusercontent.com/mokoconsulting-tech/MokoWaaS/main/updates.xml -``` - -Updates are published automatically when new releases are created through the GitHub release workflow. - -## Usage - -Once installed and enabled, the plugin automatically replaces Joomla branding with your configured values. No code changes needed. - -### Changing the Brand Name - -1. Navigate to **System → Plugins → System - MokoWaaS** -2. Set **Brand Name** to your desired name (e.g., "MyPlatform") -3. Set **Company Name** to your company (e.g., "My Company Inc.") -4. Set **Support URL** to your support site (e.g., "https://support.mycompany.com") -5. Click **Save & Close** -6. The new branding appears immediately across admin and frontend - -### What Gets Rebranded - -| Area | Example | -| ---- | ------- | -| Admin footer | "Powered by [YourBrand](https://your-url)" | -| Dashboard | "Welcome to YourBrand!" | -| Quick Icons | "YourBrand is up to date." | -| System Info | "YourBrand Version" | -| Login page | "YourBrand Administrator Login" | -| Update component | "YourBrand Update" | -| Frontend footer | "Powered by [YourBrand](https://your-url)" | -| Error pages | No Joomla references | - -## Configuration - -The plugin provides the following configuration options accessible through **System → Plugins → System - MokoWaaS**: - -### Parameters - -| Parameter | Type | Default | Description | -| --------- | ---- | ------- | ----------- | -| Enable Branding | Yes/No | Yes | Master toggle for all branding overrides | -| Brand Name | Text | MokoWaaS | Replaces "Joomla" throughout the interface | -| Company Name | Text | Moko Consulting | Used in support/attribution links | -| Support URL | URL | https://mokoconsulting.tech | Destination for help and documentation links | - -See the [Configuration Guide](docs/guides/configuration-guide.md) for detailed documentation on how overrides work. - -## Technical Implementation - -### Architecture - -The plugin follows Joomla 5.x system plugin architecture: - -``` -PlgSystemMokoWaaS -├── Event Handlers -│ ├── onAfterInitialise - Framework initialization hook -│ └── onAfterRoute - Route determination hook -├── Dependency Injection -│ └── ServiceProvider - DI container registration -└── Language Integration - └── Native Override System - Joomla's built-in override mechanism -``` - -### Core Components - -1. **mokowaas.php** - - Main plugin class extending `CMSPlugin` - - Implements system event handlers - - Namespace: `Moko\Plugin\System\MokoWaaS` - -2. **mokowaas.xml** - - Plugin manifest defining metadata and structure - - Joomla 5.x namespace configuration - - File and folder definitions - -3. **services/provider.php** - - Dependency injection service provider - - Registers plugin with Joomla's DI container - - Joomla 5.x compatibility layer - -4. **language/en-GB/** - - Plugin-specific language strings - - Installation and configuration UI text - -5. **language/overrides/** - - Frontend language override files - - Replaces Joomla terminology with MokoWaaS branding - -6. **administrator/language/overrides/** - - Administrator language override files - - Backend-specific branding replacements - -### Language Override Integration - -The plugin leverages Joomla's native language override system rather than programmatically loading strings. Language override files are placed in standard Joomla locations: - -- Frontend: `language/overrides/{locale}.override.ini` -- Administrator: `administrator/language/overrides/{locale}.override.ini` - -Joomla automatically loads these overrides during initialization, ensuring optimal performance and compatibility. - -## Repository Structure - -``` -mokowaas/ -├── src/ # Plugin source files -│ ├── mokowaas.php # Main plugin class -│ ├── mokowaas.xml # Plugin manifest -│ ├── services/ -│ │ └── provider.php # DI service provider -│ ├── language/ -│ │ ├── en-GB/ # Plugin language files -│ │ └── overrides/ # Frontend language overrides -│ └── administrator/ -│ └── language/ -│ └── overrides/ # Admin language overrides -├── docs/ # Documentation -│ ├── index.md # Documentation index -│ ├── plugin-basic.md # Plugin overview -│ ├── guides/ # Operational guides -│ └── reference/ # Reference materials -├── scripts/ # Build and validation scripts -│ ├── validate_manifest.sh -│ ├── verify_changelog.sh -│ └── update_changelog.sh -├── .github/ # GitHub workflows -│ └── workflows/ -│ ├── build.yml -│ ├── ci.yml -│ └── release_from_version.yml -├── CHANGELOG.md # Version history -├── README.md # This file -├── LICENSE.md # GPL-3.0-or-later license -├── CONTRIBUTING.md # Contribution guidelines -└── CODE_OF_CONDUCT.md # Community guidelines -``` - -## Development - -### Building the Plugin - -Build the installable plugin package from source: - -```bash -cd src -zip -r ../mokowaas_v01.04.00.zip . -x "*.git*" -``` - -### Running Validation Scripts - -```bash -# Validate plugin manifest -./scripts/validate_manifest.sh - -# Verify changelog format -./scripts/verify_changelog.sh -``` - -### PHP Syntax Validation - -```bash -cd src -find . -name "*.php" -exec php -l {} \; -``` - -### Automated Build via GitHub Actions - -The repository includes automated workflows: - -- **build.yml**: Creates ZIP package on release -- **ci.yml**: Runs validation checks on pull requests -- **release_from_version.yml**: Automates release process - -## Documentation - -Comprehensive documentation is available in the `/docs` directory: - -- **[Plugin Overview](docs/plugin-basic.md)**: Detailed plugin documentation -- **[Installation Guide](docs/guides/installation-guide.md)**: Step-by-step installation -- **[Build Guide](docs/guides/build-guide.md)**: Building and packaging -- **[Configuration Guide](docs/guides/configuration-guide.md)**: Configuration options -- **[Operations Guide](docs/guides/operations-guide.md)**: Operational procedures -- **[Troubleshooting Guide](docs/guides/troubleshooting-guide.md)**: Common issues - -All documentation follows the [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards) documentation framework. - -## Support - -### Getting Help - -- **Documentation**: Check the `/docs` directory for detailed guides -- **Issues**: Submit issues through the GitHub issue tracker -- **Service Support**: For operational issues, submit a ticket through the Moko Consulting service channel - -### Reporting Issues - -When reporting issues, include: -- Joomla version -- PHP version -- Plugin version -- Steps to reproduce -- Expected vs actual behavior -- Relevant error messages or logs - -## License - -This project is licensed under the GNU General Public License version 3 or later (GPL-3.0-or-later). - -See [LICENSE.md](LICENSE.md) for the full license text. - -## Versioning - -This extension follows the [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards) version governance model using semantic versioning: `MAJOR.MINOR.PATCH` - -Current version: **02.01.18** - -## Changelog - -See [CHANGELOG.md](CHANGELOG.md) for a complete version history. - -### Recent Changes (v02.01.18 - 2026-04-23) - -- Always install and lock MokoOnyx template on install/update -- Always unlock MokoCassiopeia on install/update (allow uninstall) -- Bundle MokoOnyx payload (replaces MokoCassiopeia payload) -- Update payload workflow to fetch MokoOnyx from Gitea releases - -## Contributing - -We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on: - -- Code of conduct -- Development workflow -- Coding standards -- Pull request process -- Documentation requirements - -## Acknowledgments - -- Built for the MokoWaaS platform -- Follows [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards) -- Designed for Joomla 5.x architecture -- Maintained by Moko Consulting +Joomla system plugin that powers the Moko Consulting Web-as-a-Service platform -- multi-tenant site management, branding injection, and automated client provisioning. --- -**Moko Consulting** | [Website](https://mokoconsulting.tech) | [Email](mailto:hello@mokoconsulting.tech) +| | | +|---|---| +| **Type** | Joomla System Plugin | +| **Language** | PHP | +| **Joomla** | 5.x | +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS) (primary) | + +--- + +## Overview + +MokoWaaS is the core plugin that transforms a standard Joomla installation into a managed WaaS platform. It handles client site configuration, branding, update management, and integrates with the MokoStandards ecosystem for automated deployment and governance. + +--- + +## Wiki Pages + +### Guides + +| Page | Description | +|------|-------------| +| [Installation Guide](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/guides-installation-guide) | Prerequisites, Joomla setup, plugin installation | +| [Configuration Guide](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/guides-configuration-guide) | Plugin parameters, client site settings | +| [Build Guide](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/guides-build-guide) | Building the installable package | +| [Operations Guide](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/guides-operations-guide) | Day-to-day management and maintenance | +| [Testing Guide](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/guides-testing-guide) | Testing procedures and validation | +| [Upgrade and Versioning Guide](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/guides-upgrade-and-versioning-guide) | Version management and upgrade paths | +| [Rollback and Recovery Guide](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/guides-rollback-and-recovery-guide) | Disaster recovery and rollback procedures | +| [Troubleshooting Guide](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/guides-troubleshooting-guide) | Common issues and solutions | + +### Reference + +- [Plugin Overview](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/reference-plugin-overview) -- architecture, event hooks, feature map +- [Plugin Basic](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/plugin-basic) -- plugin structure and manifest +- [Update Server](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki/update-server) -- Joomla update server configuration + +--- + +## Related Wikis + +| Repo | Purpose | +|------|---------| +| [Template-Client-WaaS](https://git.mokoconsulting.tech/MokoConsulting/Template-Client-WaaS/wiki) | Client site template (paired with MokoWaaS) | +| [MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/wiki) | Joomla admin template | +| [joomla-api-mcp](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki) | Joomla Web Services API MCP | +| [deploy-mcp](https://git.mokoconsulting.tech/MokoConsulting/deploy-mcp/wiki) | Git-based deployment MCP | +| [backup-mcp](https://git.mokoconsulting.tech/MokoConsulting/backup-mcp/wiki) | Backup MCP with Akeeba integration | + +--- + +> **[MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki)** -- central standards hub for all Moko Consulting projects. + +--- + + + +--- + +## Documentation + +Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki). + +## Contributing + +See the wiki for development guidelines and contribution instructions. + +## License + +This project is licensed under the GNU General Public License v3.0 or later -- see the [LICENSE](LICENSE) file. + +--- + +*[Moko Consulting](https://mokoconsulting.tech) -- [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*