# 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](https://git.mokoconsulting.tech/MokoConsulting/MokoSuite/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](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.