Upgrade

Move to a newer Community Edition release without losing data.

Upgrades pull new code and run any new database migrations. The order matters — back up first, and never skip the migration step.

Back up before every upgrade

Migrations alter the schema in place. If one fails halfway, a backup is the only way back. See Backup and restore.

#Docker

Back up

bash

docker compose exec orangescrum-postgres \
  pg_dump -U orangescrum orangescrum > backup-$(date +%F).sql

docker run --rm \
  -v orangescrum_orangescrum-app-files:/files \
  -v "$PWD":/backup alpine \
  tar czf /backup/files-$(date +%F).tar.gz -C /files .

Read the release notes
Check for breaking changes and required manual steps before pulling. Do not skip this because the last few upgrades were uneventful.

Pull the new code

bash

git fetch --tags
git checkout <new-version-tag>

Rebuild and restart
bash
```
docker compose up -d --build
```
Volumes are preserved — your database 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 and load the dashboard, a project, a task detail and the time log. Then check the error log:
bash
```
docker compose exec orangescrum-app tail -50 logs/error.log
```

#Manual install

bash

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

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

# 3. Dependencies
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 files were added
sudo chown -R www-data:www-data .

#Before you upgrade production

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 quiet window
Migrations can lock tables. Do it when nobody is working.
Know how to roll back
Checking out the old tag is easy; reversing a migration is not. Rollback in practice means restoring the backup — make sure you have one you have actually tested.

#If an upgrade fails

Migration errors out halfway

Do not re-run it hoping it will sort itself out — a partially applied migration leaves the schema in a state the next attempt does not expect. Restore the backup, reproduce on a copy, and report the error.

Pages 500 after upgrading

Usually a stale cache. Run cache clear_all. If that does not fix it, check logs/error.log — a missing template or asset points to an incomplete build; re-run npm run build.

Assets look broken

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

Often a FULL_BASE_URL or cookie-domain mismatch introduced by the new config. Compare against Configuration.

Version 0.1.0

The Community Edition is early. Read the release notes for every upgrade — breaking changes are more likely than in a mature project.