Upgrade

Move to a newer Orangescrum release without losing data — and how to roll back if it goes wrong.

Upgrades pull new code and apply database migrations. The order matters, and the backup is not optional.

Back up before every upgrade

Migrations alter the schema in place. If one fails halfway, a restore is the only way back — and rollback in practice means restoring the backup, not reversing the migration. See Backup.

#Before you touch production

Read the release notes
Check for breaking changes and required manual steps. Do not skip this because the last few upgrades were uneventful.
Rehearse on a copy
Restore last night's backup into a scratch instance and upgrade that first. This catches migration failures where they cost nothing.
Pick a maintenance window
Migrations can lock tables. Do it when nobody is working.
Confirm you can roll back
Which means: confirm you have a backup you have actually restored before.

#Docker

Take a full backup
Database dumps, volumes, secrets and compose files.

Pull the new version

bash

cd /opt/orangescrum
git fetch --tags
git checkout <new-version-tag>

Rebuild and restart
bash
```
docker compose pull
docker compose up -d --build
```
Volumes are preserved, so your data and attachments survive the rebuild.

Run migrations

bash

docker compose exec orangescrum-app php bin/cake.php migrations migrate

Clear caches

bash

docker compose exec orangescrum-app php bin/cake.php cache clear_all

Verify
Sign in; load a project, a task detail, the time log and a report. Then check the log:
bash
```
docker compose exec orangescrum-app tail -50 logs/error.log
```

#Traditional install

bash

# 1. Back up the database and webroot/files first.

# 2. New code
git fetch --tags && git checkout <new-version-tag>

# 3. Dependencies and assets
composer install --no-dev --optimize-autoloader
npm install && npm run build

# 4. Migrations
php bin/cake.php migrations migrate

# 5. Caches
php bin/cake.php cache clear_all

# 6. Permissions, if new files were added
sudo chown -R www-data:www-data .

#Supported upgrade paths

The same tooling handles several scenarios:

Path	What happens
V2 → V3	Migrates an existing V2 database with automatic data conversion
Re-install over V3	Re-runs installation against an existing database
V3 → V3 feature upgrade	Applies new feature migrations to a running install

Your package guide is authoritative

Exact commands and migration specifics for your version ship as the Installation & Upgrade Guide included with your package. Where it disagrees with this page, follow the package guide.

#When an upgrade fails

A migration errors out halfway

Do not re-run it hoping it resolves itself — a partially applied migration leaves the schema in a state the next attempt does not expect. Restore the backup, reproduce on a copy, and contact support with the error.

Pages 500 after upgrading

Usually a stale cache: cache clear_all. If that does not fix it, logs/error.log will name the missing class or template — an incomplete asset build is the common cause.

Styling looks broken

The front-end bundle did not rebuild. Re-run npm install && npm run build, then hard-refresh.

Reports stopped working

Superset runs as its own service with its own database. Check docker compose logs orangescrum-reports and confirm its database is healthy.

Often a base-URL or cookie-domain mismatch introduced by new config. Compare against Configuration.

#After the upgrade

⏰Check background jobs

Confirm digests and reminders still fire — cron lives outside the app.

🔑Check the licence

Confirm your licence covers the new version.

💾Take a fresh backup

Your pre-upgrade backup no longer matches the schema.

📣Tell your users

Especially if the release changes anything visible.