Upgrades

An upgrade is a pull, a migration and a restart. Run them in that order.

git pull
make external          # the pinned third-party trees and rule corpora
make docker-build

cd docker && docker compose up migrate

make docker-up

MigrationsCopy Anchor Link

The API does not migrate on startup unless RUN_MIGRATIONS_ON_STARTUP is set, which it should not be in production.

• On the compose stack the migrate service reruns on the next up and exits immediately when there is nothing to apply.
• Elsewhere, make migrate from the repository root. It sources bootstrap.env when present and runs alembic upgrade head from apps/api; DATABASE_URL must be reachable from where you run it, so the compose-internal postgres:5432 will not do.

Picking up a source editCopy Anchor Link

After a pull that adds a revision, migrate before restarting the services. The production stack bakes the frontend into an image and runs the worker under plain arq, so neither picks up a source edit on its own: make fe-rebuild rebuilds and replaces the frontend container, and make worker-restart restarts the worker.

A stack that runs the pulled MinIO imageCopy Anchor Link

To upgrade a stack that runs the pulled MinIO image (minio/minio:RELEASE.2025-09-07T16-13-09Z), run docker compose build minio before the restart, or let the next up build it. malspark-minio starts on the same minio_data volume, under the same service and container name, ports, credentials and command. Nothing needs migrating: the release built is the one after that image's, which changes no on-disk format, so buckets, objects, versions, policies and object lock settings read unchanged.

From an environment-file deploymentCopy Anchor Link

Settings are not imported from a .env deployment. To move one, enter its settings once in Settings → Configuration, or import a JSON export from another instance.

Staged samples after an upgradeCopy Anchor Link

If the staging directory holds flat uploads or a single carved/ tree, leave them: the sidecars sweep them on the staging TTL. Nothing has to be moved. See Staged samples.