50 lines
3.2 KiB
Markdown
50 lines
3.2 KiB
Markdown
<!-- SPDX-License-Identifier: LicenseRef-ConusAI-Template-1.0 -->
|
|
# Convex backups
|
|
|
|
The Convex profile runs a separate `backup` service. Compose keeps its Node runner alive; it invokes
|
|
the supported `convex export` admin command, includes file storage, streams the archive to the project's ConusAI
|
|
Blob service, and keeps the newest 30 archives. The interval and retention are configurable with
|
|
`CONVEX_BACKUP_INTERVAL_HOURS` and `CONVEX_BACKUP_RETENTION`. The provider injects
|
|
`CONVEX_SELF_HOSTED_URL` and `CONVEX_SELF_HOSTED_ADMIN_KEY`; the latter is server-only and is also
|
|
used by the one-shot `convex-deploy` service before web starts. That service places the scoped
|
|
`CONUSAI_API_URL`, `CONUSAI_API_TOKEN`, and `CONUSAI_ORG_SLUG` in the Convex backend env through a
|
|
0600 temporary file before deploying functions. It uses the platform's project service credential,
|
|
not a human owner credential. The provider provisions the backend but does not deploy app functions.
|
|
The platform does not back up Convex deployments (AT-D16);
|
|
monitor the backup service logs and Blob usage as part of operating the app.
|
|
|
|
Archives are stored at `convex-backups/<project-id>/<UTC timestamp>.zip`. An archive contains
|
|
table documents and, when requested, file storage. It does not contain the deployed functions,
|
|
schema, environment variables, or pending scheduled functions. Keep the source revision and
|
|
deployment configuration available separately, and run restore drills against a disposable
|
|
deployment before relying on a backup for recovery.
|
|
|
|
Restore into a new, empty Convex deployment before directing application traffic to it:
|
|
|
|
1. Pause the app's `backup` service and obtain the target deployment's admin key.
|
|
2. Download the selected archive from Blob to a trusted operator machine. Keep it private: it
|
|
contains the app's complete Convex data and uploaded file contents.
|
|
3. Deploy the same app revision to the empty target first. This installs the app schema and its
|
|
components (including the audit component tables) without adding application rows. Let the
|
|
`convex-deploy` service install the target's scoped platform environment before deploying.
|
|
4. Point the Convex CLI at that now-initialized, still-empty deployment and import the archive:
|
|
|
|
```sh
|
|
CONVEX_SELF_HOSTED_URL="$TARGET_CONVEX_URL" \
|
|
CONVEX_SELF_HOSTED_ADMIN_KEY="$TARGET_CONVEX_ADMIN_KEY" \
|
|
pnpm exec convex import ./convex-export.zip
|
|
```
|
|
|
|
5. Verify the notes list and attached files in the app before switching traffic. Resume the backup
|
|
service after the target is serving traffic.
|
|
|
|
The import intentionally has no replace flag: it fails closed if the target already contains
|
|
conflicting table data. Install the app schema/components first, then import into the empty app
|
|
deployment and verify it before switching traffic. The
|
|
profile gate exercises export, Blob upload, retention pruning, and import into an empty local
|
|
backend. Convex currently documents CLI data import as a beta feature, so keep an independent
|
|
recovery path and run restore drills before production use. See Convex's current
|
|
[backup and restore guide](https://docs.convex.dev/database/backup-restore)
|
|
and [data import documentation](https://docs.convex.dev/database/import-export/import) for archive
|
|
contents, import behavior, and limitations.
|