docs: update README from wiki Home

2026-05-10 18:39:21 +00:00
parent 8d8dfe5b28
commit 16ebfabd4e
1 changed files with 78 additions and 350 deletions
@@ -1,357 +1,85 @@
-<!--
- Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+# MokoWaaS

- This file is part of a Moko Consulting project.
+MokoWaaS is a Joomla 5.x / 6.x system plugin that provides a configurable white-label identity layer for the MokoWaaS platform.

- SPDX-LICENSE-IDENTIFIER: GPL-3.0-or-later
+![Language](https://img.shields.io/badge/Markdown-000000?style=flat-square&logo=markdown&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Wiki](https://img.shields.io/badge/wiki-MokoWaaS-blue?style=flat-square)

- This program is free software; you can redistribute it and modify it under the terms of the GNU General Public License version 3 or later.

- This program is distributed in the hope that it will be useful but without warranty.
-
- You should have received a copy of the GNU General Public License in LICENSE.md.
-
- # FILE INFORMATION
- DEFGROUP: Joomla.Plugin
- INGROUP: MokoWaaS
- REPO: https://github.com/mokoconsulting-tech/mokowaas
- VERSION: 02.01.24
- PATH: /README.md
- BRIEF: Rebranding plugin for MokoWaaS platform
- NOTE: Internal WaaS identity abstraction layer
-->
-
-# 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)*