# Upgrade

> Move to a newer Community Edition release without losing data.

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

Source: https://helpdesk.orangescrum.com/guide/community/operate/upgrade

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

**Login works but pages are empty**

    Often a `FULL_BASE_URL` or cookie-domain mismatch introduced by the new
    config. Compare against
    [Configuration](https://helpdesk.orangescrum.com/guide/community/install/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.