AuraBoot
Start free
English简体中文

Upgrade

AuraBoot is under active development. Upgrades between 0.x versions may include schema migrations, DSL contract changes, and new mandatory configuration. Following the procedure below keeps the upgrade boring.

Versioning

The release line is MAJOR.MINOR.PATCH (the current main-line version is 1.0.0-SNAPSHOT). Within a MAJOR.MINOR line, upgrades are backwards-compatible aside from documented breaking changes in the release notes. Crossing a MAJOR boundary may require manual migration steps.

When to use

  • Adopting a new feature shipped in a later release.
  • Pulling a security fix.
  • Coming back to a stale environment that has fallen multiple releases behind. Upgrade one minor at a time; do not jump.

Pre-upgrade checks

# 1. Snapshot the current version
curl -sS "$AURA_API_URL/actuator/info" | jq .build.version

# 2. Health must be UP across all nodes
for n in app-1 app-2 app-3; do
  curl -sS "https://$n/actuator/health" | jq -r '.status'
done

# 3. Full backup (see operations/backup-restore)
./scripts/backup.sh --tag pre-upgrade-$(date +%Y%m%d)

# 4. Confirm no in-flight long-running jobs (first inventory the enabled automation rules)
curl -sS "$AURA_API_URL/api/automations?enabled=true" \
  -H "Authorization: Bearer $AURA_TOKEN" | jq '.data.total'

A pre-upgrade backup is mandatory. The pg_dump, DSL export, and MinIO mirror together let you roll back without data loss.

Migration order

Migrations must apply in this order. Skipping or reordering steps causes the classic "menu missing" or "permission denied" symptom on first login.

  1. Stop traffic to the application nodes (drain via load balancer).
  2. Stop application processes on all nodes.
  3. Upgrade the platform binary (jar) on each node.
  4. Run database migrations. The bundled Flyway/Liquibase script is invoked automatically on first boot; for staged environments invoke reset-and-init.sh only on clean environments, never on production.
  5. Boot one application node with --spring.profiles.active=community (the deployment-side production profile; Docker / Kubernetes use the same). Watch the logs to confirm BootstrapStartupRunner is absent (no startup-time writes) and that plugin import completes.
  6. Verify health before booting the remaining nodes.
  7. Boot remaining nodes one at a time.
  8. Reopen traffic at the load balancer.
# Single-command-per-step upgrade on one node
systemctl stop auraboot
cp /downloads/platform-1.0.1.jar /opt/auraboot/platform.jar
systemctl start auraboot
journalctl -u auraboot -f | grep -E "Started|migrated|imported"

For clean environments (CI, fresh staging) the supported entry point is:

yes y | ./scripts/reset-and-init.sh   # OSS
# or
yes y | ./scripts/oss-reset-and-init.sh

reset-and-init.sh is the only sanctioned write path for bootstrap data. Application startup must never repair, backfill, or ensure missing roles, menus, or seed rows.

Breaking changes

The release notes for each minor version call out:

  • New required environment variables.
  • Removed permission codes (replace with the listed successor).
  • DSL schema field renames (e.g. cr_csp_connector_id -> cr_csp_connector_pid).
  • Behavior changes that affect plugin authors.

Read the notes before upgrading. Run aura plugin validate plugins/<each-plugin> against the new platform before importing.

Rollback

If post-upgrade verification fails:

# 1. Stop the upgraded nodes
systemctl stop auraboot

# 2. Restore from the pre-upgrade backup
./scripts/restore.sh --tag pre-upgrade-20260528

# 3. Pin the previous jar
cp /opt/auraboot/platform-1.0.0.jar /opt/auraboot/platform.jar
systemctl start auraboot

Rolling back across more than one minor version is not supported. Restore to the snapshot taken before the failed upgrade.

Verify

  • /actuator/info reports the new version on every node.
  • /actuator/health is UP everywhere and the database migration result is recorded.
  • aura plugin validate passes for every imported plugin.
  • A login plus a representative list page and a representative command both succeed end-to-end.
  • No BadSqlGrammar, DataIntegrityViolation, or references unregistered handler errors appear in the logs for the first hour after upgrade.

Related