Updates and database migrations

An update replaces application files and may change the database schema. Plan it as a deployment, not as a button inside Admin. Admin → Updates reports the current application and schema state; it does not download new source files.

1. Choose the update source

Use one of these sources:

Latest published release

This command selects the newest published archive from GitHub:

cd /var/www
rm -rf /tmp/agovena-release
mkdir -p /tmp/agovena-release
RELEASE_URL="$(curl -fsSL https://api.github.com/repos/milovd/Agovena/releases/latest 2>/dev/null | sed -n 's/.*"browser_download_url": "\(https:[^"]*agovena-[^"]*\.tar\.gz\)".*/\1/p' | head -n 1 || true)"
if [ -z "$RELEASE_URL" ]; then
  printf '%s\n' 'No matching published release archive found. Use the source checkout update path instead.'
  exit 1
fi
curl -fL "$RELEASE_URL" -o /tmp/agovena-latest.tar.gz
tar -xzf /tmp/agovena-latest.tar.gz -C /tmp/agovena-release

If test -n "$RELEASE_URL" fails, use the Source checkout update path. That means GitHub has no matching published archive yet. When an archive is available, use the extracted directory in step 4.

Source checkout

For a checkout, pull the latest main revision:

cd /var/www/agovena
git pull --ff-only origin main
composer install --no-dev --optimize-autoloader
npm ci
npm run build

Use this path only for a source checkout. Do not run composer update during a deployment.

2. Back up the store

Before replacing files:

1. Make a MariaDB backup.
2. Back up .env, including the existing APP_KEY.
3. Back up storage/app/private and storage/app/public.
4. Preserve installed package files under storage/app/packages.
5. Record the current revision and the backup location.

Read backups and restore and make sure the backup can be read before you continue.

3. Enter maintenance mode

Schedule a quiet period, let active queue work finish and stop the supervised worker:

cd /var/www/agovena
php artisan down
sudo systemctl stop agovena-queue.service

The scheduler cronjob can remain installed, but pause this store's scheduler entry while files are being replaced if your deployment process requires it. Maintenance mode does not stop unrelated CLI processes or external provider callbacks.

4. Replace the application files

For a release archive, copy the extracted release into the existing application directory:

sudo cp -a /tmp/agovena-release/agovena-*/. /var/www/agovena/

Keep the existing .env, storage/, database and installed package data. Do not delete them and do not copy an empty storage tree over merchant data.

For a source checkout, the commands in step 1 already updated the application and rebuilt frontend assets.

5. Apply migrations

Run the upgrade command from the application root:

cd /var/www/agovena
php artisan config:clear
php artisan agovena:upgrade
php artisan agovena:doctor

agovena:upgrade applies Core migrations, migrates installed Modules and Extensions and recovers interrupted package operations. Stop if it fails. Do not bring the store online or run the remaining commands blindly.

Never run migrate:fresh, migrate:reset or a database wipe on a store with real data.

6. Restart services

Start the worker, clear maintenance mode and check the application:

sudo systemctl start agovena-queue.service
php artisan queue:restart
php artisan up
php artisan agovena:doctor

If the PHP process manager or selected web server was restarted during the deployment, reload it as well. Keep the scheduler cronjob in place.

7. Check the updated store

Check the store through the real HTTPS hostname:

• the storefront and a product page;
• /login and /admin;
• an existing order and invoice;
• public media;
• email delivery;
• queue consumption;
• the scheduler heartbeat;
• Admin → Updates for the new schema state.

Review application and worker logs after the first queued and scheduled tasks have run.

8. If the update fails

Keep the store in maintenance mode. Read the first migration or deployment error and do not retry external payment or provisioning work without checking the provider first.

Returning to old application files does not automatically undo database or package migrations. Restore a consistent database-and-files backup when necessary, fix the cause and then repeat the deployment from the chosen release.