Upgrade

This page explains how to upgrade the site to a new Release with awhere upgrade. If the site is still v4, start at Upgrade from v4.

Before you upgradeCopy Anchor Link

• Read the release notes of every Release between the current one and the one you upgrade to.
• Back up all four databases and the site's env files. If the new Release has a contract Migration, restoring from the backup is the only way back (Roll back).
• Pick a time when no one is using the site. During an upgrade, each container stops serving until the new one is ready.

UpgradeCopy Anchor Link

1. Run the upgrade command with the Release number you want.

   Copy Text

   awhere upgrade 5.1.0

   The command downloads the images of that Release, then runs Preflight on every node. If a check fails, the system changes nothing. If all pass, it replaces the containers with the new ones, one at a time, starting with core-services. If the Release you chose skips an upgrade stop, the command tells you before it starts.

2. Check the result.

   Copy Text

   awhere status

Watch progress on the System pageCopy Anchor Link

Open the System page in Configuration (System). The page refreshes by itself every 10 seconds.

• The message "Nodes are on different Releases" is normal during an upgrade. It goes away once every node has changed.
• A Migration that shows Paused continues by itself when the node of that service starts again. One that shows Failed is retried by the system.
• If a Migration shows Done but skipped some data, someone must open that row and read what it skipped.

If the upgrade stops halfwayCopy Anchor Link

The site has containers of both the old and the new Release, but it is not broken. Find the cause with awhere logs <component>, then run the same awhere upgrade command again. You can also go back with awhere rollback.

What the system recordsCopy Anchor Link

The file /etc/awhere/release holds the Release the site runs. The file /etc/awhere/release.history holds the history of Releases that were deployed. awhere rollback reads it to know which Release to go back to.