Test a HumHub upgrade before your community sees it
A HumHub upgrade changes the database and every module at once, and the members find out in the morning. Trying it first on a copy of the community turns that surprise into a checklist. This guide shows how, on your own server and on CUZY Hosting.
Why an upgrade deserves a test
HumHub releases often: a patch release every few weeks, a minor release a few times a year. A minor release changes the core and the interfaces modules rely on, so a module, a theme or a setting that worked yesterday may behave differently after it. HumHub also migrates its database forward on the first start of a new version, and the previous code cannot read the migrated database: the only way back is the backup taken before the upgrade, which loses everything posted since.
The risk grows with what you added to HumHub: marketplace modules, a custom theme, a module written for your community, single sign-on through Keycloak or Microsoft Entra. A community with the preinstalled modules only rarely meets a problem; one with ten modules and its own theme should look before its members do.
What to check on the copy
Upgrade the copy, then spend a quarter of an hour on what your members actually use:
- Sign in, with a password and with single sign-on if you use it, and once with two-factor authentication.
- The dashboard and two or three busy spaces: the stream loads, posts and comments show, a new post can be written.
- Every module you enabled: open its page, use its main action once (an event in the calendar, a survey answer, a map, a course).
- Your theme: the logo, the colors, the top menu, a page on a phone.
- Administration: Administration → Information shows no error, Administration → Modules lists no module as incompatible.
- What HumHub changed: read the release notes for the lines that concern administrators; the HumHub 1.19 post is an example of that reading.
If something is wrong, note it before upgrading production: it is a module update to wait for, a setting to change, or a question for support.
On a self-hosted HumHub: build a staging server
A staging server is a second installation that you refresh from production before each test:
- a second database restored from the latest dump, and a copy of the
uploadsfolder (or a read-only mount of it, to save disk); - the same HumHub version and the same modules as production, then the upgrade applied to it;
- email switched off or redirected (HumHub's file transport), or members will receive notifications from the copy;
- the API keys of connected services removed (payment providers, maps, single sign-on clients), so a test never charges a card or signs anyone in;
- its address protected (an IP allowlist or HumHub's maintenance mode), and the copy deleted when the test is over, since it holds the personal data of every member.
It works, and it is a second server to keep in step with the first. Most self-hosted communities skip it, which is how upgrades end up tested by the members.
On CUZY Hosting: the testing instance (Business)
On the Business plan, the testing instance is part of the community page of your dashboard:
- Create a testing instance. CUZY makes it from the latest backup of your community, at
<your name>-test.<region>.cuzy.app, in a few minutes. Members are anonymized (only administrators keep their accounts), email reaches administrators only, the credentials of connected services are removed, and the uploaded files of production are shown read-only without being copied. - Upgrade the testing instance. When CUZY offers a new HumHub version, its notification and the upgrade dialog say what changes and what to check. Upgrade the copy: it runs at once.
- Open it and run the checklist above, with your usual administrator password; a banner reminds everyone it is the copy.
- Upgrade production from the same page, the coming night in your region or right away; a backup is taken first. If the copy is missing or behind, the dialog says so before you go on.
The copy has no backup and no monitoring of its own. It is deleted 7 days after its last use, with a notice the day before, and again when the community leaves Business; Recreate from production gives a fresh copy with today's data. The details are in the update and support policy.
On Team the upgrade is the same, offered in the dashboard, a backup first, the version checked by CUZY beforehand, without the copy. Security fixes reach every community usually within 48 hours whatever the plan.
Questions
Do I have to test every HumHub upgrade?
A patch release (1.19.2 to 1.19.3) mostly fixes bugs and rarely needs more than a look at the pages you use. A minor release (1.19 to 1.20) changes features and the modules that depend on them: test it, especially with custom modules, a custom theme or single sign-on.
Can I go back to the previous HumHub version after an upgrade?
Not in place: HumHub migrates its database forward and the older code cannot read it. Going back means restoring the backup taken before the upgrade, which loses what members posted since. That is why testing on a copy first is cheaper than undoing an upgrade.
Is the testing instance included in every CUZY plan?
It is part of Business (€450/month or €4,500/year). On Team, the upgrade itself is the same, a backup taken first and the version checked by CUZY, without a copy to try it on.
Does the testing instance contain our members' personal data?
Only the administrators' accounts are kept as they are. Every other member's name, email address, phone, address and profile fields are replaced, emails reach administrators only, and the copy is deleted 7 days after its last use.