Updates & upgrades

Vistralio now ships with a dedicated update subsystem.

Use it when you want Vistralio to:

• check whether a newer release exists
• explain blockers or compatibility issues before an upgrade
• apply an update from the WebUI, API, a remote manifest, or a local release bundle

Where it lives

• Admin -> Advanced -> System -> Software updates
• CLI wrapper: scripts/update.sh
• automatic checker:
  • sentinel-update-check.service / sentinel-update-check.timer

Update sources

The updater supports three source modes:

• Latest
  • selects the newest release in the configured manifest for the chosen channel
• Manual
  • loads every release in the configured manifest and lets you choose a specific version
• Local
  • uses packages staged under /var/lib/vistralio/updates
  • supports uploads from the WebUI
  • scans staged file and folder names for Vistralio version numbers when checking availability
  • each new Vistralio build also drops an installable package into /var/lib/vistralio/updates/packages

Local mode is the safest choice when you are testing an unreleased build or doing a one-off staged upgrade from an extracted release directory.

For Manual and Local, Vistralio shows a selectable scrollable version list. That list is intentionally limited to:

• any higher version than the one currently installed
• builds from exactly one semantic version lower

Each packaged release also refreshes:

• /root/sentinel/installers/ for operator-facing install/update entrypoints
• /root/sentinel/versions/<version>/ for versioned source snapshots
• /var/lib/vistralio/updates/packages/ for local update testing as if the build had been downloaded onto a customer system

CLI usage

From an extracted or checked-out release tree:

cd /root/sentinel
sudo ./scripts/update.sh

The script will:

1. ask which source mode you want
2. inspect the installed version
3. inspect the selected target release
4. run compatibility and preflight checks
5. tell you about blockers, warnings, and what to do next
6. only queue/apply the update if the checks pass

Compatibility checks

The updater checks more than just the version number. It also checks things like:

• whether the selected version is actually newer
• whether the install/config files exist
• whether enough disk space is available
• whether the current services are healthy
• whether a SQL backup can be taken automatically
• any release-specific compatibility rules from the manifest

Example: legacy pre-0.1.0 builds are intentionally blocked from jumping straight into managed remote updates. The updater tells the operator to first run a one-time Local upgrade from an extracted 0.1.0+ release bundle.

Automatic daily checks

The update checker runs daily via:

• sentinel-update-check.timer
• sentinel-update-check.service

The timer writes machine-readable status to Vistralio's update state so the WebUI can show:

• installed version
• last checked target
• whether an update is available
• blockers
• warnings
• last apply status

WebUI permissions

The update controls are permission-gated:

• system.update.view
• system.update.check
• system.update.apply

settings.admin can also use the updater.

Update manifest format

Remote updates are driven by a JSON manifest. A release entry should look like:

{
  "latest_version": "0.1.0 (Beta) Build 20260415.6",
  "releases": [
    {
      "version": "0.1.0 (Beta) Build 20260415.6",
      "channel": "beta",
      "released_at": "2026-04-15T12:00:00Z",
      "download_url": "https://updates.example.com/sentinel-0.1.0-build-20260415.6.tar.gz",
      "sha256": "0123456789abcdef...",
      "compatibility": [
        {
          "code": "legacy-bridge",
          "severity": "block",
          "from_max": "0.0.8 (Beta) Build 20260413.2",
          "message": "This release needs a staged local upgrade first.",
          "resolution": "Download the release bundle onto the host and run scripts/update.sh in Local mode."
        }
      ]
    }
  ]
}

Notes

• The updater still uses scripts/install.sh underneath to perform the real installation work.
• install.sh remains the low-level installer.
• update.sh is the operator-facing wrapper for staged upgrades and release selection.
• For local build/release workflows, Vistralio now also prepares:
  • /root/sentinel/installers/ for the current installer entrypoints and tarball
  • /root/sentinel/admin-installers/ for admin-only/internal installers that must not be published in customer downloads
  • /root/sentinel/versions/<version>/ for a versioned source snapshot
• The local update shelf under /var/lib/vistralio/updates is trimmed automatically. Vistralio keeps the current semantic version plus the three previous semantic versions, ignoring build numbers for that cleanup rule. If you need something older, you can still upload or place it there manually later.