Private · Upgrade

Upgrades are high-risk. Complete every step in this procedure; if anything goes wrong, roll back.

Pre-Upgrade Checklist

Item	Required
Back up all databases (MySQL / PostgreSQL)	✓
Back up file storage	✓
Read the target version's Changelog	✓
Read incompatible changes (if any)	✓
Fully validate in a staging environment	✓
Pick a low-traffic window	✓
Notify users (if downtime needed)	✓

Backup

MySQL

docker compose exec mysql mysqldump \
  -u root -p --single-transaction --routines --triggers \
  evose > /backup/$(date +%F)-mysql.sql

PostgreSQL (Knowledge base)

docker compose exec postgres pg_dump -U postgres -F c evose_kb \
  > /backup/$(date +%F)-pg.dump

Files

rsync -av /opt/evose/data/files/ /backup/$(date +%F)-files/

Run a local restore drill

A backup that hasn't been verified is no backup at all.

Upgrade Methods

Docker Compose

# Stop the service (if zero-downtime is not required)
docker compose down
 
# Pull the new version
git -C evose-edition pull
# or
tar -xzf evose-edition-NEW.tar.gz
 
# Start
docker compose pull
docker compose up -d
 
# Watch initialization (may include DB migrations)
docker compose logs -f evose-init

Kubernetes (Helm)

# Look up new versions
helm search repo evose --versions
 
# Upgrade
helm upgrade evose evose/evose -n evose -f values.yaml --version <new>
 
# Watch rollout
kubectl -n evose rollout status deploy/evose-api

Database Migrations

evose-init runs schema migrations automatically on startup:

[init] applying migration 20260301_add_credit_balance
[init] applying migration 20260315_add_skill_tags
[init] migrations complete

Large-table migrations may be slow

If your database is > 100GB, some ALTER TABLE may take hours. Test in staging first to estimate the window.

Verification

After the upgrade, run smoke tests:

# 1. Health endpoint
curl https://evose.example.com/health
 
# 2. Log into the admin console
# 3. Trigger an Agent on the Workbench
# 4. Run a Workflow once
# 5. Confirm data in the observability panel
# 6. Test connections on the Model platform

Rollback

If business is broken after upgrading, roll back immediately:

Docker Compose

docker compose down
git -C evose-edition checkout <old tag>
docker compose up -d
 
# Restore DB if needed
docker compose exec mysql mysql -u root -p evose < /backup/<DATE>-mysql.sql

Kubernetes

helm rollback evose -n evose

Incompatible Upgrade (Major Version Bump)

Major version bumps (e.g. 1.x → 2.x) may involve:

Major schema changes
Renamed / removed config items
API field changes

Mandatory:

Run a full pass in staging
Read the Migration Guide (released with the version)
Schedule a formal downtime window
Have a clear rollback plan

Next Steps

HA topology → HA
Security updates → Changelog

Private · Upgrade

On this page