Skip to main content
Reset a dedicated installation, then recreate its collections (Corpora) and source connectors from a private JSON declaration.

​
Prerequisites

  • A checkout of the same Quivr revision your installation runs, Python 3.12+ (python3 --version), and the built quivr binary (quivr --version).
  • For Compose, the running make dev Stack from this checkout and Docker Compose (docker compose version). Use its project name from .scratch/. Standalone Compose layouts and externally managed API processes are unsupported.
  • For Railway, the checked-in deployment layout, Railway CLI with railway api and railway ssh, and an account/workspace RAILWAY_API_TOKEN with operator access to every environment. Unset project-scoped RAILWAY_TOKEN; it cannot prove project-wide volume isolation. Every service must use one stable, redeployable artifact; stop deployment automation during maintenance.
  • Four data volumes dedicated to this installation: PostgreSQL, Temporal, Weaviate and SeaweedFS. The object store must contain only the engine’s quivr-content bucket. Source archives belong in a separate store.
  • QUIVR_API_URL and QUIVR_API_KEY for one organization, with corpora:read, corpora:write, corpora:rename, connectors:read and connectors:write. Install the required connector providers; credential deposits need the installation’s credential encryption key.
  • If you declare plugins, QUIVR_OPERATOR_KEY with plugins:admin. Run the plugin hosts before applying; this command registers and activates them through the public API.
Reset deletes documents, vectors, blobs, connector credentials and PostgreSQL state, and terminates running workflows in the default Temporal namespace. It preserves installation credentials, infrastructure settings and cached model files. Keep your declarations, secrets and replay journal outside the public repository.

​
Steps

​
1. Prepare private declarations

Copy the neutral sources example outside your checkout. Replace the feed URL, source bucket and prefixes. The example lists an RSS feed and an object-storage archive; its placeholders do not point at working sources. Corpora use stable idempotency_key values and name. A connector’s corpus references one of those keys. Each connector declares its own key, source_namespace, kind, nonsecret config, work_queue (live by default, or bulk) and schedule.interval_seconds. An omitted interval uses the installed kind’s default. Put credential environment variable names in credential_env; load their values into your shell privately. Alternatively, set credential_file to a private 0600 JSON object matching the kind’s credential schema. Existing credentials are not overwritten: the public replacement API has no conditional version fence. Use an explicit public rotation procedure, or reload after reset. Relative paths resolve beside the declaration. Never put secret values in the declaration, URLs or plugin configuration. A Corpus may select an existing retrieval_profile by name at creation. Apply refuses later profile changes; use the plugin upgrade procedure for those changes. Optional plugins entries contain idempotency_key, endpoint, manifest_file, and nonsecret configuration. They accept fixture_files (fixture name to local path), routes, kinds and spaces from the public registration API. Manifests and fixtures resolve beside the declaration. Conflicting declared plugin roles are refused before writes; a changed registration needs a new key. Plugin host secrets stay in the host environment. Copy either the Compose installation example or the Railway example. Set your deployment name and selectors. dedicated: true asserts exclusive use of all four selected data volumes. Compose verifies project/service volume labels and refuses additional container attachments. Railway also verifies that no other environment attaches them; it refuses incomplete or unreadable ownership checks. Declare every Railway service with a supported role, including autoscaler when present.

​
2. Preview and reset

The following commands are examples requiring your private declarations and deployment access. Preview reads deployment state without stopping services:
Inspect the selected deployment, volume IDs, writer services and storage counts. Execute only after typing the declared deployment name exactly:
Both confirmation inputs are required. Reset stops writers, terminates running workflows, replaces the four data volumes, applies startup migrations and restarts writers. Compose reports deleted volumes and storage counts. Railway restores the same deployed artifacts and reports detached old volumes whose deletion was acknowledged; provider retention can delay physical deletion. If Railway acknowledges a stop but leaves instances running after 30 seconds, reset removes that recorded deployment and verifies shutdown before replacing volumes. Restore redeploys the original recorded artifact, including a removed deployment.

​
3. Preview and apply sources

Use the same API address and organization key on every replay. The private journal binds to both and stores resource IDs, creation intents and keyed credential digests. It contains no credential values. Back up this journal with your private declaration. These commands are examples requiring your API access and source credentials:
Preview prints additions, name and schedule changes, and redacted credential differences. Confirm the displayed changes:
Keep the same journal after reset: missing resources are recreated and connectors receive the new Corpus IDs. Applying an unchanged declaration again prints No changes. and makes no remote writes.

​
Check it worked

Reset checks that replacement blob and vector stores are empty before returning. Railway also checks the migrated database has no Corpora. After apply, list your Corpora and connectors through the public API; source import continues on their declared schedules. An unchanged confirmed apply must print No changes..

​
Troubleshooting

​
Next