Upgrade Packages

What the upgrade system provides

LabSchool Exams releases can provide two package types. The full package is used for a fresh installation or full application replacement. The incremental upgrade package is smaller and is used only when the installed version matches the supported starting version.

Packages in a v2.1.2 release

For v2.1.2, the release workflow publishes these files.

labschool-exams-v2.1.2-full.zip
labschool-exams-v2.1.2-full.zip.sha256
labschool-exams-v2.1.1-to-v2.1.2-upgrade.zip
labschool-exams-v2.1.1-to-v2.1.2-upgrade.zip.sha256
update.json

• Use the full package when you install from scratch or when no matching incremental package exists.
• Use the upgrade package only when the currently installed version is exactly the package from_version.
• Use the SHA-256 checksum file to confirm that the downloaded package was not corrupted.
• Use update.json when the in-app Update Center reads update metadata from a public manifest.

What is inside an incremental package

The incremental package contains the application files that changed between the two supported versions, plus release metadata needed by the operator.

• Added, copied, renamed, or modified files between the two versions.
• Built frontend assets under public/build.
• A top-level VERSION file for the target version.
• upgrade-manifest.json, deleted-files.txt, and UPGRADE.md.

A. Before upgrading

Treat every upgrade like a short maintenance procedure. Do not start by copying files. First confirm the version, take backups, and make sure you can return to the previous state if something unexpected happens.

1. Check the installed application version from the footer, the Update Center, APP_VERSION, or the packaged VERSION file.
2. Confirm that the upgrade package starts from that exact version. For example, use v2.1.1-to-v2.1.2 only on an installed v2.1.1 instance.
3. Back up the database before changing files or running migrations.
4. Back up the application files, especially .env, storage/, and public/storage.
5. Choose a quiet time window, because users should not be taking quizzes while the update is being applied.

B. Applying an incremental upgrade

The example below describes the professional path for an existing installation. On shared hosting, some commands may be run from a hosting terminal, SSH, or a deployment panel.

1. Put the application in maintenance mode

php artisan down

2. Extract the upgrade package

Extract the upgrade package over the existing installation. Do not replace .env, storage/, or public/storage. These contain local configuration and runtime data.

3. Remove deleted files when needed

Open deleted-files.txt. If it lists paths, remove those old files from the installed application. If it is empty, there is nothing to remove.

4. Check whether Composer is required

Open upgrade-manifest.json. Run Composer only when composer_install_required is true.

composer install --no-dev --prefer-dist --optimize-autoloader

5. Run migrations and rebuild caches

php artisan migrate --force
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

6. Bring the application back online

php artisan up

C. When to use the full package

Use the full package when you are making a fresh installation, when your installed version does not match an incremental package, or when you intentionally want to replace the application code as a whole. Keep local files such as .env, storage/, and public/storage safe.

For a fresh installation, follow the installation guide. For a replacement of an existing installation, use the same backup and maintenance-mode discipline as an incremental upgrade.

D. Update Center and update.json

The in-app Update Center can show the latest version and, when available, the matching upgrade package. It compares the installed version with the from_version values in update.json. The full package remains available as a fallback.

APP_UPDATE_MANIFEST_URL=https://updates.example.org/exams/update.json

If package links point to private GitHub release URLs, anonymous installations cannot download them. Publish the manifest and packages at a public endpoint when deployed instances must reach them directly.

E. Verification after the upgrade

After the application comes back online, do a short but meaningful smoke test before telling users that the system is ready.

1. Teacher login works and the dashboard loads.
2. The footer or Update Center reports the expected target version.
3. Quiz create, edit, and list pages load correctly.
4. A student or guest participation link opens and can start a quiz.
5. Printable quiz PDF, attempt PDF, and certificate verification still work.
6. If mail is used, confirm that one log-mail or SMTP flow is recorded correctly.