template-app/docs/backup.md

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:

   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 and data import documentation for archive contents, import behavior, and limitations.