Upgrade

1. See what you run

Any of these report the installed package version:

curl -sS https://api.help.example.com/health
cat /var/www/hesk-api/VERSION

On 1.7.0 or newer, staff with settings privilege can also compare against this site:

curl -sS -H "Authorization: Bearer $TOKEN" \
  https://api.help.example.com/v1/updates?refresh=1

/health and VERSION are the install. GET /v1/updates is the install plus the latest version we publish.

2. See the latest we publish

Machine-readable channel (what the updater reads):

curl -sS https://tacticaldataconcepts.com/hesk-api/version.json
curl -sS https://tacticaldataconcepts.com/hesk-api/VERSION

version.json includes the zip URL, SHA-256, this upgrade page, and the install page. If that file is missing, the updater falls back to VERSION plus hesk-api-{version}.zip and hesk-api-{version}.zip.sha256.

Human pages: product · changelog · this upgrade guide.

3. If you are behind — manual upgrade

Use these steps for 1.6.0 or older (no updater yet), or any time you want to apply the zip yourself.

1. Download hesk-api-1.8.0.zip and confirm the SHA-256 above (or the value in version.json).
2. Unpack next to the live tree — do not empty the live directory first.
3. Copy config/config.local.php from the old tree into the new tree if you unpacked to a new directory. Copy anything you added under storage/ the same way.
4. Swap the live path to the new tree (rsync into place is fine). Never copy the example config over config.local.php.
5. From the live tree: php bin/install-schema.php — safe to re-run (CREATE TABLE IF NOT EXISTS).
6. Reload PHP-FPM if opcache is on.
7. Check GET /health — status is ok and version matches the zip you installed.

cd /tmp
curl -fsSLO https://tacticaldataconcepts.com/hesk-api/hesk-api-1.8.0.zip
curl -fsSLO https://tacticaldataconcepts.com/hesk-api/hesk-api-1.8.0.zip.sha256
sha256sum -c hesk-api-1.8.0.zip.sha256

unzip -q hesk-api-1.8.0.zip
sudo rsync -a --exclude 'config/config.local.php' --exclude 'storage/' \
  hesk-api-1.8.0/ /var/www/hesk-api/
sudo -u www-data php /var/www/hesk-api/bin/install-schema.php
sudo systemctl reload php8.3-fpm
curl -sS https://api.help.example.com/health

Adjust the web user, FPM unit, and paths to match the host.

4. Check from the dashboard (1.8.0+)

Sign in at /login with a HESK staff account. The token dashboard (/tokens) and Updates (/updates) both show:

• This install vs Latest on TDC.com
• If an update is available, Upgrade instructions points at this page
• Administrators and staff with HESK “Manage settings” can change how the updater behaves
• Administrators can type APPLY to install the published zip in place (SHA-256 gated)

Dashboard settings are stored in storage/updates/settings.json (kept when a package is applied). config.local.php still works.

5. Check, ticket notify, or auto-install (1.7.0+)

1.7.0 can poll this site. Default is check-only. Ticket notify and auto-install are opt-in.

php bin/check-updates.php
php bin/check-updates.php --notify
php bin/check-updates.php --apply --confirm=APPLY

REST (admin / can_man_settings):

• GET /v1/updates — installed vs latest (?refresh=1 skips cache)
• POST /v1/updates/check — { "notify": true } opens a help-desk ticket if newer
• PATCH /v1/updates/settings — change mode / notify ticket / allow_auto_install
• POST /v1/updates/apply — { "confirm": "APPLY" } installs (admin only)

'updates' => [
    'enabled' => true,
    'channel_url' => 'https://tacticaldataconcepts.com/hesk-api',
    'mode' => 'off',               // off | notify | auto
    'allow_auto_install' => false, // required for unattended --cron auto-install
    'ticket' => [
        'category' => 1,           // required for notify
        'owner' => 1,              // staff id or username; omit = unassigned
        'priority' => 2,
    ],
],

Cron (example, daily 04:15). mode decides check, ticket, or install:

15 4 * * * www-data php /var/www/hesk-api/bin/check-updates.php --cron

Notify tickets include the zip URL, SHA-256, and a pointer to this page. Auto-install stays off until both mode=auto and allow_auto_install=true.

Need a first-time install instead? Install guide →

Safety (every install path)

• HTTPS only, port 443, host allow-list (channel host + allowed_hosts)
• SHA-256 of the zip must match the published checksum — unsigned or mismatched zips are refused
• Zip must unpack as hesk-api-{version}/ with VERSION, src/, public/index.php, config/config.php, bin/install.php
• No path traversal, no symlinks
• Backup zip under storage/updates/backups/ (last 3 kept) on the auto-install path
• Never overwrites config/config.local.php, hesk-api-creds.txt, or storage/
• Refuses downgrade unless allow_downgrade is true and you pass force

Rollback

If auto-install ran, the previous tree is in storage/updates/backups/. Unpack the newest backup next to the live path, copy config.local.php back if needed, point the vhost at public/, reload PHP-FPM, then GET /health.

If you upgraded by rsync, restore from your own backup of the previous directory. The updater never writes over local config; a bad apply should not wipe tokens or settings.

After it is live

• GET /health → version equals the zip you meant to install
• Staff token portal still signs in (/login)
• On 1.8.0+, /updates shows This install matching Latest on TDC.com
• Swagger at /docs still loads this install’s OpenAPI
• A test GET /v1/tickets?limit=1 still returns tickets