Convex Backups

Backup script for self-hosted Convex instances. Exports your database (and optionally file storage) via npx convex export, uploads to S3-compatible storage, and manages retention policies. Backups are importable to any Convex instance via npx convex import.

Features

• Multi-backend support — back up multiple Convex instances in a single deployment
• Multiple backup frequencies — automatic hourly, daily, weekly, and monthly schedules with configurable retention
• S3-compatible storage — works with AWS S3, Cloudflare R2, Backblaze B2, MinIO, etc.
• File storage backups — optionally include Convex file storage in exports
• Automatic retention — old backups are pruned per frequency
• Automatic retry — failed backups are retried after a configurable delay (default: 5 minutes)
• Failure notifications — get notified via Telegram (or any shoutrrr-supported service) when backups fail
• Single-shot mode — run once and exit, for use with external schedulers (e.g. Kubernetes CronJobs)

Environment Variables

Convex Backend Configuration

You can configure a single backend using legacy env vars, or multiple backends using CONVEX_BACKENDS.

Variable	Required	Default	Description
CONVEX_BACKENDS	No		Comma-separated backend configs using :: as field separator (see format below). Takes priority over legacy vars.
CONVEX_SELF_HOSTED_ADMIN_KEY	No*		Admin key for your self-hosted instance. *Required if CONVEX_BACKENDS is not set.
CONVEX_SELF_HOSTED_URL	No*		API URL for your self-hosted instance. *Required if CONVEX_BACKENDS is not set.
CONVEX_URL	No		Alternative Convex URL.

CONVEX_BACKENDS format: name::url::adminKey per backend, comma-separated for multiple. Fields are separated by :: (double colon) to avoid conflicts with admin keys that contain |. The name is used as the S3 folder for that backend's backups.

CONVEX_BACKENDS=my-app::https://my-app.convex.cloud::adminKey1,my-blog::https://my-blog.convex.cloud::adminKey2

For single-backend setups using legacy env vars, the folder name defaults to BACKUP_FILE_PREFIX (which defaults to backup).

S3 Storage

Variable	Required	Default	Description
AWS_ACCESS_KEY_ID	Yes		AWS access key ID.
AWS_SECRET_ACCESS_KEY	Yes		AWS secret access key.
AWS_S3_BUCKET	Yes		S3 bucket name.
AWS_S3_REGION	Yes		Bucket region (set to auto if unknown).
AWS_S3_ENDPOINT	No		Custom S3 endpoint for third-party services (Cloudflare R2, Backblaze B2, MinIO, etc.).
AWS_S3_FORCE_PATH_STYLE	No	false	Use path-style URLs instead of subdomain-style. Useful for MinIO.

Backup Schedules

Backups run on randomized schedules to prevent collisions across backends. Each frequency gets a unique random minute (0-59) and hour (0-5 AM) at startup:

Frequency	Schedule
Hourly	Every hour at a random minute
Daily	Once per day at a random early morning time
Weekly	Every Sunday at a random early morning time
Monthly	1st of every month at a random early morning time

Retention Limits

Maximum number of backups to keep per frequency. Oldest backups are deleted first.

Variable	Required	Default	Description
MAX_HOURLY_BACKUPS	No	24	Max hourly backups to retain.
MAX_DAILY_BACKUPS	No	7	Max daily backups to retain.
MAX_WEEKLY_BACKUPS	No	4	Max weekly backups to retain.
MAX_MONTHLY_BACKUPS	No	12	Max monthly backups to retain.

Backup Options

Variable	Required	Default	Description
BACKUP_FILE_PREFIX	No	backup	Prefix for backup filenames.
BUCKET_SUBFOLDER	No		Subfolder within the bucket to store backups.
INCLUDE_FILE_STORAGE	No	false	Include file storage in the backup export.
SUPPORT_OBJECT_LOCK	No	false	Enable MD5 hashing for buckets with object lock.
RUN_ON_STARTUP	No	false	Run a backup immediately on startup, then continue on schedule.
SINGLE_SHOT_MODE	No	false	Run a single backup and exit. Useful with external cron schedulers.
BACKUP_MAX_RETRIES	No	1	Number of retry attempts for failed backups before exiting.
BACKUP_RETRY_DELAY_MS	No	300000	Delay in milliseconds between retry attempts (default: 5 minutes).

Notifications

Failure notifications are sent via shoutrrr. When SHOUTRRR_URL is set, you'll be notified whenever a backup fails.

Variable	Required	Default	Description
SHOUTRRR_URL	No		Shoutrrr notification URL. Empty = notifications disabled.

Telegram example:

SHOUTRRR_URL=telegram://bottoken@telegram?chats=chatid

To set up Telegram notifications:

1. Create a bot via @BotFather and copy the bot token
2. Send a message to your bot, then get your chat ID from https://api.telegram.org/bot<token>/getUpdates
3. Set SHOUTRRR_URL=telegram://<token>@telegram?chats=<chatid>

Shoutrrr supports many other services (Discord, Slack, email, etc.) — see the shoutrrr docs for all supported URLs.

Export Cleanup

Convex stores export files at /convex/data/storage/exports inside the backend container. These accumulate over time and should be cleaned up. Add an export-cleanup sidecar to your Convex backend's docker-compose.yml that shares the data volume and runs a daily cleanup:

services:
  backend:
    image: 'ghcr.io/get-convex/convex-backend:latest'
    volumes:
      - 'data:/convex/data'
    # ... your existing backend config

  export-cleanup:
    image: alpine:latest
    volumes:
      - 'data:/convex/data'
    entrypoint: /bin/sh
    command: -c 'while true; do rm -f /convex/data/storage/exports/*; echo "$(date) - Cleaned exports"; sleep 86400; done'
    restart: unless-stopped

volumes:
  data:

Multi-Backend Example

Back up two Convex instances with custom retention:

CONVEX_BACKENDS=my-app::https://my-app.convex.cloud::appAdminKey,my-blog::https://my-blog.convex.cloud::blogAdminKey

MAX_HOURLY_BACKUPS=48
MAX_DAILY_BACKUPS=14
MAX_WEEKLY_BACKUPS=8
MAX_MONTHLY_BACKUPS=24

AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_S3_BUCKET=my-backups
AWS_S3_REGION=us-east-1

SHOUTRRR_URL=telegram://bottoken@telegram?chats=chatid

This creates the following S3 structure (one folder per backend name):

my-backups/
  my-app/
    hourly/
      backup-2024-01-01T05-00-00-000Z.zip
    daily/
      backup-2024-01-01T00-00-00-000Z.zip
    weekly/
      backup-2024-01-07T00-00-00-000Z.zip
    monthly/
      backup-2024-02-01T00-00-00-000Z.zip
  my-blog/
    hourly/
      backup-2024-01-01T05-00-00-000Z.zip
    daily/
      backup-2024-01-01T00-00-00-000Z.zip
    weekly/
      backup-2024-01-07T00-00-00-000Z.zip
    monthly/
      backup-2024-02-01T00-00-00-000Z.zip