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.

  1. Sign in with an existing account and open its space.

  2. Download an existing original and compare it with the expected file.

  3. Search an indexed document and open a returned source.

  4. 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.

ContextBase0.1.0

Search the documentation