Guides
MokonyxBackup Backup Before Update
- Details
- Category: Guides
- Applicable Software: MokonyxBackup
- Min Version Number: 01.00.01
- Max Version Number: Not Applicable
Update Joomla and your extensions without holding your breath. MokonyxBackup takes a fresh, full-screen backup before any core update, install, update or uninstall — on its own page with a real progress bar, never synchronously inside the update request — then hands control back so the action continues. If the backup fails, the action is blocked.
Overview
MokonyxBackup can automatically run a full-screen backup before Joomla changes anything — before a Joomla core update, before an extension install, before an extension update, and before an extension uninstall. The backup runs on its own dedicated full-page screen, shows a real progress bar, and then hands control back to Joomla so the original action continues.
The design goal is safety without white-screens: no backup ever runs synchronously inside the core update request. Running a large-site backup inside the update request is exactly what white-screened sites in earlier approaches, so the core-update flow always redirects to the standalone backup screen first.
These pre-action backups are gated on the execution-tuning wizard. While the wizard is pending (MokonyxBackup flags it after an install so it can measure the host's real limits), the pre-update, pre-install and pre-uninstall backups do not run — and a skipped pre-action backup is never silent: MokonyxBackup raises an admin warning and writes a mokonyxbackup log entry stating that the action continued without a backup. Note: with the wizard pending, updates and installs proceed unprotected until it is run. Running the execution-tuning wizard (in Components > MokonyxBackup > Options) restores these backups.
Pre-Install Backup (with Opt-Out)
In addition to the pre-update backup, MokonyxBackup can take a backup before an extension install, giving you a fresh restore point in case a new extension damages the site. Because installs are routine, the pre-install backup is presented as an opt-out checkbox on the Install screen (System > Install > Extensions): the “back up before installing” checkbox is offered right where you upload the package, and you can untick it to skip the backup for that install. This sits alongside the existing pre-update and pre-uninstall opt-outs and uses the same full-screen backup flow.
While the execution-tuning wizard is pending, the pre-update, pre-install and pre-uninstall opt-out checkboxes are suppressed — you can't disable a pre-action backup or run a manual one until the wizard has been run.
Turning It On
Configure under Components > MokonyxBackup > Options > Pre-Action:
| Option | Param | Default | Covers |
|---|---|---|---|
| Backup before update | backup_before_update | No | Joomla core updates and extension updates |
| Backup before install | backup_before_install | No | Extension installs (with a per-install opt-out checkbox on the Install screen) |
| Backup before uninstall | backup_before_uninstall | No | Extension uninstalls (Extensions > Manage) |
The backup runs with the component's default profile (default_profile, defaults to profile 1). These features are Super User only — a non-super-user updating or installing an extension is never intercepted. Pre-update is owned by the System plugin via the component options above; there is no separate per-plugin “before update” toggle.
One Backup Per Update Action
A pre-action backup fires once per Install/Update/Uninstall action, not on a timer. A per-request dedupe guard means a batch update backs up only once, and a one-shot skip flag prevents the client-side and server-side paths from duplicating each other — while the next distinct action still backs up again. The core-update path uses its own session key so it never suppresses extension backups.
How It Works — Joomla Core Updates
For a core update the plugin intercepts server-side (in onAfterRoute) at the last moment before any files change:
- The Install the update click is matched on the confirm/updating page.
- The browser is redirected to the full-screen backup screen (
view=runbackup) with a validatedreturnurlback to the update page. - The backup runs on its own page.
- On return, a small injected script auto-ticks Joomla's "I have taken a backup" checkbox and clicks Install, so the update continues automatically instead of stopping for a second manual click.
How It Works — Extension Installs / Updates / Uninstalls
Extension install/update/uninstall are POST actions carrying a CSRF token and (for update/uninstall) a checked selection, so this path is handled client-side by the plugin's installer-backup.js, injected on Extensions > Install, Extensions > Update and Extensions > Manage. In Joomla 6 the toolbar buttons are web components, so the script uses a capture-phase click listener that runs before the toolbar's own handler:
- Intercept the Install/Update/Uninstall action and, for update/uninstall, capture the checked selection into
sessionStorage. - Send the browser to the full-screen backup screen with a validated
returnurl. - The backup runs, then returns to the original page.
- Resume — the script restores the selection and re-fires the action so the real POST proceeds. In Joomla 6 the click handler is bound to the inner button (not the outer
taskwrapper), and a list-selection button starts disabled untilboxcheckedfires a change event — the script handles both so the action actually submits. While the action runs, a full-screen “now running — please wait” overlay is shown so you know it is working. The overlay leads with a prominent amber warning triangle above the spinner, reinforcing “do not close this window until the update finishes”.
A server-side fallback still exists for the extension path; when it runs synchronously it raises PHP limits and sets ignore_user_abort(true) so a large-site backup can't exhaust the request. If the client-side redirect can't be built, the script bails without preventing the click, so Joomla's own action proceeds normally.
The Full-Screen Backup Screen
view=runbackup is the shared full-page screen used by both the pre-action flow and the dashboard Backup Now:
- Auto-starts the stepped backup over AJAX with a full-bleed, Atum-coloured progress bar on a black backdrop.
- While the backup runs it shows a prominent “do not close this window or switch to another window” warning and a Cancel button. Cancelling requires a double confirmation; on confirm it stops the backup, cancels the record, and returns to the dashboard without continuing any pending action.
- The
returnurlis validated to block open-redirect /javascript:XSS — only a same-host absolute URL or a root-relative path is accepted. - Pre-action flow: the screen shows an “Automatically continue when the backup finishes” checkbox, ticked by default. Checked → hands straight back to Joomla and the action continues seamlessly; unticked → stops on a completion panel with a View backup record link (opens in a new window) and a Continue button.
- Manual Backup Now: shows a View backup record button and Back to dashboard.
- On failure the action is blocked. The pre-action screen offers only Retry or Back to dashboard — never “continue without backup” — so a broken backup can never let the install/update proceed unprotected.
Notifications
Every pre-action backup surfaces its outcome in the admin as an enqueued message — success, warning, or failure — so a successful pre-action backup is visible, not just failures. A pre-action backup that did not run at all (the tuning wizard is pending, a preflight check failed, the profile is missing, or the run threw) is announced just as loudly: an admin warning plus a mokonyxbackup log entry stating the action continued without a backup.
- Hits: 14
MokonyxBackup Backup Profiles & Types
- Details
- Category: Guides
- Applicable Software: MokonyxBackup
- Min Version Number: 01.00.01
- Max Version Number: Not Applicable
Backup profiles let each site tailor exactly what gets captured and how. Choose from full, database-only, files-only or differential backup types, then fine-tune archive format, sanitization, filters, extension exclusions, retention and off-site destinations — all per profile. Here's how the profile tabs and default settings fit together.
Backup Types
Set on the profile's General tab (default full):
| Type | Database | Files | Use Case |
|---|---|---|---|
| Full | Yes | All files | Complete site snapshot |
| Database Only | Yes | No | Quick DB backup before changes |
| Files Only | No | All files | Code/media backup |
| Differential | Yes (full) | Changed only | Fast daily backups between weekly fulls |
Default Backup Directory
Out of the box the default backup directory is now one level above the web root (a sibling of public_html) so that backup archives are not web-accessible. You can still point a profile anywhere — including inside the web root — but the safe out-of-box location keeps archives off the public site by default. Paths support placeholders and are created automatically at backup time.
Default Profile
The component-wide default profile (Options > General, defaults to profile 1) is what runs when a trigger doesn't name a specific profile — including the pre-update / pre-uninstall full-screen backup, the dashboard Backup Now screen, and a web-cron call with no profile_id.
Profile Tabs
- General: title, description, backup type
- Archive: format (
zip,tar.gz,7z), compression level, split size, backup directory, archive name format, Include restore script (None / Inside the archive / Outside as a sidecar), encryption password - Sanitization: scrub the DB dump — sanitize passwords (with preserve super admin), sanitize emails, sanitize sessions
- Filters: exclude directories, files (glob wildcards, e.g.
*.bak), and database tables - Extensions: exclude specific installed extensions from the backup, plus Exclude Development-Version Extensions (see below)
- Retention: per-profile overrides of the global cleanup age/count (a value of
0falls back to the global default) - Notifications: email recipients, notify user groups, notify on success/failure, plus ntfy topic/server/token
New profiles are pre-populated from the component-wide Profile Defaults (default archive format and the sanitization toggles) in Options; existing saved profiles are loaded unchanged.
Exclude Development-Version Extensions
The Extensions tab includes an Exclude Development-Version Extensions toggle. When enabled, it automatically detects every installed extension on a development or pre-release version — a version tagged -dev, -alpha, -beta or -rc — and strips it from the backup (both its files and its Joomla registry rows), in addition to any extensions you pick manually in the same tab. This is ideal for producing a clean, production-safe archive from a dev or demo site so it can be restored onto production without carrying in-development builds.
Execution Tuning
How a backup is paced into steps (files per step, seconds per step, upload chunk size) is controlled by host-wide Execution Tuning options rather than per-profile settings, and a wizard sets them for you by probing the host. After a fresh install the tuning wizard must be run before interactive backups are allowed (it stays pending across updates until you run it). See MokonyxBackup Execution Tuning.
Remote Destinations
Off-site upload is configured per profile with remote destinations (SFTP, FTP, S3, Google Drive, or a Local folder). There is no longer a separate “keep local copy” option — a Local destination IS the local copy: add one to keep the archive on this server, omit it to have the local archive removed after upload. See Remote Storage.
Differential Backups
Compares the current filesystem against a manifest from the last full backup; only new/modified files are included, while the database is always fully dumped. Falls back to a full backup if no base manifest exists.
- Hits: 16
MokonyxBackup Execution Tuning
- Details
- Category: Guides
- Applicable Software: MokonyxBackup
- Min Version Number: 01.00.01
- Max Version Number: Not Applicable
Every host paces a backup differently, so MokonyxBackup ships a tuning wizard that probes your server — PHP limits, disk speed, site footprint — and sets the host-wide step values for you. It's required after a fresh install: until you run it, both interactive backups and pre-action (before update/install/uninstall) backups stay gated, while automated backups and updates themselves keep running.
Overview
Every host is different — PHP time limits, memory ceilings, disk speed and site size all affect how a stepped backup should be paced. Execution Tuning is a set of host-wide component options that control how MokonyxBackup breaks a backup into steps, plus a Run tuning wizard that probes the host and fills those values in for you. Get tuning right and large sites back up reliably on shared hosting without timing out; leave it wrong and a backup can stall or die mid-step.
These are host-wide component options, not per-profile or per-destination settings — they apply to every profile and every destination on the site, and both backup engines consume them. Find them under Components > MokonyxBackup > Options > Execution Tuning.
The Tuning Values
| Option | Controls | Out-of-box default |
|---|---|---|
| Files per step | How many files are packed into the archive in a single AJAX step before the engine returns and continues on the next request | 100 |
| Seconds per step | The wall-clock budget for one step — the engine stops the current step and yields once this many seconds have elapsed, keeping each request comfortably under the host's execution limit | 10 |
| Upload chunk size (bytes) | The size of each chunk streamed to remote destinations (resumable/multipart uploads) | 2 MB (2097152) |
| “Inside” wrapping viable | Whether wrapping the restore script inside the archive (the sidecar-free delivery mode) is fast enough on this host to be recommended | Yes/No, set by the wizard |
A value of 0 for any numeric field means engine auto — the backup engine picks a value at run time rather than using a fixed number. The conservative out-of-box defaults (100 files/step, 10 seconds/step, 2 MB chunk) are deliberately safe for the lowest-common-denominator shared host until the wizard measures the real one.
The Tuning Wizard
The Run tuning wizard button sits on the Execution Tuning options screen. When you run it, it probes the actual host and the site's file footprint, then writes the measured values back into the tuning options. It measures:
max_execution_time— the host's configured PHP time limit.- Whether
set_time_limit(0)sticks — some hosts silently ignore attempts to lift the time limit; the wizard checks whether it actually takes effect, which determines how aggressive the per-step budget can be. memory_limit— the PHP memory ceiling.- A disk I/O benchmark — a short read/write test to gauge how fast the filesystem is.
- The site's file footprint — via a
FileScannerpass, how many files and how much data a full backup would have to process.
From those measurements it fills Files per step, Seconds per step, Upload chunk size, and decides whether “Inside” wrapping is viable on this host. Because the values are host-wide, you only need to run the wizard once per site (and again after a hosting change).
The wizard's suggestions are not saved until you Save. When the probe finishes, the values are filled into the fields client-side and the result box appears as an orange warning reading “Not saved yet — click Save (or Save & Close) to apply these tuning values.” Saving persists the values and clears the pending flag; navigating away without saving discards them.
A Reset tuning wizard button sits next to Run tuning wizard. It re-arms the wizard on demand — resetting the tuning values to their defaults and re-setting the pending flag — without reinstalling the component, so the gate and post-install behaviour can be re-tested against a fresh state.
The Wizard Is Required After a Fresh Install
On a fresh install of MokonyxBackup, a flag is set marking the tuning as pending. (Because the wizard measures host capabilities, which an extension update does not change, it is not re-armed on every update — a never-tuned site stays gated across updates until the wizard is actually run, and a genuine host change is handled by the Reset tuning wizard button.) Until you run the wizard and clear that flag:
- Interactive (UI) backups are blocked. The run-backup screen shows a modal telling you to run the tuning wizard first, the Dashboard shows a reminder that links to the wizard, and the Backup Now button is disabled.
- Pre-action backups do not run at all. Pre-update, pre-install, and pre-uninstall backups are gated too — while the flag is set, no safety backup is taken before an update, install, or uninstall. Each time one is skipped, MokonyxBackup raises an admin warning and writes a matching entry to the
mokonyxbackuplog stating the action continued without a backup, so it is never silent. The “skip pre-update / pre-install” opt-out checkboxes are hidden while the flag is set, since there is nothing left to opt out of. - Unattended backups keep running. Scheduled tasks, web-cron, CLI, and API-triggered backups are not blocked — they continue on the current (or conservative default) values, so your unattended protection is never interrupted.
- Updates are never blocked. The pending-tuning flag gates backups, not updates — you can still install and update extensions and Joomla core.
While the wizard is pending, updates and installs proceed with no pre-action backup. This is a deliberate, accepted trade-off: rather than back a site up on unverified host limits, MokonyxBackup takes no backup and says so loudly (admin warning + mokonyxbackup log entry). If you are about to update or uninstall something important, run the wizard first.
Running the wizard clears the flag, which unblocks interactive backups, restores pre-action backups, and dismisses the reminder.
Managed-Site Reporting
The pending state is surfaced to fleet management. The backup heartbeat reports a tuning_pending status, and MokonyxHQ flags any managed site whose tuning wizard has not yet run — so an administrator managing a fleet can see at a glance which sites still need tuning.
Recommended Workflow
- Install MokonyxBackup.
- Open Components > MokonyxBackup > Options > Execution Tuning.
- Click Run tuning wizard and let it probe the host.
- Review the values it filled in (adjust manually if you have a reason to), then Save — the orange “Not saved yet” notice will clear once you do.
- Interactive and pre-action backups are now unblocked — run a manual backup to confirm.
Documentation
Full documentation is on the MokonyxBackup Wiki.
- Hits: 19
MokonyxBackup Notifications
- Details
- Category: Guides
- Applicable Software: MokonyxBackup
- Min Version Number: 01.00.01
- Max Version Number: Not Applicable
Never wonder whether last night's backup ran. MokonyxBackup sends per-profile success and failure alerts over email and ntfy push, targeting individual addresses or whole Joomla user groups — with rich run details and, on failure, the tail of the backup log to help you diagnose fast.
Overview
MokonyxBackup can send notifications when backups complete or fail, over both email and ntfy push. Notifications are configured per profile, giving you fine-grained control over who gets notified and when. Component-level defaults fill in any field a profile leaves blank.
Configuration
Open a backup profile and go to the Notifications tab:
| Field | Description |
|---|---|
| Notification Email | Comma-separated email addresses to receive notifications |
| Notify User Groups | Select Joomla user groups — all members will receive notifications |
| Notify on Success | Send when a backup completes successfully (default: No) |
| Notify on Failure | Send when a backup fails (default: Yes) |
| ntfy Topic / Server / Token | Optional ntfy push: topic, server (default https://ntfy.mokoconsulting.tech), and access token |
Email addresses and user group members are combined. Duplicate addresses are automatically filtered.
Global Defaults and Inheritance
Component-wide defaults live in Components → Backup → Options, on the Notifications tab — which now also contains the ntfy push settings (server, topic, token) that previously had their own section. You can set a default notification email, notify-on-success and notify-on-failure, and ntfy server, topic, and token there.
These defaults are applied per field: when a profile leaves a notification or ntfy field blank, it inherits the component-level value; when a profile sets its own value, that value is used instead. Inheritance applies to both backup-completion notifications and restore/snapshot notifications.
Email Content
Subject Line
[MokonyxBackup] SUCCESS: Daily Full Backup — My Joomla Site
[MokonyxBackup] FAILED: Daily Full Backup — My Joomla SiteEmail Body Includes
- Site name and URL
- Backup status (success/failure)
- Profile name and backup type
- Backup description and origin (backend, CLI, scheduled, web cron)
- Archive filename and total size
- Duration, start time, and end time
- Remote filename (if uploaded to SFTP/FTP/S3/Google Drive)
- File count and table count
On failure, the last 30 lines of the backup log are appended to help diagnose the issue.
Tips
- For critical production sites, enable Notify on Failure and add the site admin's email or an ntfy topic
- Use user group notifications to automatically include new team members
- Set a notification email and ntfy topic once in the component Options and leave those fields blank on individual profiles to have every profile inherit the same recipients
- Notification errors are logged but never block the backup process — a failed email won't cause a backup failure
- Hits: 16
MokonyxBackup Placeholders
- Details
- Category: Guides
- Applicable Software: MokonyxBackup
- Min Version Number: 01.00.01
- Max Version Number: Not Applicable
Make your backup paths and filenames dynamic and portable. Placeholders like [HOST], [DATETIME], [PROFILE_NAME] and [DEFAULT_DIR] are resolved at backup time in your backup directory, archive name format, and remote destination paths — so one profile works across servers without hard-coded paths.
Overview
Placeholders are tokens enclosed in square brackets that are resolved at backup time. Use them in the Backup Directory and Archive Name Format fields of a backup profile, and in the destination path fields — the Local destination path, the S3 Path Prefix, and the Google Drive Subfolder Path — to create dynamic, portable paths and filenames.
Available Placeholders
| Placeholder | Resolves To | Example |
|---|---|---|
[HOST] | Server hostname (sanitised) | www.example.com |
[SITE_NAME] | Joomla site name (sanitised) | My-Joomla-Site |
[DATE] | Date as Ymd | 20260607 |
[TIME] | Time as His | 143025 |
[DATETIME] | Date and time as Ymd_His | 20260607_143025 |
[YEAR] | Four-digit year | 2026 |
[MONTH] | Two-digit month | 06 |
[DAY] | Two-digit day | 07 |
[HOUR] | Two-digit hour (24h) | 14 |
[MINUTE] | Two-digit minute | 30 |
[SECOND] | Two-digit second | 25 |
[PROFILE_ID] | Backup profile ID | 1 |
[PROFILE_NAME] | Profile title (sanitised) | Daily-Full |
[TYPE] | Backup type | full, database, files, differential |
[RANDOM] | Random 6-character hex string | a3f2b1 |
[DEFAULT_DIR] | Default backup directory (from the component's Default backup directory option) | /home/user/backups |
[HOME] | Home directory of the PHP process owner | /home/user |
Where Placeholders Resolve
Placeholders are resolved in the profile's Backup Directory and Archive Name Format fields, and in the path fields of remote destinations:
- Local destination path — run through the same resolver as the profile's backup directory. Tokens such as
[HOME]and[HOST]in a local destination path are expanded to their real values at backup time. Previously these were treated literally, which created folders with the literal bracketed names (for example a directory called[HOME]) inside the web root — that no longer happens. - S3 Path Prefix — the object-key prefix (e.g.
[HOST]/backups) is resolved before use, so a value like[HOST]/backupsbecomes a real folder in the bucket rather than a literal[HOST]key. Because this is an object-key prefix and not a filesystem path, the[DEFAULT_DIR]/ relative-path handling does not apply to it. - Google Drive Subfolder Path — the subfolder path (e.g.
[HOST]/[YEAR]) is resolved, and each/segment is found or created under the configured Drive folder (or your Drive root); the deepest folder holds the uploaded file.
Each placeholder-enabled field shows a clickable Insert: legend of placeholder pills — click a pill to insert that token at the cursor.
Note: remote destination paths (Local, S3, Google Drive) resolve environment tokens — [HOST], [SITE_NAME], [HOME], [DEFAULT_DIR], and the date/time tokens. The per-backup tokens ([PROFILE_ID], [PROFILE_NAME], [TYPE], [RANDOM]) are intended for the profile's Archive Name Format and are not meaningful in a destination path.
Examples
Archive Name Format
Default: [HOST]_[DATETIME]_profile[PROFILE_ID]
Result: www.example.com_20260607_143025_profile1.zip
Custom: [SITE_NAME]_[TYPE]_[DATE]_[RANDOM]
Result: My-Joomla-Site_full_20260607_a3f2b1.zip
Backup Directory
Default: [DEFAULT_DIR] (resolves to the folder set in the component's Default backup directory option — out of the box, a backups folder one level above the web root)
Outside web root: /home/user/backups/[HOST]/[YEAR]/[MONTH]
Result: /home/user/backups/www.example.com/2026/06/
Organised by profile: /var/backups/joomla/[PROFILE_NAME]
Result: /var/backups/joomla/Daily-Full/
Local Destination Path
Sibling of the web root, per host: [HOME]/backups/[HOST]
Result: /home/user/backups/www.example.com/
S3 Path Prefix
Per host: [HOST]/backups
Result (bucket key prefix): www.example.com/backups
Google Drive Subfolder Path
Per host and year: [HOST]/[YEAR]
Result (folders created under the configured Drive folder): www.example.com/2026
Notes
- Placeholders are resolved at backup time — the directory is created automatically if it doesn't exist
- The
[DEFAULT_DIR]placeholder reads the component's Default backup directory option, making profiles portable across different server paths - On CLI/cron there is no HTTP host, so set the site's live_site (with scheme) in Global Configuration to get the correct
[HOST]in archive names - Directory paths containing unresolved placeholders skip permission checks in the dashboard (they can't be validated until backup time)
- Sanitisation removes special characters, keeping only alphanumerics, dots, hyphens, and underscores
- Hits: 19