# Upgrade

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

> For the complete documentation index, see [llms.txt](https://helpdesk.orangescrum.com/llms.txt).

Source: https://helpdesk.orangescrum.com/guide/self-hosted/operate/upgrade

---
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](https://helpdesk.orangescrum.com/guide/self-hosted/operate/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.

**Login works but pages are empty**

    Often a base-URL or cookie-domain mismatch introduced by new config. Compare
    against [Configuration](https://helpdesk.orangescrum.com/guide/self-hosted/install/configuration).

## After the upgrade

- **Check background jobs**: Confirm digests and reminders still fire — cron lives outside the app.

- [Check the licence](https://helpdesk.orangescrum.com/guide/self-hosted/admin/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.