Back up the complete recovery set

A database dump alone is not enough. Preserve the database, application tree, settings.php, encryption hash, .htaccess, attachments, downloads, uploaded media (including assets/media/documents/), custom storage, custom extensions, theme assets, and scheduler configuration together.

Safe release process

  1. Read the changelog.Identify breaking routes, schema changes, manual steps, and runtime requirements. Every release since 1.7.5 has its own page under Release notes.
  2. Create verified backups.Record sizes and checksums, then test that the database dump can be imported.
  3. Clone staging.Use isolated database and storage paths; prevent outgoing customer email.
  4. Deploy files.Preserve local configuration and custom code deliberately.
  5. Apply release data.Use only the release's documented installer or upgrade mechanism.
  6. Test.Authenticate, traverse public/control routes, exercise billing and support, and inspect logs.
  7. Cut over and monitor.Reset caches, restore scheduler traffic, and watch failures and queues.

Recovery priorities

Restore the settings file and encryption hash with the matching database. A mismatched encryption hash can make protected values unreadable. Restore private file stores before testing customer downloads or ticket attachments.

When an upgrade stops on a database error, the full error is in the log. Fix its cause and run the upgrade again: the incremental scripts are written to be safe to re-run. Restore the backup only if you cannot get past it.

Do not stop at 1.9.8.

On some databases the 1.9.8 migration, upgrade198.sql, stopped with "Illegal mix of collations" and left the site on a "Critical Error" page, because the tables and information_schema used different collations. 1.10.0 corrects the script. Update straight to the current release rather than to 1.9.8.

Automatic updates

WBAMS applies releases itself. It asks the license server for the newest release on its channel, receives an expiring download token, fetches the package, checks it against the published SHA-256, verifies every file against the package's own manifest, and only then installs it. The update-check response is a signed envelope: a signature that is present and does not verify is a refusal, and a package with no SHA256SUMS.txt is refused outright rather than installed on the strength of the archive checksum alone.

Every file an update replaces is copied aside first, so a failure part way through restores what was there; files the update created are removed again. When an update cannot finish in the browser, the installer applies the same release: copy the files of the release's fresh-install package over the site and run Upgrade this installation, as Upgrading to 1.12.0 describes, from /install/ or with php -d opcache.enable_cli=0 install/bin/installer.php --upgrade.

From 1.11.0 or earlier to 1.12.0, use the installer.

The update screen of an earlier release cannot give the database the names 1.12.0 uses, so a site below 1.12.0 is upgraded with the release's files and its install/ folder: see Upgrading to 1.12.0. From 1.12.0 on, Update WBAMS works as described here.

One update at a time
Since 1.9.4 a second start of an update while one is running is turned away, and the window follows the update already in progress. Since 1.12.0 the installer's upgrade does the same: a second one stops before it changes anything and says that another upgrade is running. Before, a browser that resent a dropped request could start the same update twice, and the second one reported "The update did not complete" on a site that had in fact updated.
What is left behind
Since 1.9.8 the downloaded package and its unpacked copy are removed when an update finishes, whether it succeeded or not, and a successful update also clears what earlier updates left in the temporary path. One rollback copy is kept: the files the latest update replaced, so they can still be put back by hand.
What an update never touches
settings.php, the site's own root .htaccess, storage/, media/ and assets/media/uploads/. Pictures shipped elsewhere under assets/media/ are added when a site lacks them and never replace the site's own. Add-ons are never removed: an update deletes only files a release lists as obsolete.
An admin area with its own address
Updates keep the admin area at the address settings.php gives it ($customadminpath), so the address the site gave up does not come back. See The admin area's address.
Where the backup lands

Before 1.3.3 the upgrade backup defaulted to dirname(target)/wbams-backups, which on the normal cPanel layout for an addon domain resolves to public_html—a served tree. The default is now the account home, and the directory carries its own deny rule and index guard wherever it lands. Anyone who ran the 1.3.2 upgrade on an addon domain should move public_html/wbams-backups out of the web root.

Upgrading to 1.12.0: use the installer

During the upgrade, the database of an installation from before 1.12.0 is given the current names of its tables, columns and settings, with every row kept. That step belongs to the 1.12.0 installer, so a site on 1.11.0 or earlier is upgraded with the release's files and its install/ folder rather than with Update WBAMS. The installer does not keep a rollback copy: the backup in step 1 is the way back.

  1. Prepare.Back up the database and every file, and check the backup has downloaded completely. If the site takes payments through a gateway 1.12.0 no longer ships, set up one of the twenty it does first. Pick a quiet time: from the moment the new files are in place until the upgrade has run, every page sends visitors to the installer.
  2. Copy the files over the site.Extract the 1.12.0 files into the site's folder, replacing the files there. Keep settings.php, storage/, the uploaded media and the site's own .htaccess. If the admin area has a folder of its own (settings.php names it as $customadminpath), the release's admin pages arrive in control/: delete the site's admin folder and rename control/ to its name.
  3. Bring .htaccess up to date.In the site's .htaccess, replace everything from ### BEGIN - WBAMS protective rules ### to ### END - WBAMS protective rules ### with that block from the 1.12.0 package (if the file has no such block yet, paste it at the top). Leave the managed rules and the lines cPanel wrote for PHP as they are. The 1.12.0 block leaves X-Frame-Options and Referrer-Policy to PHP, so neither arrives twice.
  4. Run the upgrade.Open https://example.org/install/ and choose Upgrade this installation. Confirm that you have a backup and press Start the upgrade once, then wait for its result page. It gives the database its current names, adds the 1.12.0 table behind Possible duplicates, and removes the earlier release's files that 1.12.0 no longer uses, each only when it is exactly as WBAMS shipped it. If it stops because a table exists under both names with rows in each, decide which one holds the site's data and run it again: it finishes what it started.
  5. Read the result page.It lists earlier files kept because they were changed on this site (compare each with your backup, carry any change you still need into the current files, then delete them), files the server's permissions kept it from removing, the add-ons and payment methods 1.12.0 no longer includes (left as they were, and no longer loaded), and this site's own files in folders WBAMS no longer uses. The full log is in install/log/.
  6. Delete install/,then sign in again. 1.12.0 renews every session once, so everyone, administrators included, signs in again after the upgrade, and carts are emptied.

The same day:

  • Payment notices. Payment callbacks are answered in the site’s extensions/processors/callback/ folder. Open Payment Gateways and save Stripe once without changing anything, and Stripe ACH, Stripe SEPA and Stripe Dynamic Payments if they are active: saving registers their notices at that address. Then, in the Stripe Dashboard under Developers › Webhooks, delete the endpoint WBAMS no longer answers. A webhook address typed into a provider's own dashboard, such as Helcim's, has to be changed there.
  • The business's details. Open Setup › Business profile and read what the upgrade brought together, then choose the time zone under General Settings › Localization.
  • Roles. The Content Manager has five new permissions. Roles with Manage Content keep everything they had; give the narrower ones where a role should change only part of the website.
  • Look around. The home page, a client sign-in, the dashboard, a client, an invoice, and System Health, which should show 1.12.0. Within five minutes of the scheduler's next run, Automation Settings shows it as running.

Upgrading to 1.11.0: add the protective rules yourself

1.11.0 ships a root .htaccess whose rules, above the WBAMS markers, turn folder listing off, refuse the package's own files, dot files, dumps, logs and backups, refuse storage/, resources/ and the other folders that are never requested directly, and send the security headers. A fresh install has them. A site updated in place does not, because an update never replaces the site's own .htaccess, and never writes into storage/.

  1. Back upthe site's current .htaccess.
  2. Copy the blockthat sits above ### BEGIN - WBAMS managed rules ### in the 1.11.0 package's .htaccess into the site's own file, also above the markers. Leave the managed rules and any cPanel PHP handler block as they are.
  3. Checkthat https://example.org/PACKAGE-MANIFEST.sha256 and https://example.org/storage/ are now refused (Forbidden, or on some servers the site's own "page not found" page), and that the public site, the admin area and webmail still load.

See Operations and security for what each rule does.

Knowing when a release is out

WBAMS checks for a new release every eight hours through the WBAMS Updates automation task, and whenever someone presses Check Now on Update WBAMS. The first check that finds a release newer than the installed one tells the people who can install it:

  • By email - once per release, to every active administrator whose role has the Update WBAMS permission. The email names the installed and the new version, the release date and its highlights, and links to Update WBAMS. Switch it off under Update WBAMS › Configure Update Settings › New release emails.
  • In the admin area - the notifications bell shows WBAMS 1.13.8 is available (with the real version) at the top of its list, for those same administrators, until the site is updated.

Administrators without the permission are not told, and a release is announced only once however many checks find it. The automation task needs the scheduler running; without it, only Check Now finds new releases.

Version 1.13.8

WBAMS 1.13.8 updates a 1.13.7, 1.13.6, 1.13.5, 1.13.4, 1.13.3, 1.13.2 or 1.13.1 site, or a 1.13.0 site whose server has the ionCube Loader, through Update WBAMS; it needs PHP 8.3 or newer and the free ionCube Loader 15 or newer, and is also available as a clean-install distribution. A site on 1.12.0 comes to 1.13.0 first, whose update screen checks for the Loader; a site on 1.11.0 or earlier comes to 1.12.0 through its installer before that (see above). Read the v1.13.8 release notes and those of every release you are skipping, all listed in the Release history, verify a complete backup, and test the same package in staging before production. 1.12.0 gives an earlier database its current names, keeping every row, and adds the table behind Possible duplicates (upgrade1120.sql); website traffic and text overrides set up their own tables when they are first used. Since 1.7.5 only one release carries a migration file: 1.9.8, upgrade198.sql, which changes how the analytics consent answer is stored. 1.10.0 adds the knowledgebase and download address columns the first time an administrator opens Help Center › Knowledgebase or Downloads, and the menu builder's table the first time Content Manager › Menus is opened. 1.11.0 makes no database change.