MokoSuite/wiki/installation.md

Installation

MokoSuite is distributed as a Joomla package (pkg_mokosuite) containing three extensions. It can be installed via the standard Joomla Extension Manager.

Requirements

Requirement	Minimum
Joomla	5.0.0+
PHP	8.1.0+

The installer checks both requirements during preflight and aborts with an error message if either is not met.

Method 1: Upload Package File

1. Download the latest pkg_mokosuite.zip from the Gitea Releases page.
2. In Joomla admin, navigate to System > Install > Extensions.
3. On the Upload Package File tab, drag and drop or browse to select pkg_mokosuite.zip.
4. Click Upload & Install.
5. Verify the success message. The package installs three extensions:
   • plg_system_mokosuite (System Plugin)
   • com_mokosuite (Component)
   • plg_webservices_mokosuite (Webservices Plugin)

Method 2: Install from URL

1. In Joomla admin, navigate to System > Install > Extensions.
2. On the Install from URL tab, enter the direct download URL for the package ZIP, e.g.:

   https://git.mokoconsulting.tech/MokoConsulting/MokoSuite/releases/download/stable/pkg_mokosuite-latest.zip
   

3. Click Install.
4. Verify the success message.

Post-Installation Verification

After installation, verify the following:

1. Plugin enabled: Navigate to System > Plugins and confirm "System - MokoSuite" is enabled (it is auto-enabled during installation).
2. Health token generated: Open the plugin configuration and check the Diagnostics tab. The health_api_token field should contain an auto-generated token.
3. Branding applied: The admin login page and dashboard should reflect MokoSuite branding (logo, colors, footer text).
4. Health endpoint: Test the health endpoint:

   curl -sk -H "Authorization: Bearer <token>" "https://yoursite.com/?mokosuite=health"
   

5. Grafana heartbeat: Check the admin message queue for a Grafana heartbeat confirmation message.

What the Installer Does

During postflight, the installer script performs these operations:

Step	Description
Enable and protect plugin	Sets enabled=1, protected=1, locked=0 in #__extensions
Install MokoOnyx template	Installs the bundled MokoOnyx site template from the plugin payload, sets it as default
Language overrides	Deploys language override files for en-GB and en-US
Login support URLs	Updates mod_loginsupport to point to Moko Consulting support/docs/news URLs
Atum branding	Applies brand colors to the Atum admin template
Action log registration	Registers MokoSuite in the Joomla action log system
Health token provisioning	Generates a random API token if one does not exist
Heartbeat	Sends a registration heartbeat to the Grafana monitoring receiver

Automatic Updates

MokoSuite includes an update server configuration that enables automatic update notifications through Joomla's built-in update system.

The update server URL is:

https://git.mokoconsulting.tech/MokoConsulting/MokoSuite/raw/branch/main/updates.xml

When a new version is available:

1. Joomla's update checker detects the new version from updates.xml.
2. A notification appears in the admin dashboard.
3. Navigate to System > Update > Extensions to install the update.
4. The postflight script runs again, re-applying all configuration steps.

Upgrading from Standalone Plugin to Package

If you previously installed the standalone plg_system_mokosuite plugin (before it was packaged as pkg_mokosuite), the package installer handles migration automatically:

1. Install the pkg_mokosuite.zip package using either method above.
2. The package installer detects the existing standalone plugin and upgrades it in place.
3. The additional extensions (com_mokosuite, plg_webservices_mokosuite) are installed alongside.
4. All existing plugin settings are preserved.
5. The protected flag is set on all package extensions.

No manual cleanup of the old standalone plugin is required.

Uninstallation

Uninstallation is restricted to the master user. See Plugin Protection for details.

When the master user uninstalls via the Extension Manager:

1. Language override files are removed from Joomla's global override directories.
2. Action log registration is cleaned up.
3. An uninstall notification is sent to the monitoring system.
4. The package and all sub-extensions are removed.