MokoConsulting/wiki
Archived
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

docs: sync wikis from Gitea (2026-05-09 23:43 UTC)

Browse Source
This commit is contained in:
gitea-actions[bot]
2026-05-09 18:43:11 -05:00
parent 5613563b84
commit 57eda6a062
16 changed files with 2242 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
MokoOnyx/CSS-Variables.-.md
+226
View File
@@ -0,0 +1,226 @@
[← Back to Home](Home)
# CSS Variables Reference
All CSS variables are defined in the theme palette files (`light.standard.css` / `dark.standard.css`) under `:root[data-bs-theme="light"]` or `:root[data-bs-theme="dark"]`. Override any of these in your [custom theme](Custom-Themes) files.
---
## Brand and Theme Colors
| Variable | Light Default | Dark Default | Description |
|----------|--------------|-------------|-------------|
| `--color-primary` | `#112855` | `#112855` | Primary brand colour |
| `--accent-color-primary` | `#3f8ff0` | `#3f8ff0` | Primary accent colour |
| `--accent-color-secondary` | `#6fb3ff` | `#6fb3ff` | Secondary accent colour |
## Typography and Body
| Variable | Light Default | Dark Default | Description |
|----------|--------------|-------------|-------------|
| `--body-font-family` | System sans-serif stack | System sans-serif stack | Base font family |
| `--body-font-size` | `1rem` | `1rem` | Base font size |
| `--body-font-weight` | `400` | `400` | Base font weight |
| `--body-line-height` | `1.5` | `1.5` | Base line height |
| `--body-color` | `#22262a` | `#e6ebf1` | Body text colour |
| `--body-bg` | `#fff` | `#0e1318` | Body background colour |
| `--heading-color` | `inherit` | `#f1f5f9` | Heading text colour |
| `--emphasis-color` | `#000` | `#fff` | Emphasis text colour |
| `--secondary-color` | `#22262abf` | `#e6ebf1bf` | Secondary text colour |
| `--tertiary-color` | `#22262a80` | `#e6ebf180` | Tertiary text colour |
| `--muted-color` | `#6d757e` | `#6d757e` | Muted text colour |
| `--highlight-color` | `#22262a` | `#111` | Highlight text colour |
| `--highlight-bg` | `#fbeea8` | `#ffe28a1a` | Highlight background |
## Standard Colors
| Variable | Light Default | Dark Default |
|----------|--------------|-------------|
| `--blue` | `#010156` | `#91a4ff` |
| `--indigo` | `#6812f3` | `#b19cff` |
| `--purple` | `#6f42c2` | `#c0a5ff` |
| `--pink` | `#e93f8e` | `#ff8fc0` |
| `--red` | `#a51f18` | `#ff7a73` |
| `--orange` | `#fd7e17` | `#ff9c4d` |
| `--yellow` | `#ad6200` | `#ffd166` |
| `--green` | `#448344` | `#78d694` |
| `--teal` | `#5abfdd` | `#76e3ff` |
| `--cyan` | `#30638d` | `#6fb7ff` |
## Gray Scale
| Variable | Light Default | Dark Default |
|----------|--------------|-------------|
| `--gray-100` | `#f9fafb` | `#161a20` |
| `--gray-200` | `#eaedf0` | `#1b2027` |
| `--gray-300` | `#dfe3e7` | `#222831` |
| `--gray-400` | `#ced4da` | `#2b323b` |
| `--gray-500` | `#adb5bd` | `#36404a` |
| `--gray-600` | `#6d757e` | `#48525d` |
| `--gray-700` | `#484f56` | `#5b6672` |
| `--gray-800` | `#353b41` | `#cfd6de` |
| `--gray-900` | `#22262a` | `#e6ebf1` |
## Links
| Variable | Light Default | Dark Default | Description |
|----------|--------------|-------------|-------------|
| `--color-link` | `#224FAA` | `white` | Navigation link colour |
| `--color-hover` | `var(--accent-color-primary)` | `gray` | Navigation hover colour |
| `--link-color` | `#224faa` | `#8ab4f8` | Content link colour |
| `--link-hover-color` | `#424077` | `#c3d6ff` | Content link hover colour |
| `--link-decoration` | `underline` | `underline` | Link text decoration |
## Navigation
| Variable | Light Default | Dark Default | Description |
|----------|--------------|-------------|-------------|
| `--mainmenu-nav-link-color` | `white` | `#fff` | Main menu active link colour |
| `--nav-text-color` | `white` | `gray` | Navigation text colour |
| `--nav-bg-color` | `var(--color-link)` | `var(--color-primary)` | Navigation background colour |
## Layout and Spacing
| Variable | Light Default | Dark Default | Description |
|----------|--------------|-------------|-------------|
| `--padding-x` | `0.15rem` | `0.15rem` | Horizontal padding |
| `--padding-y` | `0.15rem` | `0.15rem` | Vertical padding |
| `--secondary-bg` | `#eaedf0` | `#151b22` | Secondary background |
| `--tertiary-bg` | `#f9fafb` | `#10151b` | Tertiary background |
| `--nav-toggle-size` | `3rem` | `3rem` | Mobile nav toggle size |
## Breakpoints
| Variable | Value | Description |
|----------|-------|-------------|
| `--bp-xs` | `0` | Extra small |
| `--bp-sm` | `576px` | Small |
| `--bp-md` | `768px` | Medium |
| `--bp-lg` | `992px` | Large |
| `--bp-xl` | `1200px` | Extra large |
## Borders
| Variable | Light Default | Dark Default |
|----------|--------------|-------------|
| `--border-width` | `1px` | `1px` |
| `--border-style` | `solid` | `solid` |
| `--border-color` | `#dfe3e7` | `#2b323b` |
| `--border-radius` | `.25rem` | `.25rem` |
| `--border-radius-sm` | `.2rem` | `.2rem` |
| `--border-radius-lg` | `.3rem` | `.3rem` |
| `--border-radius-pill` | `50rem` | `50rem` |
## Shadows
| Variable | Light Default | Dark Default |
|----------|--------------|-------------|
| `--box-shadow` | `0 .5rem 1rem #00000026` | `0 .5rem 1rem #00000066` |
| `--box-shadow-sm` | `0 .125rem .25rem #00000013` | `0 .125rem .25rem #00000040` |
| `--box-shadow-lg` | `0 1rem 3rem #0000002d` | `0 1rem 3rem #00000080` |
## Header Background
| Variable | Light Default | Dark Default | Description |
|----------|--------------|-------------|-------------|
| `--header-background-color` | `#adadad` | `#1a1f2b` | Header fallback colour |
| `--header-background-image` | `url(.../bg.svg)` | `url(.../bg.svg)` | Header background image |
| `--header-background-attachment` | `fixed` | `fixed` | CSS attachment |
| `--header-background-repeat` | `repeat` | `repeat` | CSS repeat |
## Container Backgrounds
Each container position (below-topbar, top-a, top-b, sidebar, bottom-a, bottom-b) has these variables:
| Variable Pattern | Description |
|-----------------|-------------|
| `--container-{position}-bg-image` | Background image (default: `none`) |
| `--container-{position}-bg-color` | Background colour (default: `transparent`) |
| `--container-{position}-bg-position` | Background position |
| `--container-{position}-bg-attachment` | Background attachment |
| `--container-{position}-bg-repeat` | Background repeat |
| `--container-{position}-bg-size` | Background size |
| `--container-{position}-border` | Border style |
| `--container-{position}-border-radius` | Border radius |
## Forms
| Variable | Light Default | Dark Default |
|----------|--------------|-------------|
| `--input-color` | `hsl(210, 11%, 15%)` | `#e6ebf1` |
| `--input-bg` | `hsl(210, 20%, 98%)` | `#1a2332` |
| `--input-border-color` | `hsl(210, 14%, 83%)` | `#3a4250` |
| `--input-focus-border-color` | `#8894aa` | `#5472ff` |
| `--form-valid-color` | `#448344` | `#78d694` |
| `--form-invalid-color` | `#a51f18` | `#ff8e86` |
## Bootstrap Palette
| Variable | Light Default | Dark Default |
|----------|--------------|-------------|
| `--primary` | `#010156` | `#010156` |
| `--secondary` | `#6d757e` | `#48525d` |
| `--success` | `#448344` | `#4aa664` |
| `--info` | `#30638d` | `#4f7aa0` |
| `--warning` | `#ad6200` | `#c77a00` |
| `--danger` | `#a51f18` | `#c23a31` |
| `--light` | `#f9fafb` | `#1b2027` |
| `--dark` | `#353b41` | `#0f1318` |
Each palette colour also has `-rgb`, `-text-emphasis`, `-bg-subtle`, and `-border-subtle` variants.
## Hero / Banner
| Variable | Description |
|----------|-------------|
| `--hero-height` | Banner height (default: `60vh`) |
| `--hero-color` | Banner text colour |
| `--hero-bg-repeat` | Background repeat |
| `--hero-bg-attachment` | Background attachment |
| `--hero-bg-position` | Background position |
| `--hero-bg-size` | Background size |
| `--hero-overlay-bg` | Overlay background colour |
| `--hero-primary-bg-color` | Primary variant background |
| `--hero-primary-overlay` | Primary variant overlay gradient |
| `--hero-secondary-bg-color` | Secondary variant background |
| `--hero-secondary-overlay` | Secondary variant overlay gradient |
| `--hero-card-*` | Hero card styling (bg, color, overlay, border-radius, padding, max-width) |
| `--hero-alt-card-*` | Alternative hero card styling |
## Block Colors
Used for top-a, top-b, bottom-a, bottom-b section backgrounds:
| Variable | Description |
|----------|-------------|
| `--block-color-1` through `--block-color-4` | Background colours |
| `--block-text-1` through `--block-text-4` | Text colours |
| `--block-highlight-bg` / `--block-highlight-text` | Highlight block |
| `--block-cta-bg` / `--block-cta-text` | Call-to-action block |
| `--block-alert-bg` / `--block-alert-text` | Alert block |
## Footer
| Variable | Default | Description |
|----------|---------|-------------|
| `--footer-padding-top` | `1rem` | Top padding |
| `--footer-padding-bottom` | `80px` | Bottom padding (accounts for FAB) |
| `--footer-grid-padding-y` | `2.5rem` | Grid vertical padding |
| `--footer-grid-padding-x` | `0.5em` | Grid horizontal padding |
## Theme FAB
| Variable | Light Default | Dark Default | Description |
|----------|--------------|-------------|-------------|
| `--theme-fab-bg` | `var(--color-primary)` | `#e6ebf1` | FAB background |
| `--theme-fab-color` | `#fff` | `#0e1318` | FAB icon colour |
| `--theme-fab-btn-bg` | `rgba(255,255,255,.15)` | `transparent` | FAB button background |
| `--theme-fab-border` | `rgba(255,255,255,0.3)` | `rgba(0,0,0,0.15)` | FAB border colour |
## Component-Specific Variables
Additional variables are defined for: VirtueMart (`--vm-*`), Gable (`--gab-*`), accordion, alert, badge, breadcrumb, cards, dropdown, list group, modal, nav tabs/pills, offcanvas, pagination, popover, progress, spinner, table, toast, and tooltip components. See the theme palette files for the complete list.
---
*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) -- Moko Consulting*
MokoOnyx/Configuration.md
+139
View File
@@ -0,0 +1,139 @@
[← Back to Home](Home)
# Configuration
MokoOnyx is configured through the Joomla template style editor at **System → Site Templates → MokoOnyx**. Parameters are organized into tabbed fieldsets.
---
## Migration Tab
Informational notes about the MokoCassiopeia migration process. No editable parameters -- this tab provides guidance only.
---
## Advanced Tab
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `developmentmode` | Toggle | Off | Enables development mode. When on, `.min` files are deleted and unminified source files are served. When off, minified files are auto-generated. |
| `fluidContainer` | Toggle | Static | Controls whether the main layout uses a fixed-width (`container`) or full-width (`container-fluid`) wrapper. |
---
## Favicon Tab
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `favicon_source` | Media picker | _(none)_ | Upload a PNG image. MokoOnyx auto-generates all required favicon sizes, `apple-touch-icon.png`, and `site.webmanifest` on the next page load. |
---
## Google Tab
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `googletagmanager` | Toggle | Off | Enable Google Tag Manager integration. |
| `googletagmanagerid` | Text | _(empty)_ | Your GTM container ID (e.g., `GTM-XXXXXXX`). Shown when GTM is enabled. |
| `googleanalytics` | Toggle | Off | Enable Google Analytics (GA4) integration. |
| `googleanalyticsid` | Text | _(empty)_ | Your GA4 measurement ID (e.g., `G-XXXXXXXXXX`). Shown when GA4 is enabled. |
| `googlesitekey` | Text | _(empty)_ | Google site verification meta tag value. |
| `googlevisitordetection` | Toggle | On | When enabled, sends visitor context to GTM/GA4: login status, user group, and page type. Shown when GTM or GA4 is enabled. |
---
## Custom Code Tab
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `custom_head_start` | Textarea | _(empty)_ | Raw HTML/JS injected at the **start** of `<head>`. Useful for consent managers or early scripts. |
| `custom_head_end` | Textarea | _(empty)_ | Raw HTML/JS injected at the **end** of `<head>`, before `</head>`. |
---
## Drawers Tab
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `drawerLeftIcon` | Text | `fa-solid fa-chevron-right` | Font Awesome class for the left drawer toggle button icon. |
| `drawerRightIcon` | Text | `fa-solid fa-chevron-left` | Font Awesome class for the right drawer toggle button icon. |
---
## Theme Tab
The Theme tab is the largest configuration area, organized into sub-sections.
### General
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `theme_enabled` | Toggle | On | Master switch for the theme system (light/dark mode). |
| `theme_control_type` | List | Radios | How the user switches themes: **Switch** (Light/Dark toggle), **Radios** (Light/Dark/System), or **None** (no visible control). |
| `theme_default_choice` | List | System | Default theme when no user preference is stored: **System**, **Light**, or **Dark**. |
| `theme_auto_dark` | Toggle | Off | Automatically switch to dark mode based on time of day. |
| `theme_meta_color_scheme` | Toggle | On | Output `<meta name="color-scheme">` tag for browser chrome theming. |
| `theme_meta_theme_color` | Toggle | On | Output `<meta name="theme-color">` tag for mobile browser address bar. |
| `theme_bridge_bs_aria` | Toggle | On | Bridge Bootstrap `data-bs-theme` attribute with ARIA attributes for screen readers. |
### Variables and Palettes
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `colorLightName` | List | Standard | Light theme palette: **Standard** (built-in) or **Custom** (loads `light.custom.css`). |
| `colorDarkName` | List | Standard | Dark theme palette: **Standard** (built-in) or **Custom** (loads `dark.custom.css`). |
See [Custom Themes](Custom-Themes) for how to create custom palettes.
### Typography
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `useFontScheme` | Grouped list | Roboto (local) | Font family. Options: **None**, **Roboto** (local), **Noto Sans** (local), **Fira Sans** (local). All local fonts are self-hosted for GDPR compliance. |
### Branding and Icons
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `brand` | Toggle | On | Show the brand/logo area in the header. |
| `logoFile` | Media picker | _(none)_ | Logo image file. Shown when brand is enabled. |
| `siteTitle` | Text | MokoOnyx | Site title displayed next to the logo. |
| `siteDescription` | Text | _(empty)_ | Tagline displayed below the site title. |
| `fA6KitCode` | Text | _(empty)_ | Font Awesome 7 Pro Kit code. If empty, the bundled Font Awesome 7 Free is used (2,000+ icons). |
### Header and Navigation
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `stickyHeader` | Toggle | Off | Make the header stick to the top of the viewport on scroll. |
| `backTop` | Toggle | Off | Show a "Back to Top" button when the user scrolls down. |
### Accessibility
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `a11y_toolbar_enabled` | Toggle | On | Master switch for the accessibility toolbar. |
| `a11y_text_resize` | Toggle | On | Allow users to increase/decrease text size. |
| `a11y_color_inversion` | Toggle | On | Allow users to invert page colors. |
| `a11y_high_contrast` | Toggle | On | Allow users to enable high-contrast mode. |
| `a11y_highlight_links` | Toggle | On | Allow users to highlight all links on the page. |
| `a11y_readable_font` | Toggle | On | Allow users to switch to a more readable font. |
| `a11y_pause_animations` | Toggle | On | Allow users to pause CSS animations. |
| `a11y_toolbar_pos` | Hidden | Bottom-right | Toolbar position (fixed to bottom-right in code). |
### Theme Toggle UI
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `theme_fab_enabled` | Toggle | On | Show the floating action button (FAB) for theme switching. |
| `theme_fab_pos` | Hidden | Bottom-right | FAB position (fixed to bottom-right in code). |
---
## CSS Variables Tab
A read-only reference tab displaying all available CSS custom properties organized by category. See the [CSS Variables](CSS-Variables) page for the full reference.
---
*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) -- Moko Consulting*
MokoOnyx/Custom-Themes.-.md
+117
View File
@@ -0,0 +1,117 @@
[← Back to Home](Home)
# Custom Themes
MokoOnyx ships with **standard** light and dark palettes. You can create fully custom colour palettes by overriding CSS variables in dedicated files.
---
## How It Works
1. MokoOnyx loads a theme CSS file based on the `colorLightName` and `colorDarkName` template parameters
2. When set to **Standard**, it loads `light.standard.css` or `dark.standard.css`
3. When set to **Custom**, it loads `light.custom.css` or `dark.custom.css`
4. The theme file sets all CSS variables inside `:root[data-bs-theme="light"]` or `:root[data-bs-theme="dark"]`
---
## Creating a Custom Palette
### Step 1: Copy the Template
MokoOnyx ships starter templates in the `templates/` directory within the template source:
```
templates/mokoonyx/templates/light.custom.css
templates/mokoonyx/templates/dark.custom.css
```
These are full copies of the standard palettes -- every variable is included so you have a complete starting point.
### Step 2: Place Files in the Media Directory
Copy your customized files to the **media** directory (this location survives template updates):
```
media/templates/site/mokoonyx/css/theme/light.custom.css
media/templates/site/mokoonyx/css/theme/dark.custom.css
```
### Step 3: Select "Custom" in Template Settings
1. Go to **System → Site Templates → MokoOnyx**
2. Open the **Theme** tab
3. Under **Variables & Palettes**:
- Set **Light Theme** to **Custom**
- Set **Dark Theme** to **Custom**
4. Save
---
## File Locations
| File | Path | Purpose |
|------|------|---------|
| Light standard | `media/templates/site/mokoonyx/css/theme/light.standard.css` | Built-in light palette (do not edit) |
| Dark standard | `media/templates/site/mokoonyx/css/theme/dark.standard.css` | Built-in dark palette (do not edit) |
| Light custom | `media/templates/site/mokoonyx/css/theme/light.custom.css` | Your custom light palette |
| Dark custom | `media/templates/site/mokoonyx/css/theme/dark.custom.css` | Your custom dark palette |
| Light template | `templates/mokoonyx/templates/light.custom.css` | Starter template (copy from here) |
| Dark template | `templates/mokoonyx/templates/dark.custom.css` | Starter template (copy from here) |
---
## Key Variables to Customize
The most impactful variables to change for a quick rebrand:
```css
:root[data-bs-theme="light"] {
/* Brand colours -- the foundation of the entire palette */
--color-primary: #112855;
--accent-color-primary: #3f8ff0;
--accent-color-secondary: #6fb3ff;
/* Body */
--body-color: #22262a;
--body-bg: #fff;
/* Links */
--color-link: #224FAA;
--link-color: #224faa;
--link-hover-color: #424077;
/* Navigation */
--mainmenu-nav-link-color: white;
--nav-text-color: white;
--nav-bg-color: var(--color-link);
/* Header */
--header-background-color: #adadad;
}
```
See the [CSS Variables](CSS-Variables) page for a complete reference of all available variables.
---
## Variable Sync on Update
When MokoOnyx is updated, the installer runs a **CSS variable sync** process. If new variables have been added to the standard palettes, they are automatically appended to your custom palette files with their default values. A notice is displayed in the admin panel telling you how many variables were added.
This ensures your custom palettes stay compatible with new template features without breaking existing customizations.
---
## Custom CSS and JavaScript
For additional overrides beyond theme variables, use these files (also update-safe):
| File | Path |
|------|------|
| Custom CSS | `media/templates/site/mokoonyx/css/user.css` |
| Custom JS | `media/templates/site/mokoonyx/js/user.js` |
---
*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) -- Moko Consulting*
MokoOnyx/Development.md
+222
View File
@@ -0,0 +1,222 @@
[← Back to Home](Home)
# Development
This page covers the repository structure, build process, release workflow, and contributing guidelines for MokoOnyx.
---
## Repository Structure
```
MokoOnyx/
├── src/ # Template source (this becomes the installable package)
│ ├── component.php # Component-only page layout
│ ├── error.php # Error page layout
│ ├── index.php # Main template entry point
│ ├── joomla.asset.json # Joomla Web Asset Manager definitions
│ ├── offline.php # Offline page layout
│ ├── script.php # Install/update/uninstall script
│ ├── sync_custom_vars.php # CSS variable sync for custom palettes
│ ├── templateDetails.xml # Joomla template manifest
│ ├── helper/ # PHP helper classes
│ │ └── minify.php # CSS/JS auto-minification
│ ├── html/ # Template overrides (modules, components, layouts)
│ ├── language/ # Language files (en-GB, en-US)
│ ├── media/ # Static assets (installed to media/templates/site/mokoonyx/)
│ │ ├── css/ # Stylesheets
│ │ │ ├── template.css # Main template stylesheet
│ │ │ ├── editor.css # Backend editor stylesheet
│ │ │ ├── offline.css # Offline page styles
│ │ │ ├── a11y-high-contrast.css # High-contrast accessibility mode
│ │ │ ├── user.css # User custom CSS (survives updates)
│ │ │ ├── fonts/ # Local font files (Roboto, Noto Sans, Fira Sans)
│ │ │ └── theme/ # Theme palette files
│ │ │ ├── light.standard.css
│ │ │ └── dark.standard.css
│ │ ├── js/ # JavaScript
│ │ │ ├── template.js # Main template JS
│ │ │ ├── gtm.js # Google Tag Manager integration
│ │ │ └── user.js # User custom JS (survives updates)
│ │ ├── images/ # Template images (bg.svg, etc.)
│ │ ├── fonts/ # Font files
│ │ └── vendor/ # Third-party assets (Font Awesome 7 Free)
│ └── templates/ # Starter files for users
│ ├── light.custom.css # Custom light palette template
│ ├── dark.custom.css # Custom dark palette template
│ └── brand-showcase.html # Brand showcase HTML template
├── Makefile # Build and validation automation
├── composer.json # PHP dependencies (MokoStandards)
├── package.json # Node.js dependencies (minification)
├── phpcs.xml # PHP CodeSniffer configuration
├── phpstan.neon # PHPStan static analysis configuration
├── codeception.yml # Testing configuration
├── updates.xml # Joomla update server manifest
├── tests/ # Test suites
├── scripts/ # Build scripts
├── docs/ # Documentation source
└── build/ / dist/ # Build output (gitignored)
```
---
## Prerequisites
- **PHP** 8.1+
- **Composer** (for MokoStandards CLI and dependencies)
- **Node.js** (optional, for build-time minification with terser/clean-css)
- **Make** (GNU Make or compatible)
- **zip** (or PowerShell for Windows)
---
## Setup
```bash
# Clone the repository
git clone https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx.git
cd MokoOnyx
# Install dependencies
make install-deps
```
---
## Building Packages
### Build an installable ZIP
```bash
make build
```
This will:
1. Clean previous build artifacts (`build/` and `dist/`)
2. Minify CSS and JS assets
3. Copy `src/` contents to `build/package/`
4. Create `dist/mokoonyx-{version}.zip`
### Build a beta release
```bash
make build-beta
```
Creates `dist/mokoonyx-{version}-beta.zip` (skips minification).
---
## Validation
MokoOnyx uses the **MokoStandards Enterprise API** for code quality checks.
```bash
# Run all validation checks
make validate
# Individual checks
make lint # PHP syntax check
make check-joomla # Joomla manifest validation
make check-version # Version consistency across files
make check-xml # XML well-formedness
make check-headers # License header verification
make check-secrets # Credential leak scanning
# Full repository health check
make health
```
---
## Releasing
### Full release pipeline
```bash
make release
```
This runs the complete pipeline: `validate` → `build` → `checksum`
After the release package is built:
1. Tag the release: `git tag {version}`
2. Push tags: `git push origin --tags`
3. Create a Gitea release and attach the ZIP from `dist/`
### Generate checksums
```bash
make checksum
```
Creates SHA-256 checksums for all ZIP files in `dist/`.
---
## Available Make Targets
| Target | Description |
|--------|-------------|
| `make help` | Show all available targets |
| `make install-deps` | Install Composer dependencies |
| `make update-deps` | Update Composer dependencies |
| `make lint` | PHP syntax check |
| `make check-joomla` | Validate Joomla manifest |
| `make check-version` | Verify version consistency |
| `make check-headers` | Check license headers |
| `make check-secrets` | Scan for leaked credentials |
| `make check-xml` | Validate XML files |
| `make validate` | Run all validation checks |
| `make health` | Full repository health check |
| `make clean` | Clean build artifacts |
| `make minify` | Minify CSS/JS assets |
| `make build` | Build installable ZIP |
| `make build-beta` | Build beta release ZIP |
| `make checksum` | Generate SHA-256 checksums |
| `make release` | Full release pipeline |
| `make version` | Display version and extension info |
| `make security-check` | Composer security audit |
| `make all` | Full pipeline (deps, validate, build, checksum) |
---
## Contributing
1. Fork the repository on [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
2. Create a feature branch from `dev`
3. Make your changes in `src/`
4. Run `make validate` to ensure all checks pass
5. Submit a pull request against `dev`
### Code Standards
- All PHP files must include the GPL-3.0-or-later license header
- PHP code must pass syntax checks and PHPStan analysis
- XML files must be well-formed
- Version numbers must be consistent across `README.md`, `templateDetails.xml`, and other version-bearing files
- Attribution goes to **Moko Consulting**, not individual contributors
### Branching Model
| Branch | Purpose |
|--------|---------|
| `main` | Stable releases |
| `dev` | Active development |
---
## Testing
The repository includes a `codeception.yml` configuration for automated testing:
```bash
# Run tests (requires Codeception via Composer)
vendor/bin/codecept run
```
---
*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) -- Moko Consulting*
MokoOnyx/Installation.md
+58
View File
@@ -0,0 +1,58 @@
[← Back to Home](Home)
# Installation
## Requirements
| Requirement | Minimum Version |
|-------------|----------------|
| Joomla | 5.x or 6.x |
| PHP | 8.1 or higher |
## Download
Download the latest `mokoonyx-{version}.zip` from the [Releases page](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases/tag/stable).
## Install via Joomla Admin
1. Log in to your Joomla administrator panel
2. Navigate to **System → Install → Extensions**
3. Upload the `mokoonyx-{version}.zip` file
4. Wait for the installer to complete
The installer performs a preflight check to verify your PHP and Joomla versions meet the minimum requirements. If they do not, installation will be blocked with an error message.
## Set as Default Template
1. Navigate to **System → Site Templates**
2. Click the star icon next to **MokoOnyx** to set it as the default site template
## First Page Load (Migration)
If you are migrating from MokoCassiopeia, the migration runs automatically during install:
1. **Visit any page on your site** after installation -- the template activates immediately
2. Check **administrator/logs/mokoonyx.log.php** to confirm the migration completed
3. Once confirmed, uninstall MokoCassiopeia from **Extensions → Manage**
See the [Migration](Migration) page for full details on what gets migrated.
## Post-Install Notes
- The extension is automatically **locked** after install to prevent accidental uninstallation
- Stale `.min` files from previous versions are cleaned automatically
- Favicon stamps are cleared so favicons regenerate on the next page load
- MokoCassiopeia references in article content and modules are automatically updated to MokoOnyx
## Update Server
MokoOnyx includes an automatic update server. Joomla will notify you when new versions are available via **System → Update → Extensions**. Two update servers are configured for redundancy:
| Priority | Server |
|----------|--------|
| 1 | Gitea (git.mokoconsulting.tech) |
| 2 | GitHub (github.com) |
---
*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) -- Moko Consulting*
MokoOnyx/Migration.md
+111
View File
@@ -0,0 +1,111 @@
[← Back to Home](Home)
# Migration from MokoCassiopeia
MokoOnyx is the successor to MokoCassiopeia. The migration runs **automatically during install/update** -- no manual steps are required beyond installing MokoOnyx.
---
## When Does Migration Run?
The migration runs in the `postflight()` method of the installer script (`script.php`), which executes during both `install` and `update` operations. It checks for existing MokoCassiopeia template styles in the database and only runs if they are found.
---
## What Gets Migrated
### 1. Template Styles and Parameters
- All MokoCassiopeia template styles are detected from the `#__template_styles` table
- For each MokoCassiopeia style, a matching MokoOnyx style is created with the same parameters
- The first MokoCassiopeia style's parameters are applied to the installer-created default MokoOnyx style
- Additional styles are created as new entries
- Parameter values are updated to replace `mokocassiopeia` references with `mokoonyx`
### 2. Default Template Assignment
If MokoCassiopeia was set as the default site template (`home = 1`), MokoOnyx automatically takes over as the default. The MokoCassiopeia style is unset as default.
### 3. Custom User Files
The following files are copied from the MokoCassiopeia media directory to MokoOnyx (only if the destination file does not already exist):
| File | Purpose |
|------|---------|
| `css/theme/light.custom.css` | Custom light palette |
| `css/theme/dark.custom.css` | Custom dark palette |
| `css/theme/light.custom.min.css` | Minified custom light palette |
| `css/theme/dark.custom.min.css` | Minified custom dark palette |
| `css/user.css` | Custom CSS overrides |
| `css/user.min.css` | Minified custom CSS |
| `js/user.js` | Custom JavaScript |
| `js/user.min.js` | Minified custom JavaScript |
Source: `media/templates/site/mokocassiopeia/`
Destination: `media/templates/site/mokoonyx/`
### 4. Content References
All references to "MokoCassiopeia" and "mokocassiopeia" in article content (`introtext` and `fulltext` columns) and module content are automatically replaced with "MokoOnyx" and "mokoonyx". This covers:
- Image paths (e.g., `media/templates/site/mokocassiopeia/...`)
- Template name references in custom HTML modules
- Any other text references in content
### 5. Additional Post-Install Tasks
These tasks run during every install/update (not just migration):
| Task | Description |
|------|-------------|
| **Favicon stamp cleared** | Deletes `.favicon_generated` stamp so favicons regenerate. Also removes the old `/images/favicons/` directory and root-level favicon files from previous versions. |
| **Media folder cleaned** | Removes stale `.min.css` and `.min.js` files (regenerated by `MokoMinifyHelper`), unminified vendor files, and deprecated files (`custom.css`, `custom.js`, `template-rtl.css`). |
| **Extension locked** | Sets `locked = 1` in `#__extensions` to prevent accidental uninstallation. |
---
## How to Trigger Migration
Migration runs automatically during installation. If you need to observe the results:
1. Install MokoOnyx via **System → Install → Extensions**
2. Go to **System → Site Templates** and verify MokoOnyx appears with your settings
3. Visit any page on your site to confirm the template is active
4. Check **administrator/logs/mokoonyx.log.php** for migration log entries
---
## Re-Running Migration
The migration runs on every install/update operation via the `postflight()` method. It is safe to re-run because:
- Style creation checks for existing styles before creating duplicates
- File copies only occur when the destination file does not exist
- Content replacements are idempotent (replacing "MokoOnyx" with "MokoOnyx" is a no-op)
To force a fresh migration, you can reinstall MokoOnyx by uploading the ZIP package again.
---
## After Migration
Once you have confirmed everything is working:
1. Uninstall MokoCassiopeia from **Extensions → Manage**
2. Optionally clean up any remaining MokoCassiopeia files in `media/templates/site/mokocassiopeia/`
---
## Troubleshooting
| Issue | Solution |
|-------|----------|
| Settings not migrated | Check `administrator/logs/mokoonyx.log.php` for error messages. Verify MokoCassiopeia styles exist in `#__template_styles`. |
| Custom theme files missing | Verify files exist in `media/templates/site/mokocassiopeia/css/theme/`. The copy only runs if the destination does not already exist -- if MokoOnyx files are already present, they are not overwritten. |
| Content references not updated | Check the log for "Content replacement failed" or "Module replacement failed" warnings. Database permissions may be insufficient. |
| PHP version error | MokoOnyx requires PHP 8.1+. The preflight check blocks installation if this is not met. |
| Joomla version error | MokoOnyx requires Joomla 4.4+. The preflight check blocks installation if this is not met. |
---
*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) -- Moko Consulting*
MokoOnyx/Minification.md
+105
View File
@@ -0,0 +1,105 @@
[← Back to Home](Home)
# Minification
MokoOnyx includes an automatic CSS/JS minification system that generates `.min` files at runtime based on the development mode setting.
---
## How It Works
The minification system is implemented in `MokoMinifyHelper` (`helper/minify.php`). It is called from the template's `index.php` on every page load and follows a simple rule:
- **Development mode OFF** (production): `.min` files are generated from source files when the source is newer or the `.min` file is missing
- **Development mode ON**: all `.min` files are **deleted** so the browser loads unminified source files for debugging
---
## Files Managed
### CSS Files
| Source File | Minified Output |
|-------------|----------------|
| `css/template.css` | `css/template.min.css` |
| `css/offline.css` | `css/offline.min.css` |
| `css/editor.css` | `css/editor.min.css` |
| `css/a11y-high-contrast.css` | `css/a11y-high-contrast.min.css` |
| `css/user.css` | `css/user.min.css` |
| `css/theme/light.standard.css` | `css/theme/light.standard.min.css` |
| `css/theme/dark.standard.css` | `css/theme/dark.standard.min.css` |
| `css/theme/light.custom.css` | `css/theme/light.custom.min.css` |
| `css/theme/dark.custom.css` | `css/theme/dark.custom.min.css` |
### JavaScript Files
| Source File | Minified Output |
|-------------|----------------|
| `js/template.js` | `js/template.min.js` |
| `js/gtm.js` | `js/gtm.min.js` |
| `js/user.js` | `js/user.min.js` |
All paths are relative to `media/templates/site/mokoonyx/`.
---
## Staleness Check
The system uses filesystem modification times to determine whether a `.min` file needs regenerating:
1. If the source file does not exist, skip it
2. If the `.min` file exists and its modification time is **newer or equal** to the source, skip it
3. Otherwise, read the source, minify it, and write the `.min` file
This means minification only runs when source files actually change, keeping page load overhead minimal.
---
## CSS Minification
The CSS minifier performs these transformations:
1. Remove CSS comments (preserving IE hacks)
2. Remove whitespace around `{ } : ; , > + ~`
3. Collapse remaining whitespace to single spaces
4. Remove trailing semicolons before closing braces (`;}` becomes `}`)
5. Strip leading/trailing whitespace
---
## JavaScript Minification
The JS minifier performs these transformations:
1. Remove multi-line comments (`/* ... */`)
2. Remove single-line comments (`//`) while preserving URLs
3. Collapse whitespace
4. Remove spaces around operators and punctuation
5. Restore necessary spaces after keywords (`var`, `let`, `const`, `return`, `typeof`, `instanceof`, `new`, `delete`, `throw`, `case`, `in`, `of`)
---
## Build-Time vs Runtime
| Context | What Happens |
|---------|-------------|
| **Runtime** (page load) | `MokoMinifyHelper::sync()` runs on every page load. In production mode, it checks timestamps and regenerates stale `.min` files. The overhead is negligible (filesystem stat calls only when files have not changed). |
| **Build-time** (`make build`) | The Makefile runs `make minify` before packaging. This uses the moko-platform `minify.js` script (Node.js) with `terser` and `clean-css` for higher-quality minification. |
| **Install/Update** | The installer script (`script.php`) deletes all `.min.css` and `.min.js` files in the `css/` and `js/` directories so they are cleanly regenerated by the runtime minifier on the first page load. Vendor `.min` files in `vendor/` are not touched. |
---
## Debug Mode Behaviour
To debug CSS or JS issues:
1. Go to **System → Site Templates → MokoOnyx**
2. Open the **Advanced** tab
3. Set **Development Mode** to **Yes**
4. Save
This immediately deletes all `.min` files. The template will load the unminified source files, making browser DevTools inspection straightforward. Remember to turn development mode **off** for production.
---
*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) -- Moko Consulting*
MokoOnyx/Template-Overrides.-.md
+102
View File
@@ -0,0 +1,102 @@
[← Back to Home](Home)
# Template Overrides
MokoOnyx includes template overrides for Joomla core modules, third-party extensions, and layout files. These overrides are located in `templates/mokoonyx/html/`.
---
## Joomla Core Module Overrides
| Module | Override File(s) | Description |
|--------|-----------------|-------------|
| `mod_articles_archive` | `default.php` | Articles archive module |
| `mod_articles_categories` | `default.php` | Article categories listing |
| `mod_articles_category` | `default.php` | Articles from a single category |
| `mod_articles_latest` | `default.php` | Latest articles module |
| `mod_articles_news` | `default.php` | News flash / articles newsflash |
| `mod_articles_popular` | `default.php` | Most-read articles |
| `mod_banners` | `default.php` | Banner display module |
| `mod_breadcrumbs` | `default.php` | Breadcrumb navigation |
| `mod_custom` | `default.php`, `hero.php` | Custom HTML module (includes a hero layout variant) |
| `mod_feed` | `default.php` | RSS/Atom feed display |
| `mod_finder` | `default.php` | Smart Search box |
| `mod_footer` | `default.php` | Footer information |
| `mod_languages` | `default.php` | Language switcher |
| `mod_login` | `default.php` | Login form |
| `mod_menu` | `default.php`, `horizontal.php`, `horizontal_component.php`, `horizontal_heading.php`, `horizontal_separator.php`, `horizontal_url.php`, `mainmenu.php`, `mainmenu_component.php`, `mainmenu_heading.php`, `mainmenu_separator.php`, `mainmenu_url.php` | Menu module with horizontal and main menu layouts |
| `mod_random_image` | `default.php` | Random image display |
| `mod_related_items` | `default.php` | Related articles |
| `mod_stats` | `default.php` | Site statistics |
| `mod_syndicate` | `default.php` | Syndication / RSS link |
| `mod_tags_popular` | `default.php` | Popular tags |
| `mod_tags_similar` | `default.php` | Similar tags |
| `mod_users_latest` | `default.php` | Latest registered users |
| `mod_whosonline` | `default.php` | Who's online |
| `mod_wrapper` | `default.php` | iFrame wrapper |
---
## Third-Party Extension Overrides
### Community Builder
| Module | Override File(s) | Description |
|--------|-----------------|-------------|
| `mod_cblogin` | `default.php`, `default_logout.php` | Community Builder login/logout module |
| `mod_comprofilermoderator` | `default.php` | CB moderator panel |
| `mod_comprofileronline` | `default.php` | CB online users |
### DPCalendar
| Module | Override File(s) | Description |
|--------|-----------------|-------------|
| `mod_dpcalendar_counter` | `default.php` | Event countdown timer |
| `mod_dpcalendar_map` | `default.php` | Event map display |
| `mod_dpcalendar_mini` | `default.php`, `default_icons.php`, `default_map.php`, `default_quickadd.php`, `_scripts.php` | Mini calendar widget |
| `mod_dpcalendar_upcoming` | `default.php`, `_scripts.php` | Upcoming events list |
### JoomGallery
| Component View | Override File(s) | Description |
|---------------|-----------------|-------------|
| `com_joomgallery/category` | `default.php`, `default_cat.php` | Gallery category view |
| `com_joomgallery/gallery` | `default.php` | Main gallery view |
| `com_joomgallery/image` | `default.php` | Single image view |
---
## Component Overrides
| Component | View | Override File(s) | Description |
|-----------|------|-----------------|-------------|
| `com_content` | `article` | `toc-left.php`, `toc-right.php` | Article views with Table of Contents positioned left or right |
---
## Layout Overrides
| Layout | Override File | Description |
|--------|--------------|-------------|
| `joomla.module` | `card.php` | Module chrome -- wraps any module in a Bootstrap card layout |
---
## Hero Layout (mod_custom)
The `hero.php` layout for `mod_custom` provides a full-width hero/banner module. It uses the hero CSS variables (`--hero-*`) for styling. Assign a custom HTML module to positions like `banner` or `top-a` and select the "hero" layout in the module's Advanced tab.
---
## Menu Layouts
MokoOnyx provides two specialized menu layouts:
- **horizontal** -- A horizontal navigation bar with dropdown support, used for the main site navigation
- **mainmenu** -- An enhanced main menu layout with support for component links, headings, separators, and URL items
Each layout has sub-templates for different menu item types: `_component`, `_heading`, `_separator`, and `_url`.
---
*Built with [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API) -- Moko Consulting*
README.md
+5 -5
View File
@@ -6,16 +6,16 @@ Consolidated backup of all project wikis from [Gitea](https://git.mokoconsulting
## Projects
- [**MokoOnyx**](MokoOnyx/) — 1 pages
- [**MokoOnyx**](MokoOnyx/) — 9 pages
- [**MokoWaaS**](MokoWaaS/) — 12 pages
- [**Template-Client-WaaS**](Template-Client-WaaS/) — 5 pages
- [**backup-mcp**](backup-mcp/) — 3 pages
- [**backup-mcp**](backup-mcp/) — 6 pages
- [**client-clarksvillefurs**](client-clarksvillefurs/) — 16 pages
- [**deploy-mcp**](deploy-mcp/) — 4 pages
- [**deploy-mcp**](deploy-mcp/) — 6 pages
- [**joomla-api-mcp**](joomla-api-mcp/) — 6 pages
- [**moko-platform**](moko-platform/) — 52 pages
- [**monitor-mcp**](monitor-mcp/) — 4 pages
- [**monitor-mcp**](monitor-mcp/) — 6 pages
- [**ssh-mcp**](ssh-mcp/) — 10 pages
---
*Last synced: 2026-05-09 23:32 UTC*
*Last synced: 2026-05-09 23:43 UTC*
backup-mcp/Configuration.md
+167
View File
@@ -0,0 +1,167 @@
[← Back to Home](Home)
# Configuration
backup-mcp loads its configuration from `~/.backup-mcp.json` (or the path set in `BACKUP_MCP_CONFIG` environment variable).
## Config File Location
| Method | Path |
|--------|------|
| Default | `~/.backup-mcp.json` |
| Environment variable | `BACKUP_MCP_CONFIG=/path/to/config.json` |
## Config File Structure
```json
{
"defaultTarget": "dolibarr-db",
"targets": {
"dolibarr-db": {
"name": "dolibarr",
"type": "mysql",
"sshHost": "crm.mokoconsulting.tech",
"sshUser": "mokoconsulting",
"sshKeyPath": "~/.ssh/id_ed25519",
"database": "dolibarr",
"dbUser": "dolibarr",
"dbPassword": "your-db-password",
"localBackupDir": "~/backups/dolibarr"
},
"joomla-db": {
"name": "joomla",
"type": "mysql",
"sshHost": "waas.mokoconsulting.tech",
"sshUser": "mokoconsulting",
"sshKeyPath": "~/.ssh/id_ed25519",
"database": "joomla",
"dbUser": "joomla",
"dbPassword": "your-db-password",
"remotePaths": ["/var/www/html/images", "/var/www/html/media"],
"localBackupDir": "~/backups/joomla"
},
"joomla-akeeba": {
"name": "joomla-akeeba",
"type": "akeeba",
"siteUrl": "https://example.com",
"secretWord": "your-joomla-api-token",
"profileId": 1,
"localBackupDir": "~/backups/joomla-akeeba"
}
}
}
```
## Top-Level Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `targets` | `Record<string, BackupTarget>` | Yes | Named backup target definitions |
| `defaultTarget` | `string` | No | Default target name. Falls back to the first key in `targets` |
## Target Types
Each target has a `type` field that determines which backup operations are available.
| Type | Tools Available | Description |
|------|----------------|-------------|
| `mysql` | `backup_database`, `backup_files` | MySQL database dump via SSH |
| `postgres` | `backup_database`, `backup_files` | PostgreSQL database dump via SSH |
| `files` | `backup_files` | Remote file/directory backup via SSH |
| `akeeba` | `akeeba_backup`, `akeeba_list`, `akeeba_download`, `akeeba_delete`, `akeeba_profiles` | Akeeba Backup via Joomla API |
## Common Target Fields
These fields apply to all target types.
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Identifier used in backup filenames (e.g. `dolibarr`, `joomla`) |
| `type` | `enum` | Yes | Target type: `mysql`, `postgres`, `files`, `akeeba` |
| `localBackupDir` | `string` | Yes | Local directory where backups are stored. Created automatically if it does not exist |
## SSH Target Fields (mysql, postgres, files)
These fields configure the SSH connection for database and file backups.
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `sshHost` | `string` | Yes | — | Remote server hostname or IP |
| `sshPort` | `number` | No | `22` | SSH port |
| `sshUser` | `string` | Yes | — | SSH username |
| `sshKeyPath` | `string` | No | — | Path to SSH private key |
## Database Fields (mysql, postgres)
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `database` | `string` | Yes | Database name to dump |
| `dbUser` | `string` | Yes | Database username |
| `dbPassword` | `string` | Yes | Database password |
## File Backup Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `remotePaths` | `string[]` | No | Array of remote directories to include in tar.gz backup |
## Akeeba Target Fields
These fields configure Akeeba Backup via the Joomla Web Services API.
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `siteUrl` | `string` | Yes | — | Joomla site base URL (e.g. `https://example.com`) |
| `secretWord` | `string` | Yes | — | Joomla API token (used as Bearer auth) |
| `profileId` | `number` | No | `1` | Akeeba backup profile ID |
## Backup File Naming
Backups are saved with timestamped filenames:
| Type | Pattern | Example |
|------|---------|---------|
| Database | `{name}-db-{timestamp}.sql.gz` | `dolibarr-db-2026-05-09T12-00-00.sql.gz` |
| Files | `{name}-files-{timestamp}.tar.gz` | `joomla-files-2026-05-09T12-00-00.tar.gz` |
| Akeeba | `{name}-akeeba-{id}-{timestamp}.jpa` | `joomla-akeeba-42-2026-05-09T12-00-00.jpa` |
## Minimal Config Examples
### MySQL database backup only
```json
{
"targets": {
"mydb": {
"name": "mydb",
"type": "mysql",
"sshHost": "server.example.com",
"sshUser": "deploy",
"database": "myapp",
"dbUser": "root",
"dbPassword": "secret",
"localBackupDir": "~/backups/mydb"
}
}
}
```
### Akeeba backup only
```json
{
"targets": {
"mysite": {
"name": "mysite",
"type": "akeeba",
"siteUrl": "https://example.com",
"secretWord": "your-joomla-api-token",
"localBackupDir": "~/backups/mysite"
}
}
}
```
---
> Built on [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)
backup-mcp/MySQL-Backup.-.md
+168
View File
@@ -0,0 +1,168 @@
[← Back to Home](Home)
# MySQL Backup
backup-mcp supports MySQL (and PostgreSQL) database backups over SSH using `mysqldump` (or `pg_dump`).
## How It Works
1. The tool connects to the remote server via SSH
2. Runs `mysqldump` on the remote server, piping through `gzip`
3. Streams the compressed output back to the local machine
4. Saves the result to `localBackupDir` with a timestamped filename
The dump command executed on the remote server:
```bash
mysqldump -u {dbUser} -p'{dbPassword}' {database} | gzip
```
For PostgreSQL targets:
```bash
PGPASSWORD='{dbPassword}' pg_dump -U {dbUser} {database} | gzip
```
## Configuration
Add a `mysql` target to `~/.backup-mcp.json`:
```json
{
"targets": {
"mysite-db": {
"name": "mysite",
"type": "mysql",
"sshHost": "server.example.com",
"sshPort": 22,
"sshUser": "deploy",
"sshKeyPath": "~/.ssh/id_ed25519",
"database": "joomla_db",
"dbUser": "joomla",
"dbPassword": "your-password",
"localBackupDir": "~/backups/mysite"
}
}
}
```
See [Configuration](Configuration) for all field descriptions.
## Running a Backup
Use the `backup_database` tool:
```
backup_database(target: "mysite-db")
```
Output:
```json
{
"success": true,
"message": "Database backup: mysite-db-2026-05-09T12-00-00.sql.gz",
"filePath": "/home/user/backups/mysite/mysite-db-2026-05-09T12-00-00.sql.gz",
"sizeBytes": 1048576
}
```
## Listing Backups
```
backup_list(target: "mysite-db")
```
Lists all local backups for the target, sorted by date (newest first):
```
mysite-db-2026-05-09T12-00-00.sql.gz 15.2 MB 2026-05-09T12:00:00.000Z
mysite-db-2026-05-08T12-00-00.sql.gz 14.8 MB 2026-05-08T12:00:00.000Z
```
## Checking Backup Status
```
backup_status(target: "mysite-db")
```
Shows total count, disk usage, and last backup info:
```
Backups: 5
Total size: 73.2 MB
Last backup: mysite-db-2026-05-09T12-00-00.sql.gz (2026-05-09T12:00:00.000Z)
```
## Pruning Old Backups
Delete backups older than a specified number of days:
```
backup_prune(target: "mysite-db", days: 30)
```
Output:
```
Pruned 3 backups older than 30 days
```
## Restoring a Database Backup
Database restore is a manual process using SSH and the backup file.
### Step 1: Locate the backup
```
backup_list(target: "mysite-db")
```
### Step 2: Copy the backup to the server
Use deploy-mcp or SCP:
```bash
scp ~/backups/mysite/mysite-db-2026-05-09T12-00-00.sql.gz deploy@server.example.com:/tmp/
```
### Step 3: Restore on the remote server
```bash
ssh deploy@server.example.com
gunzip < /tmp/mysite-db-2026-05-09T12-00-00.sql.gz | mysql -u joomla -p joomla_db
```
### Step 4: Verify
```bash
mysql -u joomla -p joomla_db -e "SHOW TABLES;"
```
## Backup Scheduling
backup-mcp does not include a built-in scheduler. Use external scheduling:
### Linux (cron)
Call the MCP tool via Claude Code on a schedule, or use a wrapper script:
```bash
# Example: daily database backup at 2 AM
0 2 * * * cd /path/to/project && npx backup-mcp backup_database --target mysite-db
```
### Windows (Task Scheduler)
Create a scheduled task that invokes the backup through Claude Code or a script.
## Timeout and Buffer Limits
| Setting | Value |
|---------|-------|
| SSH timeout | 5 minutes (300,000 ms) |
| Max buffer | 500 MB |
Large databases that exceed the buffer or timeout will fail. For very large databases, consider running `mysqldump` directly on the server and downloading the result separately.
---
> Built on [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)
backup-mcp/Restore-Guide.-.md
+203
View File
@@ -0,0 +1,203 @@
[← Back to Home](Home)
# Restore Guide
Step-by-step procedures for restoring from each backup type supported by backup-mcp.
## Restore from Database Backup (MySQL)
Database backups are stored as gzip-compressed SQL dumps (`{name}-db-{timestamp}.sql.gz`).
### Step 1: Identify the backup to restore
```
backup_list(target: "mysite-db")
```
Select the backup file by date.
### Step 2: Upload the backup to the server
```bash
scp ~/backups/mysite/mysite-db-2026-05-09T12-00-00.sql.gz user@server:/tmp/
```
### Step 3: Stop the application (recommended)
```bash
ssh user@server "sudo systemctl stop apache2"
```
### Step 4: Restore the database
```bash
ssh user@server "gunzip < /tmp/mysite-db-2026-05-09T12-00-00.sql.gz | mysql -u dbuser -p'password' database_name"
```
For a clean restore (drop and recreate):
```bash
ssh user@server << 'EOF'
mysql -u dbuser -p'password' -e "DROP DATABASE database_name; CREATE DATABASE database_name;"
gunzip < /tmp/mysite-db-2026-05-09T12-00-00.sql.gz | mysql -u dbuser -p'password' database_name
EOF
```
### Step 5: Restart the application
```bash
ssh user@server "sudo systemctl start apache2"
```
### Step 6: Verify
```bash
ssh user@server "mysql -u dbuser -p'password' database_name -e 'SHOW TABLES;'"
```
## Restore from Database Backup (PostgreSQL)
PostgreSQL backups are also gzip-compressed (`{name}-db-{timestamp}.sql.gz`).
### Steps
```bash
# Upload
scp ~/backups/mydb/mydb-db-2026-05-09T12-00-00.sql.gz user@server:/tmp/
# Restore
ssh user@server "gunzip < /tmp/mydb-db-2026-05-09T12-00-00.sql.gz | PGPASSWORD='password' psql -U dbuser database_name"
```
For a clean restore:
```bash
ssh user@server << 'EOF'
PGPASSWORD='password' dropdb -U dbuser database_name
PGPASSWORD='password' createdb -U dbuser database_name
gunzip < /tmp/mydb-db-2026-05-09T12-00-00.sql.gz | PGPASSWORD='password' psql -U dbuser database_name
EOF
```
## Restore from File Backup
File backups are tar.gz archives of remote directories (`{name}-files-{timestamp}.tar.gz`).
### Step 1: Identify the backup
```
backup_list(target: "mysite-files")
```
### Step 2: Upload the archive to the server
```bash
scp ~/backups/mysite/mysite-files-2026-05-09T12-00-00.tar.gz user@server:/tmp/
```
### Step 3: Extract to the original location
```bash
ssh user@server "cd / && tar xzf /tmp/mysite-files-2026-05-09T12-00-00.tar.gz"
```
The tar archive preserves the full path structure from `remotePaths`. Extracting from `/` restores files to their original locations.
### Step 4: Fix permissions
```bash
ssh user@server << 'EOF'
chown -R www-data:www-data /var/www/html/images
chown -R www-data:www-data /var/www/html/media
find /var/www/html/images -type f -exec chmod 644 {} +
find /var/www/html/images -type d -exec chmod 755 {} +
EOF
```
### Step 5: Verify
```bash
ssh user@server "ls -la /var/www/html/images/"
```
## Restore from Akeeba Backup
Akeeba backups are JPA archives that contain both the database and all site files.
### Step 1: List available Akeeba backups
```
akeeba_list(target: "mysite-akeeba")
```
### Step 2: Download the backup locally
```
akeeba_download(target: "mysite-akeeba", backup_id: "42")
```
The file is saved to `localBackupDir` as `{name}-akeeba-{id}-{timestamp}.jpa`.
### Step 3: Upload to the server
```bash
scp ~/backups/mysite-akeeba/mysite-akeeba-42-2026-05-09T12-00-00.jpa user@server:/tmp/
```
### Step 4: Extract using Akeeba Kickstart
1. Download [Akeeba Kickstart](https://www.akeeba.com/products/akeeba-kickstart.html) and upload `kickstart.php` to the web root:
```bash
scp kickstart.php user@server:/var/www/html/
```
2. Open `https://example.com/kickstart.php` in a browser.
3. Select the JPA file from `/tmp/` and follow the wizard:
- **Archive file**: `/tmp/mysite-akeeba-42-2026-05-09T12-00-00.jpa`
- **Extract to**: `/var/www/html`
- Click **Start** to extract
4. After extraction, the Akeeba Installer (ANGIE) will launch automatically:
- Verify database connection settings
- Update site URL if restoring to a different domain
- Complete the restoration
### Step 5: Clean up
```bash
ssh user@server "rm /var/www/html/kickstart.php /tmp/*.jpa"
```
### Step 6: Verify
Visit the site in a browser and check:
- Frontend loads correctly
- Administrator login works
- Media files are accessible
## Restore Checklist
| Step | Database | Files | Akeeba |
|------|----------|-------|--------|
| Identify backup | `backup_list` | `backup_list` | `akeeba_list` |
| Download/locate | Already local | Already local | `akeeba_download` |
| Stop application | Recommended | Optional | Required |
| Upload to server | SCP | SCP | SCP |
| Restore | `mysql` / `psql` | `tar xzf` | Kickstart + ANGIE |
| Fix permissions | N/A | `chown` + `chmod` | Handled by ANGIE |
| Restart application | Yes | Optional | Yes |
| Verify | Query tables | List files | Browse site |
## Important Notes
- Always create a fresh backup before restoring, in case the restore needs to be reverted.
- For Joomla sites, clear the cache after any restore: **System > Clear Cache** in the administrator.
- Database restores overwrite all data in the target database. Ensure you are restoring to the correct database.
- File restores overwrite existing files at the same paths. Files not in the backup are left untouched.
- Akeeba restores are the most complete option for Joomla sites, as they include both database and files.
---
> Built on [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)
deploy-mcp/Joomla-Sync.-.md
+163
View File
@@ -0,0 +1,163 @@
[← Back to Home](Home)
# Joomla Sync
The `deploy_sync_joomla` tool synchronizes Joomla extension files between two servers. It wraps the `sync-joomla.php` script from the `moko-platform/deploy/` directory.
## Overview
| Feature | Description |
|---------|-------------|
| Tool name | `deploy_sync_joomla` |
| Script | `sync-joomla.php` (located via `platformPath` config or `A:/moko-platform/deploy/`) |
| Auth | Uses SFTP config files from each server |
| Timeout | 5 minutes (300,000 ms) |
## Sync Modes
### manifest (default)
Smart diff-based sync. Compares extension manifests between source and destination to detect changes, then copies only modified extensions.
```
mode: "manifest"
```
- Fastest mode for routine syncs
- Only transfers files belonging to extensions whose manifests differ
- Best for syncing individual extension updates
### rsync
Full site sync using SSH-based rsync. Transfers the entire Joomla site directory tree.
```
mode: "rsync"
```
- Uses `rsync` over SSH for efficient delta transfer
- Syncs the complete site, not just extensions
- Best for initial deployment or full site migration
### full
SFTP directory scan mode. Walks the remote directory tree via SFTP to compare files.
```
mode: "full"
```
- Scans directories via SFTP connection
- Supports `scope` parameter to limit what is synced
- Slower than manifest mode but does not require manifest files
## Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `source_config` | `string` | Yes | — | Path to the source server's `sftp-config.json` |
| `dest_config` | `string` | Yes | — | Path to the destination server's `sftp-config.json` |
| `mode` | `enum` | No | `manifest` | Sync mode: `manifest`, `rsync`, or `full` |
| `scope` | `enum` | No | `all` | Scope for `full` mode only: `all`, `components`, `plugins`, `modules`, `templates`, `media`, `language` |
| `dry_run` | `boolean` | No | `false` | Preview changes without syncing |
| `force` | `boolean` | No | `false` | Copy all differing files regardless of timestamp |
| `verbose` | `boolean` | No | `false` | Show individual file transfers |
## SFTP Config Format
Both `source_config` and `dest_config` point to Sublime Text-style `sftp-config.json` files:
```json
{
"host": "server.example.com",
"user": "deploy",
"port": "22",
"remote_path": "/var/www/html",
"ssh_key_file": "~/.ssh/id_ed25519"
}
```
## Usage Examples
### Preview changes (dry run)
Manifest-based diff between dev and production:
```
deploy_sync_joomla(
source_config: "C:/projects/mysite/sftp-config.dev.json",
dest_config: "C:/projects/mysite/sftp-config.prod.json",
mode: "manifest",
dry_run: true
)
```
### Sync extensions from dev to production
```
deploy_sync_joomla(
source_config: "C:/projects/mysite/sftp-config.dev.json",
dest_config: "C:/projects/mysite/sftp-config.prod.json",
mode: "manifest",
verbose: true
)
```
### Full site rsync
```
deploy_sync_joomla(
source_config: "C:/projects/mysite/sftp-config.dev.json",
dest_config: "C:/projects/mysite/sftp-config.prod.json",
mode: "rsync"
)
```
### Sync only templates (full mode)
```
deploy_sync_joomla(
source_config: "C:/projects/mysite/sftp-config.dev.json",
dest_config: "C:/projects/mysite/sftp-config.prod.json",
mode: "full",
scope: "templates"
)
```
### Force sync all differing files
```
deploy_sync_joomla(
source_config: "C:/projects/mysite/sftp-config.dev.json",
dest_config: "C:/projects/mysite/sftp-config.prod.json",
force: true
)
```
## platformPath Configuration
The tool locates `sync-joomla.php` by checking these paths in order:
1. `{platformPath}/deploy/sync-joomla.php` — from `platformPath` in `~/.deploy-mcp.json`
2. `A:/moko-platform/deploy/sync-joomla.php` — hardcoded fallback
If the script is not found, the tool returns: `"sync-joomla.php not found. Set platformPath in deploy-mcp config."`
Set `platformPath` in your deploy config:
```json
{
"platformPath": "A:/moko-platform",
"connections": { ... }
}
```
## Requirements
- PHP must be available on the local system (the script runs locally via `php`)
- The `sync-joomla.php` script from moko-platform must be accessible
- Valid SFTP config files for both source and destination servers
---
> Built on [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)
deploy-mcp/Troubleshooting.md
+174
View File
@@ -0,0 +1,174 @@
[← Back to Home](Home)
# Troubleshooting
Common issues and solutions when using deploy-mcp.
## Config File Not Found
**Symptom:** Server fails to start with `Failed to load config from ~/.deploy-mcp.json`.
**Cause:** The config file does not exist or is not valid JSON.
**Solution:**
1. Create `~/.deploy-mcp.json` (see [Configuration](Configuration) for full format):
```json
{
"connections": {
"myserver": {
"host": "server.example.com",
"username": "deploy",
"keyPath": "~/.ssh/id_ed25519",
"remotePath": "/var/www/html",
"localPath": "C:/projects/mysite/src"
}
}
}
```
2. Or set the `DEPLOY_MCP_CONFIG` environment variable to an alternate path.
## SSH Connection Failures
**Symptom:** `deploy_status` returns `FAILED` or upload/download operations time out.
**Cause:** SSH cannot authenticate or reach the server.
**Solutions:**
| Check | Fix |
|-------|-----|
| Host reachable | Verify hostname/IP and port in config |
| Key auth | Ensure `keyPath` points to a valid private key and the public key is in remote `authorized_keys` |
| BatchMode | Connection uses `BatchMode=yes`; password-based auth will fail silently |
| Firewall | Confirm SSH port is open on the remote server |
| ConnectTimeout | The client sets a 10-second connect timeout; check network latency |
Test manually:
```bash
ssh -o BatchMode=yes -i ~/.ssh/id_ed25519 user@host echo ok
```
## Connection Not Found
**Symptom:** `Connection "name" not found. Available: ...`
**Cause:** The `connection` parameter does not match any key in `connections`.
**Solution:**
- Run `deploy_list_connections` to see available names.
- Omit the `connection` parameter to use the default.
- Add the missing connection to `~/.deploy-mcp.json`.
## Upload/Download Failures
**Symptom:** `deploy_upload` or `deploy_download` returns `FAILED: Command failed: scp`.
**Common Causes:**
| Cause | Solution |
|-------|----------|
| Remote path does not exist | Create the directory first: `deploy_remote_exec` with `mkdir -p /path` |
| Permission denied | Ensure the SSH user has write access to the remote path |
| Disk full | Check remote disk: `deploy_disk_usage` |
| File too large | The operation timeout is 120 seconds; very large transfers may exceed this |
## Rsync Sync Failures
**Symptom:** `deploy_sync` returns errors about rsync.
**Common Causes:**
| Cause | Solution |
|-------|----------|
| rsync not installed locally | Install rsync (e.g. `apt install rsync` or via Git Bash on Windows) |
| rsync not installed on remote | Install rsync on the server |
| Trailing slash issues | The tool auto-appends `/` to local paths for content sync |
| `--delete` removes files | This is expected; rsync mirrors the local directory. Use `dry_run: true` first |
Always preview with dry run:
```
deploy_sync(local_path: "./src", remote_path: "/var/www/html", dry_run: true)
```
## Rollback Issues
**Symptom:** `deploy_rollback` fails with `"previous directory does not exist"`.
**Cause:** No previous release directory exists at the specified path.
**Solution:**
1. Use `deploy_backup_before` to create a backup before deploying:
```
deploy_backup_before(remote_path: "/var/www/html")
```
This creates a timestamped copy like `/var/www/html.backup-2026-05-09T12-00-00`.
2. For rollback, provide the correct paths:
```
deploy_rollback(
current_dir: "/var/www/html",
previous_dir: "/var/www/html.backup-2026-05-09T12-00-00"
)
```
The rollback performs an atomic swap: current becomes previous and vice versa.
## Permission Issues
**Symptom:** Deployed files have wrong permissions; site returns 403 errors.
**Solution:**
Use `deploy_permissions` to fix file and directory permissions:
```
deploy_permissions(remote_path: "/var/www/html")
```
This sets:
- Files: `644` (owner read/write, group/other read)
- Directories: `755` (owner full, group/other read/execute)
For web server ownership issues, use `deploy_remote_exec`:
```
deploy_remote_exec(command: "chown -R www-data:www-data /var/www/html")
```
## Joomla Sync Script Not Found
**Symptom:** `deploy_sync_joomla` returns `"sync-joomla.php not found"`.
**Cause:** The `sync-joomla.php` script cannot be located.
**Solution:**
Set `platformPath` in `~/.deploy-mcp.json`:
```json
{
"platformPath": "A:/moko-platform"
}
```
The tool checks these paths in order:
1. `{platformPath}/deploy/sync-joomla.php`
2. `A:/moko-platform/deploy/sync-joomla.php`
## Operation Timeout
**Symptom:** Commands fail after 120 seconds (2 minutes).
**Cause:** The default command timeout is 120,000 ms. Large file transfers or slow networks may exceed this.
**Solution:**
- For large deployments, use `deploy_sync` (rsync) which is more efficient than `deploy_upload` (scp).
- Break large uploads into smaller batches.
- The Joomla sync tool has a longer timeout of 5 minutes (300,000 ms).
---
> Built on [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)
monitor-mcp/Configuration.md
+133
View File
@@ -0,0 +1,133 @@
[← Back to Home](Home)
# Configuration
monitor-mcp loads its configuration from `~/.monitor-mcp.json` (or the path set in `MONITOR_MCP_CONFIG` environment variable).
## Config File Location
| Method | Path |
|--------|------|
| Default | `~/.monitor-mcp.json` |
| Environment variable | `MONITOR_MCP_CONFIG=/path/to/config.json` |
## Config File Structure
```json
{
"defaultConnection": "production",
"connections": {
"production": {
"host": "server.example.com",
"port": 22,
"username": "deploy",
"keyPath": "~/.ssh/id_ed25519"
},
"staging": {
"host": "staging.example.com",
"username": "deploy",
"keyPath": "~/.ssh/id_ed25519"
}
},
"grafana": {
"baseUrl": "https://grafana.example.com",
"apiKey": "glsa_xxxxxxxxxxxx"
},
"sitesJsonPath": "/path/to/sites.json"
}
```
## Top-Level Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `connections` | `Record<string, MonitorConnection>` | Yes | Named SSH server connections |
| `defaultConnection` | `string` | No | Default connection name. Falls back to the first key in `connections` |
| `grafana` | `GrafanaConfig` | No | Grafana instance configuration |
| `sitesJsonPath` | `string` | No | Path to a `sites.json` file for site inventory management |
## Connection Fields
Each entry in `connections` defines an SSH target server.
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `host` | `string` | Yes | — | Hostname or IP address |
| `port` | `number` | No | `22` | SSH port |
| `username` | `string` | Yes | — | SSH login user |
| `keyPath` | `string` | No | — | Path to SSH private key file |
## Grafana Fields
The `grafana` block enables Grafana monitoring tools (`grafana_health`, `grafana_dashboards`, `grafana_alerts`, etc.).
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `baseUrl` | `string` | Yes | Grafana instance URL (e.g. `https://grafana.example.com`) |
| `apiKey` | `string` | Yes | Grafana service account token (Bearer auth) |
Both `baseUrl` and `apiKey` must be present for Grafana tools to activate. If omitted, all Grafana tools return "Grafana not configured".
### Grafana from sites.json
If `sitesJsonPath` is set and the `sites.json` file contains a top-level `grafana` block, monitor-mcp will use it as a fallback when `grafana` is not set directly in the config file.
## sitesJsonPath
Points to a `sites.json` file that defines monitored sites. This enables the `monitor_sites`, `monitor_site_add`, and `monitor_site_remove` tools.
### sites.json Format
```json
{
"grafana": {
"baseUrl": "https://grafana.example.com",
"apiKey": "glsa_xxxxxxxxxxxx",
"dashboardFolder": "Sites",
"dashboardFolderUid": "abc123"
},
"sites": [
{
"name": "mysite-live",
"url": "https://example.com",
"type": "joomla",
"client": "Example Corp",
"joomlaToken": "tok_xxxx",
"akeebaSecret": "secret123",
"tlsVerify": true
}
]
}
```
### Site Definition Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Unique site identifier (e.g. `mysite-live`, `mysite-dev`) |
| `url` | `string` | Yes | Site URL |
| `type` | `string` | Yes | Site type: `joomla`, `dolibarr`, `gitea`, `grafana`, `generic` |
| `client` | `string` | Yes | Client name label |
| `joomlaToken` | `string` | No | Joomla API token |
| `dolibarrToken` | `string` | No | Dolibarr API token |
| `akeebaSecret` | `string` | No | Akeeba Backup frontend secret word |
| `tlsVerify` | `boolean` | No | Verify TLS certificates (default `true`) |
## Minimal Config Example
The simplest valid configuration with a single server:
```json
{
"connections": {
"myserver": {
"host": "192.168.1.100",
"username": "admin"
}
}
}
```
---
> Built on [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)
monitor-mcp/Troubleshooting.md
+149
View File
@@ -0,0 +1,149 @@
[← Back to Home](Home)
# Troubleshooting
Common issues and solutions when using monitor-mcp.
## Grafana Not Configured
**Symptom:** All Grafana tools return `"Grafana not configured"`.
**Cause:** The `grafana` block is missing from `~/.monitor-mcp.json`, or one of `baseUrl`/`apiKey` is absent. Both fields are required for the Grafana client to initialize.
**Solution:**
1. Add the `grafana` block to your config:
```json
{
"grafana": {
"baseUrl": "https://grafana.example.com",
"apiKey": "glsa_your_service_account_token"
}
}
```
2. Or set `sitesJsonPath` pointing to a `sites.json` that contains a `grafana` block (used as fallback).
3. Verify the API key is a valid Grafana service account token with Viewer permissions or higher.
## SSH Connection Failures
**Symptom:** SSH-based tools (`monitor_health`, `monitor_disk`, etc.) fail with timeout or permission errors.
**Cause:** SSH cannot reach the target or authentication fails.
**Solutions:**
| Check | Command | Fix |
|-------|---------|-----|
| Host reachable | `ssh user@host -p port echo ok` | Verify hostname/IP and port |
| Key auth works | `ssh -i /path/to/key user@host echo ok` | Ensure `keyPath` points to valid private key |
| BatchMode works | `ssh -o BatchMode=yes user@host echo ok` | Must not require password prompt; add key to `authorized_keys` |
| Correct port | Check config `port` field | Default is `22`; update if non-standard |
The SSH client uses these options:
- `StrictHostKeyChecking=accept-new` — auto-accepts new host keys
- `BatchMode=yes` — fails immediately if password is required
- Timeout: 30 seconds per command
## sites.json Not Found
**Symptom:** `monitor_sites` returns `"No sites.json configured"`.
**Cause:** Either `sitesJsonPath` is not set in the config, or the file at that path does not exist.
**Solution:**
1. Set `sitesJsonPath` in `~/.monitor-mcp.json`:
```json
{
"sitesJsonPath": "/home/user/sites.json"
}
```
2. Ensure the file exists and is valid JSON with a `sites` array:
```json
{
"sites": []
}
```
3. The path is resolved relative to the working directory unless absolute. Use an absolute path to avoid ambiguity.
## Connection Not Found
**Symptom:** Tool call fails with `Connection "name" not found. Available: ...`
**Cause:** The `connection` parameter refers to a name that does not exist in the `connections` map.
**Solution:**
- Use `monitor_list_servers` to see all available connection names.
- Omit the `connection` parameter to use the default.
- Add the missing connection to `~/.monitor-mcp.json`.
## Config File Not Found
**Symptom:** Server fails to start with `No connections in ~/.monitor-mcp.json`.
**Cause:** The config file does not exist or contains no `connections`.
**Solution:**
1. Create the config file:
```bash
cat > ~/.monitor-mcp.json << 'EOF'
{
"connections": {
"myserver": {
"host": "server.example.com",
"username": "deploy",
"keyPath": "~/.ssh/id_ed25519"
}
}
}
EOF
```
2. Or set the `MONITOR_MCP_CONFIG` environment variable to point to an alternate location.
## Grafana API Errors
**Symptom:** Grafana tools return `Error 401` or `Error 403`.
**Cause:** The API key is invalid, expired, or lacks permissions.
**Solution:**
1. Generate a new service account token in Grafana: **Administration > Service Accounts > Add token**.
2. Ensure the service account has at least **Viewer** role.
3. Update `grafana.apiKey` in the config file.
## Docker Tools Return "Docker not available"
**Symptom:** `monitor_docker` or `monitor_docker_stats` output `"Docker not available"`.
**Cause:** Docker is not installed on the remote server, or the SSH user does not have permission to run `docker` commands.
**Solution:**
- Verify Docker is installed: `docker --version`
- Add the SSH user to the `docker` group: `sudo usermod -aG docker username`
- Or use a connection with a user that has Docker access.
## Command Timeout
**Symptom:** Tools fail with a timeout error after 30 seconds.
**Cause:** The remote command is taking longer than the 30-second timeout (`TIMEOUT = 30_000`).
**Solution:**
- Check network latency to the server.
- For `monitor_logs`, reduce the `lines` parameter.
- For `monitor_processes`, reduce the `count` parameter.
- Verify the server is not under heavy load causing slow SSH responses.
---
> Built on [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)