Upgrade Guide - openises/tickets GitHub Wiki

Upgrade Guide

How to upgrade TicketsCAD from any previous version to the latest release.

Docker Upgrade (Easiest)

cd ~/ticketscad
docker compose pull
docker compose up -d

Done. The database schema is auto-synced.

Traditional (XAMPP / Apache) Upgrade

1. Backup Your Database

mysqldump -u tickets -p tickets > backup_before_upgrade.sql

2. Download the Latest Release

From https://github.com/openises/tickets/releases

3. Replace Application Files

Extract the new release files over your existing installation. Do not delete these files:

  • incs/mysql.inc.php (your database configuration)
  • uploads/ directory (user attachments)
  • _tile_cache/ directory (cached map tiles)

4. Run the Installer

Open http://your-server/tickets/install.php in your browser.

  • If you're already logged in as admin, the installer loads directly
  • If not, you'll see a "Database Update Required" page — click "Run Upgrade"
  • Select Upgrade mode (not Install/Reinstall)
  • Click Do It

The installer creates any missing tables and syncs column changes.

5. Verify

Log in and check that incidents, users, and settings are intact.

Upgrading from Very Old Versions (3.30 and earlier)

If you're upgrading from version 3.30A or earlier:

  1. Passwords work automatically. The login system now recognizes all legacy password formats:

    • MySQL PASSWORD() hashes (very old versions)
    • MD5 hashes (versions 3.0–3.40)
    • SHA1 hashes
    • bcrypt (current)

    Your existing passwords will work without resetting. On first login, the password is silently upgraded to bcrypt.

  2. PHP compatibility. If you're also upgrading PHP, version 3.44.1+ includes a compatibility layer that supports PHP 7.0 through 8.4+. Functions removed in PHP 8.2+ (like utf8_encode) are automatically polyfilled.

  3. If login fails after upgrade, use the password reset tool:

    http://your-server/tickets/tools/reset-admin-password.php

    Download it from: https://raw.githubusercontent.com/openises/tickets/main/tools/reset-admin-password.php

    Delete this file after use — it allows anyone to reset passwords.

Troubleshooting Upgrades

"Installer step parse error"

This usually means PHP warnings are being output before JSON. Fixed in 3.44.1 — if you see this, re-download the latest files.

"Field doesn't have a default value"

Legacy tables may have NOT NULL columns without defaults. The installer handles this automatically as of 3.44.1.

504 Gateway Timeout

The upgrade may take longer on large databases. Increase your PHP/nginx timeout:

# nginx
fastcgi_read_timeout 300;

# php.ini
max_execution_time = 300

Blank pages on Situation, New, Units, Fac's, Config (MySQL 8.0+)

Error: Expression #22 of SELECT list is not in GROUP BY clause and contains nonaggregated column ... incompatible with sql_mode=only_full_group_by

Cause: MySQL 8.0+ enables ONLY_FULL_GROUP_BY strict mode by default. Legacy queries use SELECT * with GROUP BY, which strict mode rejects.

Fix: Update to the latest code — the fix sets a compatible SQL mode at connection time:

cd /path/to/tickets
curl -L https://raw.githubusercontent.com/openises/tickets/main/incs/db.inc.php -o incs/db.inc.php
curl -L https://raw.githubusercontent.com/openises/tickets/main/incs/functions.inc.php -o incs/functions.inc.php

"Incorrect DATETIME value: ''" (MySQL 8.0+)

Cause: MySQL 8.0 strict mode rejects empty string '' for DATETIME columns. Legacy code uses '' instead of NULL.

Fix: Same as above — the updated connection code disables STRICT_TRANS_TABLES for compatibility.

diagnose.php error: "Unknown column 'key'"

Cause: The settings table uses name as the column name in legacy installations. The diagnostic tool was looking for key.

Fix: Update diagnose.php:

curl -L https://raw.githubusercontent.com/openises/tickets/main/tools/diagnose.php -o tools/diagnose.php

Missing tables (regions, region_types, road_info)

After updating files, run the installer in Upgrade mode:

http://your-server/tickets/install.php

Select Upgrade and click Do It. This creates missing tables without affecting existing data.

White screen after upgrade

Check PHP error log. Most likely cause: PHP 8.2+ removed utf8_encode(). Update to 3.44.1+ which includes the compatibility polyfill.