Upgrade MOVO

This guide is for administrators updating an existing Docker Compose deployment. For a first installation, see Quick start.

Before you upgrade

1. Check the current service state with ./movo status.
2. Back up the database, knowledge documents and other persistent volumes, and make sure the backup can be restored.
3. Review the release notes and .env. If MOVO_VERSION is pinned, an upgrade will continue to use that tag rather than switching to latest. Confirm that the target registry has the required tag.
4. Before changing registries, verify that the new registry carries all tags your deployment needs. The China mirror may not have every GHCR tag.

up is not an upgrade command

./movo up pulls only images missing locally. Rerunning it with latest does not guarantee that a newer remote image is downloaded.

Upgrade with the launcher

Update the local checkout first to obtain the current launcher and deployment files:

git pull --ff-only

For the default GHCR registry:

./movo update

If this deployment uses the China mirror and the required tag is available there:

./movo --mirror cn update

update checks and pulls remote images, runs the required database upgrade, and recreates affected containers. Unchanged image layers can be reused. It does not update the local Git checkout, which is why the preceding git pull --ff-only matters.

Upgrade with native Compose

If you deploy without the ./movo launcher, first confirm the backup and target image version, then run:

docker compose pull
docker compose up -d

Native Compose does not perform the launcher's additional readiness checks. If the target release requires a database migration, follow that release's migration instructions before relying on these commands alone.

Source development mode

Rebuild local images only if you develop MOVO from source:

git pull --ff-only
./movo up --build

./movo update is for prebuilt-image deployments, not locally built image mode.

Verify after upgrading

./movo status
./movo logs chat-api
./movo logs dsh-runtime-host

Once services are healthy, verify employee and admin sign-in, ordinary chat, and the knowledge or plugin capabilities used by your organization.

Preserve persistent data

./movo down -v deletes MOVO persistent volumes and initial setup state. Do not run it during an upgrade.