https://github.com/tlockcuff/convex-backup-scripts
A secure, automated backup solution for Convex databases with built-in encryption
https://github.com/tlockcuff/convex-backup-scripts
backup-script convex convex-database database
Last synced: 25 days ago
JSON representation
A secure, automated backup solution for Convex databases with built-in encryption
- Host: GitHub
- URL: https://github.com/tlockcuff/convex-backup-scripts
- Owner: tlockcuff
- Created: 2025-09-16T18:59:22.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-17T12:28:54.000Z (9 months ago)
- Last Synced: 2025-09-17T13:29:56.376Z (9 months ago)
- Topics: backup-script, convex, convex-database, database
- Language: Shell
- Homepage:
- Size: 47.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Convex Database Backup Tool
A secure, automated backup solution for Convex databases with built-in encryption.
## Overview
This tool creates encrypted backups of your Convex database, including file storage, using a simple shell script. All backups are automatically encrypted with AES-256-CBC encryption for security.
## Features
- 🔒 **Encrypted Backups**: AES-256-CBC encryption with OpenSSL
- 📁 **File Storage Included**: Backs up both database and file storage
- 🕐 **Timestamped**: Automatic timestamp-based file naming
- 🔐 **Secure**: Original unencrypted files are automatically deleted
- ⚙️ **Configurable**: Environment variable-based configuration
- 📊 **Comprehensive Status**: Real-time backup monitoring and health checks
- 🛡️ **Error Handling**: Robust error handling with detailed logging
- 🚫 **Concurrency Protection**: Prevents multiple backup processes
- 📝 **Detailed Logging**: Structured logging with timestamps and colors
- 🎯 **Interactive Setup**: Easy configuration with guided setup
- ☁️ **S3 Cloud Storage**: Optional AWS S3 upload with automatic local cleanup
## Prerequisites
- Node.js (v24.8.0 recommended, managed by Volta)
- Convex CLI access
- OpenSSL (typically pre-installed on macOS/Linux)
- A Convex project with appropriate permissions
- AWS CLI (optional, for S3 cloud storage)
## Quick Setup
### Option 1: Interactive Setup (Recommended)
```bash
# Clone the repository
git clone https://github.com/tlockcuff/convex-backup-scripts.git
cd convex-backup-scripts
# Install dependencies
npm install
# Run interactive setup
./setup.sh
```
### Option 2: Manual Setup
1. **Clone/Download** this repository
2. **Install dependencies**:
```bash
npm install
```
3. **Generate a backup password and create the .env file**:
```bash
# Generate a secure password
openssl rand -base64 32
# Create .env file with the generated password
echo "BACKUP_PASSWORD=your-generated-password-here" > .env
```
4. **Add self-hosted convex admin key and url to the .env file** (optional):
```bash
echo "CONVEX_SELF_HOSTED_ADMIN_KEY=your-admin-key" >> .env
echo "CONVEX_SELF_HOSTED_URL=your-convex-url" >> .env
```
5. **Make scripts executable**:
```bash
chmod +x backup.sh status.sh setup.sh
```
### Option 3: Command Line Setup
```bash
# Generate password automatically
./setup.sh --generate-password
# Or set specific password
./setup.sh --password "your-secure-password"
# Set Convex configuration
./setup.sh --convex-key "your-admin-key" --convex-url "your-url"
# Check configuration
./setup.sh --check
```
## Usage
### Creating Backups
```bash
# Create a backup
./backup.sh
```
The backup script will:
1. Validate configuration and check prerequisites
2. Create a `backups/` directory with secure permissions
3. Export your Convex database with file storage
4. Encrypt the backup using AES-256-CBC encryption
5. Apply retention policy (remove old backups)
6. Set up cron job for automatic backups
7. Log all operations to `backup.log`
### Checking Status
```bash
# Check comprehensive backup status
./status.sh
```
The status script shows:
- Current backup process status
- Number and size of backups
- Oldest and newest backup information
- Disk space usage
- Cron job configuration
- Last backup success/error
- Health checks and warnings
### Configuration Management
```bash
# Check current configuration
./setup.sh --check
# Interactive configuration
./setup.sh
# Generate new password
./setup.sh --generate-password
# Set specific configuration
./setup.sh --password "new-password" --retention 30
```
### Environment Variables
Configure the tool using the `.env` file:
```env
# Required: Backup encryption password
BACKUP_PASSWORD=your-secure-password-here
# Optional: Self-hosted Convex configuration
CONVEX_SELF_HOSTED_ADMIN_KEY=your-admin-key
CONVEX_SELF_HOSTED_URL=your-convex-url
# Optional: AWS S3 cloud storage (enables automatic S3 upload and local cleanup)
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_BUCKET_NAME=your-backup-bucket
# Optional: Backup retention policy (days)
RETENTION_POLICY=14
```
### S3 Cloud Storage
When AWS S3 is configured, the backup script will:
1. Upload encrypted backups to S3 with organized folder structure: `convex-backups/YYYY/MM/DD/`
2. Use `STANDARD_IA` storage class for cost optimization
3. Verify successful upload before deleting local backup files
4. Apply retention policy to both local and S3 backups
5. Keep backups locally if S3 upload fails
### Example Output
```
[2024-09-17 14:30:22] [INFO] === Convex Backup Script Started ===
[2024-09-17 14:30:22] [INFO] Validating configuration...
[2024-09-17 14:30:22] [SUCCESS] Configuration validation passed
[2024-09-17 14:30:22] [INFO] Checking Convex access...
[2024-09-17 14:30:23] [SUCCESS] Convex CLI is accessible
[2024-09-17 14:30:23] [INFO] Starting backup creation...
[2024-09-17 14:30:23] [INFO] Exporting Convex database...
[2024-09-17 14:30:45] [SUCCESS] Database exported successfully (15MB)
[2024-09-17 14:30:45] [INFO] Encrypting backup file...
[2024-09-17 14:30:46] [SUCCESS] Backup file encrypted successfully
[2024-09-17 14:30:46] [SUCCESS] 🎉 Backup completed successfully!
```
## Manual Restore
To manually decrypt and restore a backup:
```bash
# Decrypt the backup
openssl enc -aes-256-cbc -d -salt -pbkdf2 -iter 100000 -in ./backups/20240917143022.zip.enc -out restored-backup.zip -pass pass:your-password
# Extract the backup
unzip restored-backup.zip
# Import back to Convex (refer to Convex documentation for import commands)
```
## Security Notes
- 🔐 The `.env` file contains your encryption password and is excluded from version control
- 🗂️ The `backups/` directory is also gitignored to prevent accidental commits
- 🔒 Original unencrypted backup files are automatically deleted
- 💾 Keep your encryption password safe - you'll need it to restore backups
- 🛡️ Backup files have restrictive permissions (600) for security
- 🚫 Lock files prevent concurrent backup operations
- 📝 Detailed logging helps track all backup operations