Upgrades

An Overlay release has two parts that move together: the web app image and the Convex functions in convex/. Upgrade both from the same release tag.

Before you start

Read the release notes in CHANGELOG.md for the tag you are moving to.
Back up the Convex backend with npx convex export.
Pin versions. Never run a floating latest tag in production, for the app or the Convex backend.

Check out the release

git fetch --tags
git checkout v<version>

Deploy the Convex functions

From the checkout, against your backend:

npx convex deploy --env-file convex.env.local

Deploy the functions and update the app one right after the other: until both are on the new release, some requests can fail.

Update the web app

With the installer:

overlayctl update <version>

With Docker Compose, set OVERLAY_WEB_IMAGE to the new tag, then:

docker compose pull
docker compose up -d

Verify

Sign in, open a chat and send a message, upload a file, and open Settings. Check /api/v1/capabilities and the app and backend logs.

The convex-backend image has its own version, separate from Overlay’s.

Export first: npx convex export --env-file convex.env.local.
Change CONVEX_BACKEND_IMAGE in convex.env to the new pinned tag, then docker compose -f docker-compose.convex.yml --env-file convex.env up -d.
Watch the backend logs for Executing Migration n/m and then MigrationComplete.

Web app and functions: set the previous image tag and restart, then check out the previous tag and run npx convex deploy again, so both sides match.
Data: if a release changed data in a way you need to undo, restore the export you took first: npx convex import --replace-all <export.zip>. This needs downtime; take a final export after traffic stops.

If you changed the source, merge the new release into your fork, run your checks, and build your own image:

git fetch upstream --tags
git merge v<version>
docker compose -f docker/docker-compose.yml -f docker/docker-compose.build.yml up --build -d