Updating Qisutu

Always extract a new release into a separate directory. Do not copy it over the existing installation or extract it directly there. The new update.sh then updates exactly the instance supplied as its argument.

Preparation and backup

Before every update, create and verify a complete backup. It must include at least:

  • The complete instance directory, especially core/config/QisutuConfig.pm

  • var/secure/security.key

  • The database

  • Custom Apache, proxy, TLS, and systemd changes

  • External attachments or connected storage locations, where applicable

security.key is essential for recovering encrypted email, OAuth, and two-factor secrets. Store it securely with the matching instance backup.

Prepare the new application package

Extract the Qisutu 2.0.2 application package into a separate temporary directory, not into the running instance. Then open the extracted directory containing update.sh. The example uses the layout documented in INSTALL.md; adjust the path to your actual extraction location.

cd /tmp/qisutu-neue-version/qisutu

Starting the update

Production instance:

sudo ./update.sh /opt/qisutu

Additional instance:

sudo ./update.sh /opt/qisututest

The updater reads var/install/instance.conf and displays the installation path, instance identifier, web path, database, and systemd service before asking for confirmation. Cancel if any of these values does not belong to the intended instance.

Update process

The script performs the following steps, among others:

  1. Verifies release checksums, versions, the schema file, Perl syntax, and program registration.

  2. Optionally creates an additional database dump. Check the available space under /var/backups first.

  3. Enables maintenance mode, stops the instance-specific daemon, and blocks new email retrieval.

  4. Updates all application files managed by the release; adds new files and removes managed files that are no longer published.

  5. Preserves local instance files, configurations, logs, runtime data, and the security key.

  6. Reconciles the database schema and runs all SQL and Perl migrations that have not yet been recorded.

  7. Verifies the target state again and starts the daemon.

Post-update checks

After successful completion, run:

systemctl status qisutu-daemon.service
journalctl -u qisutu-daemon.service --since today

Then sign in, check the displayed Qisutu and database versions, and test at least sign-in, the ticket view, email retrieval, and email delivery. If there are multiple instances, perform these checks separately for every updated instance.

Failed update

Do not restart the script repeatedly without first identifying the cause. Save the output and logs, then check free storage, database access, file permissions, and service status. If the state is unclear, restore the previously verified complete backup of the application directory and database together.

Upgrading to 2.0.2

Application and database versions become 2.0.2; the internal add-on API remains 1.0. Schema synchronization adds internal chat, ticket presence, report schedules with recipients and delivery logs, service-to-CI relationships, FAQ attachments and the optional process template reference on forms. These additions do not delete existing data.

Use update.sh from the new application package for the explicitly selected instance. Updating these Sphinx source files or running build-all.bat does not update the Qisutu application or its database.

The updater does not create an automatic program backup. A complete backup of the instance and database, including var/secure/security.key, must exist beforehand. If an error occurs after changes begin, maintenance mode remains active. Resolve the reported cause and rerun the same update; do not overwrite isolated program or database files indiscriminately.

Afterwards, check versions, login, email retrieval, chat and handover, report delivery, an FAQ download and service-to-CI assignments. Check a form process only when KimProcesses is actually installed and enabled.