MokoWaaS/docs/guides/configuration-guide.md

MokoWaaS Configuration Guide (VERSION: 02.01.08)

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. 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

10. 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.

11. 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.

12. 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

Revision History

Version	Date	Author	Description
01.02.00	2025-12-11	Jonathan Miller (@jmiller)	Initial standalone configuration guide created
02.01.08	2026-04-07	Jonathan Miller (@jmiller)	Full rewrite: WaaS access, visual branding, tenant restrictions, security, maintenance, action logs