On this page
Back up, restore and upgrade¶
Quickstart backup¶
From the matching source checkout, pause external producers and drain any split worker pools. The distribution script requires downtime and one responsive, idle worker. Use the running project name and a destination directory that does not exist.
./scripts/distribution.sh backup contextbase /absolute/path/to/new-backup
Wait for the COMPLETE marker. The backup contains image metadata,
checksums, a PostgreSQL custom-format dump and archives of the stopped
configuration, original-file and Redis volumes. The script stops producers
and the idle worker, then attempts to resume the services if the producers
were stopped successfully.
For a deployment-specific Compose overlay, pass its absolute path with
CONTEXTBASE_COMPOSE_OVERRIDE and preserve it with the installation’s
configuration. For a different topology, arrange equivalent database,
object-storage and external-service recovery separately.
Decide what the recovery copy must contain¶
Keep the PostgreSQL dump, document originals and their configuration encryption keys together. Also record the revision, image identities and Compose overlays. Account for Redis persistence and any external vector database, object store, identity service or provider configuration. Local volume archives cover only local data.
Restrict access to the backup and keep a copy in an independent failure domain. Test a restore and a product workflow before upgrading.
Test the restore¶
Select a new project name and unused port. Use the recorded source revision and the corresponding application images first. Reuse the same effective storage configuration and choose an overlay suitable for the isolated restore.
CONTEXTBASE_UI_PORT=13002 ./scripts/distribution.sh restore \
contextbase-restored /absolute/path/to/new-backup
The script checks the completion marker and checksum set, refuses existing target containers, networks or volumes, restores files and credentials, initializes PostgreSQL and loads the dump. It starts the recovered application with its migration step. If restore fails, inspect the isolated target and use a fresh project after correcting the cause.
Verify these behaviors on the restored installation.
Sign in with an existing account and open its space.
Download an existing original and compare it with the expected file.
Search an indexed document and open a returned source.
Exercise a saved encrypted configuration if the installation uses one.
Model cache and collected assets need not be in the backup. Allow time for model downloads or warm-up after restoration.
Upgrade safely¶
For installations using the published local installer, follow the release upgrade instructions. That path stages the next release’s images before stopping the current installation and uses its existing project and volumes. Back up first. Changes to storage initialization or other incompatible Compose settings require a separate migration procedure.
For compatible versioned images built from source, use the generated
release.env for the reviewed revision, then run the following from
that checkout.
set -a
. /absolute/path/to/new-release-manifest/release.env
set +a
./scripts/distribution.sh upgrade contextbase /absolute/path/to/pre-upgrade-backup
Keep the previous source and images available. The upgrade verifies local image identities and platform, creates a pre-upgrade backup and runs the new migration step. Confirm sign-in, document retrieval and background processing before reopening normal traffic. If the upgrade cannot finish, restore the pre-upgrade backup on the previous version in a fresh project. Reapplying an older image to a migrated database is not a schema rollback.