MAIA PlusDocumentation

An existing installation

An upgrade you can control.

Review the plan, confirm the upgrade and verify the result. MAIA-MAINTENANCE manages the signed package, database backup, migrations and service restart.

Signed ZIP packagePreflight before changesPlanned restart

1. Before you begin

  • Schedule a maintenance window and notify users. Upgrading restarts MAIA.
  • Identify the installation directory and service name: for example, C:\MAIA and MAIA, or /opt/maia and maia.service.
  • Review running workflows, schedules and jobs. Allow for downtime; do not assume uninterrupted execution.
  • Prepare a persistent, protected backup directory and space for a database dump and the previous application payload.
  • Ensure pg_dump and pg_restore are available and compatible with the PostgreSQL server version.
  • Download the correct platform package and read its release notes and requirements.
Do not replace executables or WebUI manually

Do not copy new files into current, delete the previous payload or run a fresh installation over a live directory. Upgrade the application through MAIA-MAINTENANCE, not by reinstalling PostgreSQL or the SDP proxy.

2. Download and verify the package

Choose the Windows ZIP or Linux ZIP on the downloads page. Compare the published SHA-256, then extract into a new directory outside the installation, such as D:\MAIA-Releases\1.1.0.

Examples use version 1.1.0. Adjust it to your downloaded package and do not overwrite an earlier release directory. From update, run:

.\MAIA-MAINTENANCE.exe check --package .

This checks the signature and package files without upgrading the application. Keep the JSON/SIG manifests. An invalid signature or modified file is a reason to stop, not to bypass verification.

Hardware without AVX2?

Use MAIA-MAINTENANCE-baseline.exe for every operation. On Linux, use maia-maintenance-linux-baseline. Helper scripts may select the standard runtime; use explicit commands for Baseline.

3. Windows — the guided path

  1. Open the update directory

    Right-click update.bat and choose Run as administrator.

  2. Select the existing installation

    Enter the actual MAIA installation directory and service name. Do not enter the newly extracted package directory as your existing installation.

  3. Read the preflight results

    Preflight checks the service, PostgreSQL, backup tools, migration history and local API without making changes. Continue only after READY TO UPDATE.

  4. Confirm UPDATE

    The updater manages service shutdown, database backup, the new payload and required migrations, then starts the service and checks application health. Keep the log and database dump location.

For a managed service, do not stop it manually or change NSSM settings. No-service mode is for administrators who control the process themselves and have confirmed it is stopped.

PowerShell — explicit preflight and upgrade

Open PowerShell as Administrator and replace the paths with your own. This PostgreSQL 18 example uses tools in bin; your installation may place them elsewhere.

Set-Location "D:\MAIA-Releases\1.1.0\update"

# Verify the package
.\MAIA-MAINTENANCE.exe check --package .

# Preflight: no changes
.\MAIA-MAINTENANCE.exe update `
  --package . `
  --install-root "C:\MAIA" `
  --service "MAIA" `
  --service-driver auto `
  --backup-dir "D:\MAIA-Backups\release-1.1.0" `
  --pg-dump "C:\Program Files\PostgreSQL\18\bin\pg_dump.exe" `
  --pg-restore "C:\Program Files\PostgreSQL\18\bin\pg_restore.exe"

After READY TO UPDATE, repeat the same parameters with --confirm:

.\MAIA-MAINTENANCE.exe update `
  --package . `
  --install-root "C:\MAIA" `
  --service "MAIA" `
  --service-driver auto `
  --backup-dir "D:\MAIA-Backups\release-1.1.0" `
  --pg-dump "C:\Program Files\PostgreSQL\18\bin\pg_dump.exe" `
  --pg-restore "C:\Program Files\PostgreSQL\18\bin\pg_restore.exe" `
  --confirm

Linux / systemd

From the extracted package’s update directory, verify the package and run preflight. Use your actual service name and installation directory.

./maia-maintenance-linux check --package .

sudo ./maia-maintenance-linux update \
  --package . \
  --install-root /opt/maia \
  --service maia.service \
  --service-driver auto \
  --backup-dir /var/backups/maia/release-1.1.0

After READY TO UPDATE, run the confirmed operation:

sudo ./maia-maintenance-linux update \
  --package . \
  --install-root /opt/maia \
  --service maia.service \
  --service-driver auto \
  --backup-dir /var/backups/maia/release-1.1.0 \
  --confirm

If PostgreSQL tools are not on PATH, supply absolute --pg-dump and --pg-restore paths in both commands. For servers without AVX2, use the baseline maintenance executable.

4. Verify the result, not just the version

Windows

Get-Service MAIA
Invoke-RestMethod http://127.0.0.1:3000/api/v1/status

Linux

systemctl status maia.service --no-pager
curl --fail http://127.0.0.1:3000/api/v1/status
  • The service is Running/active and the API returns HTTP 200 with the MAIA status message.
  • WebUI works through the correct public address. Refresh your browser cache if it shows an old view.
  • Login, data, knowledge and AI provider configuration work.
  • Selected workflows pass a deliberate test. Tests may perform real operations.
  • The updater log confirms success, and the backup and previous payload remain available.

Keep previous, the dump and logs until the release is accepted. The version number alone cannot distinguish different builds carrying the same number. Check the package and hashes when in doubt.

What changes, and what stays?

The new application goes into current; the previous payload goes into previous. Persistent configuration, certificates, state and logs remain under the installation root. The updater may apply required migrations, which is why database backup is part of the procedure.

If preflight or upgrade fails

UPDATE BLOCKED — before changes

Resolve the reported cause and run preflight again. Common blockers include missing PostgreSQL tools, insufficient access, a modified package, unverifiable migration history or another process using MAIA’s port. Do not erase migration history or manually replay old SQL scripts.

An interrupted upgrade — preserve the evidence

Keep console output, the database dump, the maintenance log and state\maintenance-update-v2.json. Do not retry UPDATE blindly or attempt to fix the situation by replacing an executable.

Recover an interrupted Windows upgrade
Recovery may restore the database and restart the service

This is recovery for an interrupted upgrade, not a general downgrade after a successful deployment. Review the journal, backup source and possible loss of later changes. If uncertain, contact MAIA Plus at stanislaw.rogasik@maiaplus.eu.

.\MAIA-MAINTENANCE.exe recover `
  --install-root "C:\MAIA" `
  --service "MAIA" `
  --backup-dir "D:\MAIA-Backups\release-1.1.0" `
  --pg-dump "C:\Program Files\PostgreSQL\18\bin\pg_dump.exe" `
  --pg-restore "C:\Program Files\PostgreSQL\18\bin\pg_restore.exe"

Recovery uses the journal and a trusted backup. Verify the final result and application health. Do not delete archives retained after a failed attempt.

Database repair is not a routine upgrade. Use it only after an administrator or DBA determines that the database is damaged or cannot be migrated correctly. Do not run it just to bypass a blocker.

Contact MAIA Plus at stanislaw.rogasik@maiaplus.eu with the version, platform, failed stage and a sanitized log excerpt. Do not send secrets or a full database dump through an ordinary support channel.