Upgrading

A new release is a new pack from the portal. The admin's Updates page says when one is out (it asks the portal that packed this install, twice a day at most), with what taking it involves and whether the apps need a new pack. Each release's Taking this release notes in CHANGELOG.md say the same.

bin/upgrade takes a release over from a running install, and goes back to the one before. Run it from the new release's backend folder, unpacked beside the install.

Upgrading

Without Docker, first install the new release's dependencies and build its assets (with your THEME, if you have one):

cd /srv/sports/backend-new                      # the new pack's backend/ folder, beside the install
APP_ENV=prod composer install --no-dev --optimize-autoloader
npm ci && npm run build
bin/upgrade /srv/sports/backend                 # the install

With Docker there's nothing to install first: building the image does it.

cd /srv/sports/backend-new
bin/upgrade /srv/sports/backend

It asks before it starts (--yes doesn't), then:

1. Backs the database up into the install's var/backups/before-<release>-<time>.sql.gz (with Docker, from the database container; without, with php bin/console app:backup).
2. Brings the instance's own files over: .env.local, the API's signing keys (config/jwt/), the uploads (public/uploads/, moved; with Docker they live in a volume) and themes of your own (themes/).
3. Swaps the folders: the new release takes the install's path, so the web server (or Docker, whose project is named after the folder) finds it where the old one was. The old release stays beside it as backend.previous, with the backup.
4. Migrates: the database migrations, new settings and sport presets (with Docker, the container does it as it starts).
5. Checks with php bin/console app:health: the database, its migrations, the settings, the signing keys, writable folders and the API answering.

When the migration or the check fails, it goes back by itself: the database returns to the backup and the old release to its place. The new one waits in backend.next.

Releases can be skipped: going from 1.0.0 to 1.2.0 runs 1.1.0's migrations too. Read each skipped release's notes (the Updates page shows the newest, and whether any release on the way needs a new pack).

Going back

/srv/sports/backend/bin/upgrade --rollback /srv/sports/backend

The release before comes back with the database as it was before the upgrade: whatever changed since (new players, payments, results) is lost, so go back soon, or not at all. The database as it is just before going back is saved first, in the release you leave (backend.next/var/backups/before-rollback-to-<release>-<time>.sql.gz).

To take the release again: backend.next/bin/upgrade /srv/sports/backend.

Only the release just before is kept: the next upgrade replaces backend.previous.

Backups by hand

php bin/console app:backup                     # var/backups/<time>-<release>.sql.gz
php bin/console app:backup /elsewhere/now.sql.gz
php bin/console app:restore var/backups/20261109-210000-1.2.0.sql.gz

They need the MySQL client (mysqldump and mysql). Nightly backups, kept for two weeks and copied off the server if you like, are bin/backup-db's (Scheduled jobs and backups). Keep copies off the server too, with the uploads, .env.local and config/jwt/: losing the signing keys signs everyone out, and losing .env.local loses the database password.

Apps

When a release needs a new pack, pack again in the portal, build and submit the apps (the pack's UPGRADING.md). Upgrade the backend first: a new app may use something only the new backend has, while a new backend still answers older apps (a release that can't says so).