Checking for and installing updates

Settings → Updates shows the version your deployment is running, tells you whether a newer one is available, and installs it. You need the admin ability. Without it the page shows "Viewing updates requires the admin role."

Open the page#

1. Open Settings and select the Administration tab.
2. In the Updates card, select Manage.

Running version#

The Running version card lists the two services the updater manages, each with the first 12 characters of its image digest:

• app, the application server
• web, the web server

The digest is the identity of the image the container is actually running. If a digest cannot be read, the page shows unknown. The version refreshes by itself every 45 seconds, and a brief failure heals on its own.

Check for updates#

Select Check for updates. The button reads Checking… while it works. The page also refreshes the running version.

The check compares each running image's digest with the digest the registry currently publishes for the same image reference, for both app and web. It does not pull anything and changes nothing. The comparison uses the tag the container was created from, which is latest unless you set WI_IMAGE_TAG.

You see one of two results:

• Both services are up to date.
• An update is available: followed by the services that differ and the first 12 characters of each new digest, for example app → 3f9a1c0b7d2e, web → 81be40aa5c19.

When an update is available, an Install update button appears.

Install an update#

An install replaces only the app and web images. See What an update changes for when a release needs install.sh re-run first.

1. Select Install update.
2. A dialog titled Install this update? warns that the app and web services restart to switch to the new version and that access is briefly interrupted. Select Install update to confirm.
3. The page shows Installing the update… with five steps, with the current one highlighted:
   • Backing up the database
   • Pulling the new images
   • Starting the new version alongside the current one
   • Health-checking the new version
   • Switching over to the new version
4. When the switchover finishes, the page shows The update installed successfully. and then Reloading…. After about two seconds it reloads so you land on the new version of the web app. You can also select Done.

The server decides what to install. When you confirm, it checks the registry again and installs the digest the registry reports at that moment. The request carries no version of its own, so you can only install what the registry currently publishes.

During the last step the app and web containers are replaced, and access is briefly interrupted. While that happens the page can show Waiting for the app to come back online…. That is expected. It keeps polling and recovers when the app answers again.

Only one install at a time#

Your company can have one install in progress. If you select Install update again, from another tab or another browser, while one is running, you are attached to the run already in progress instead of starting a second one.

The page remembers the active install#

The page stores the id of the active install in your browser, so a refresh or a closed tab does not lose track of it. When you return, you see the progress of that run. The page forgets the stored id when you select Done or Dismiss, and after a successful reload. If the stored run no longer exists on the server, the page drops it and shows the normal check view.

The run itself is recorded on the server and does not depend on your browser. Clearing browser storage only means a refresh no longer reattaches the page to the run.

Errors you can see#

The page shows the server's message in red under the control that failed.

Message	Cause
no running container found for service 'app' (compose project 'wi-prod') (or web)	The update check cannot find the running container. The stack was not started under the wi-prod project, or the container is stopped. This is a 503 response.
Install is unavailable on this instance (workflows not launched)	The application's workflow engine did not start. This is a 503 response. Check the app log.
docker registry inspection failed for image ...	The registry could not be reached, or it refused the request. This is a 502 response. See Registry credentials for updates.
The registry did not report a target digest to install	The registry answered without a digest. This is a 502 response. Try again.
the running 'app' container was created from a bare image id ... (or 'web')	The container's image reference was lost, so the registry cannot be checked. Recreate it with sudo docker compose -f docker-compose.prod.yml up -d --force-recreate app (or web) in the deployment directory.

If an install fails, see When an update fails. To learn what each step does, see How an update runs.