Configuration

Configuration

ConvexAutoBackup stores app state in SQLite by default and uses environment variables for process-level settings. Product resources such as projects, targets, destinations, jobs, schedules, users, tokens, and encrypted secret references are managed through the web UI, CLI, or API.

Required decisions

Before the first real backup, decide:

Item	Options
Install path	Native, Docker, Cargo, or source.
Data directory	Native app data directory or Docker /data volume.
Convex credentials	Encrypted secret in the app or environment-variable reference.
Destination	Local filesystem or S3-compatible object storage.
Access	Owner/admin/operator/viewer accounts and API tokens.
Exposure	Local/LAN only or HTTPS reverse proxy.

The web console in v0.1.0-beta.5 walks through these setup decisions as a guided flow. Use the CLI examples below when you are automating setup, recovering access from a server shell, or making advanced changes outside the browser.

Data directory

Docker uses /data inside the container. Mount it to durable storage:

docker run -d \
  --name convex-autobackup \
  -p 8976:8976 \
  -v convex-autobackup-data:/data \
  kodydoty/convex-autobackup:latest

The data directory holds runtime state, the SQLite database, managed runner files, and local backup destination data when configured that way.

Master key

Set CONVEX_AUTOBACKUP_MASTER_KEY for encrypted secret storage.

export CONVEX_AUTOBACKUP_MASTER_KEY="$(openssl rand -base64 32)"

Back it up securely. If you lose the key, encrypted stored credentials may not be recoverable.

Convex credentials

Create a Convex deploy key with enough access to export the deployment you want to protect.

Preferred app-managed flow:

CONVEX_AUTOBACKUP_MASTER_KEY=<master> convex-autobackup secret put \
  --label "Production deploy key" \
  --kind convex_deploy_key \
  --value "<deploy-key>" \
  --json

Environment-reference flow:

export CONVEX_DEPLOY_KEY=...

Use environment references for local automation if you do not want deploy keys stored by the app.

Projects and targets

Projects group related Convex targets. A target is a concrete Convex deployment.

convex-autobackup project create --name "Client App" --json
convex-autobackup target create-cloud \
  --project-id <project-id> \
  --name Production \
  --deployment <deployment-name> \
  --deploy-key-secret-id <secret-id> \
  --json

Destinations

Local destination:

convex-autobackup destination create-local \
  --name "Local Vault" \
  --root /data/backups \
  --json

S3-compatible destination:

convex-autobackup destination create-s3 \
  --name "Object Storage" \
  --bucket <bucket> \
  --prefix convex-autobackup \
  --region auto \
  --endpoint <endpoint-if-needed> \
  --credentials-secret-id <secret-id> \
  --json

S3-compatible storage is intended to support providers such as R2, B2, MinIO, and compatible object stores.

Jobs and schedules

A job connects a target and a destination.

convex-autobackup job create \
  --project-id <project-id> \
  --target-id <target-id> \
  --destination-id <destination-id> \
  --name "Daily production backup" \
  --json

Schedules run jobs automatically through the worker.

Network binding

Default:

0.0.0.0:8976

Manual server command:

convex-autobackup serve --bind 0.0.0.0:8976

For production, bind behind a reverse proxy with HTTPS. Do not expose the service directly to the public internet without a hardened proxy and access controls.

Secrets policy

Never commit or paste:

• Convex deploy keys.
• CONVEX_AUTOBACKUP_MASTER_KEY.
• Docker Hub tokens.
• crates.io tokens.
• GitHub tokens.
• S3 access keys.
• Backup archives containing production data.