{"id":31160067,"url":"https://github.com/tlockcuff/convex-backup-scripts","last_synced_at":"2026-05-09T05:33:56.579Z","repository":{"id":315235439,"uuid":"1058200330","full_name":"tlockcuff/convex-backup-scripts","owner":"tlockcuff","description":"A secure, automated backup solution for Convex databases with built-in encryption","archived":false,"fork":false,"pushed_at":"2025-09-17T12:28:54.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-17T13:29:56.376Z","etag":null,"topics":["backup-script","convex","convex-database","database"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tlockcuff.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-16T18:59:22.000Z","updated_at":"2025-09-17T12:32:53.000Z","dependencies_parsed_at":"2025-09-17T13:29:58.663Z","dependency_job_id":"2322b635-12c7-42f9-a802-44bb5ef7b8d0","html_url":"https://github.com/tlockcuff/convex-backup-scripts","commit_stats":null,"previous_names":["tlockcuff/convex-backup-scripts"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tlockcuff/convex-backup-scripts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlockcuff%2Fconvex-backup-scripts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlockcuff%2Fconvex-backup-scripts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlockcuff%2Fconvex-backup-scripts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlockcuff%2Fconvex-backup-scripts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tlockcuff","download_url":"https://codeload.github.com/tlockcuff/convex-backup-scripts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlockcuff%2Fconvex-backup-scripts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275867745,"owners_count":25542807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-19T02:00:09.700Z","response_time":108,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup-script","convex","convex-database","database"],"created_at":"2025-09-19T02:07:03.974Z","updated_at":"2025-09-19T02:07:07.451Z","avatar_url":"https://github.com/tlockcuff.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Convex Database Backup Tool\n\nA secure, automated backup solution for Convex databases with built-in encryption.\n\n## Overview\n\nThis 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.\n\n## Features\n\n- 🔒 **Encrypted Backups**: AES-256-CBC encryption with OpenSSL\n- 📁 **File Storage Included**: Backs up both database and file storage\n- 🕐 **Timestamped**: Automatic timestamp-based file naming\n- 🔐 **Secure**: Original unencrypted files are automatically deleted\n- ⚙️ **Configurable**: Environment variable-based configuration\n- 📊 **Comprehensive Status**: Real-time backup monitoring and health checks\n- 🛡️ **Error Handling**: Robust error handling with detailed logging\n- 🚫 **Concurrency Protection**: Prevents multiple backup processes\n- 📝 **Detailed Logging**: Structured logging with timestamps and colors\n- 🎯 **Interactive Setup**: Easy configuration with guided setup\n- ☁️ **S3 Cloud Storage**: Optional AWS S3 upload with automatic local cleanup\n\n## Prerequisites\n\n- Node.js (v24.8.0 recommended, managed by Volta)\n- Convex CLI access\n- OpenSSL (typically pre-installed on macOS/Linux)\n- A Convex project with appropriate permissions\n- AWS CLI (optional, for S3 cloud storage)\n\n## Quick Setup\n\n### Option 1: Interactive Setup (Recommended)\n```bash\n# Clone the repository\ngit clone https://github.com/tlockcuff/convex-backup-scripts.git\ncd convex-backup-scripts\n\n# Install dependencies\nnpm install\n\n# Run interactive setup\n./setup.sh\n```\n\n### Option 2: Manual Setup\n1. **Clone/Download** this repository\n\n2. **Install dependencies**:\n   ```bash\n   npm install\n   ```\n\n3. **Generate a backup password and create the .env file**:\n   ```bash\n   # Generate a secure password\n   openssl rand -base64 32\n   \n   # Create .env file with the generated password\n   echo \"BACKUP_PASSWORD=your-generated-password-here\" \u003e .env\n   ```\n\n4. **Add self-hosted convex admin key and url to the .env file** (optional):\n   ```bash\n   echo \"CONVEX_SELF_HOSTED_ADMIN_KEY=your-admin-key\" \u003e\u003e .env\n   echo \"CONVEX_SELF_HOSTED_URL=your-convex-url\" \u003e\u003e .env\n   ``` \n\n5. **Make scripts executable**:\n   ```bash\n   chmod +x backup.sh status.sh setup.sh\n   ```\n\n### Option 3: Command Line Setup\n```bash\n# Generate password automatically\n./setup.sh --generate-password\n\n# Or set specific password\n./setup.sh --password \"your-secure-password\"\n\n# Set Convex configuration\n./setup.sh --convex-key \"your-admin-key\" --convex-url \"your-url\"\n\n# Check configuration\n./setup.sh --check\n```\n\n## Usage\n\n### Creating Backups\n\n```bash\n# Create a backup\n./backup.sh\n```\n\nThe backup script will:\n1. Validate configuration and check prerequisites\n2. Create a `backups/` directory with secure permissions\n3. Export your Convex database with file storage\n4. Encrypt the backup using AES-256-CBC encryption\n5. Apply retention policy (remove old backups)\n6. Set up cron job for automatic backups\n7. Log all operations to `backup.log`\n\n### Checking Status\n\n```bash\n# Check comprehensive backup status\n./status.sh\n```\n\nThe status script shows:\n- Current backup process status\n- Number and size of backups\n- Oldest and newest backup information\n- Disk space usage\n- Cron job configuration\n- Last backup success/error\n- Health checks and warnings\n\n### Configuration Management\n\n```bash\n# Check current configuration\n./setup.sh --check\n\n# Interactive configuration\n./setup.sh\n\n# Generate new password\n./setup.sh --generate-password\n\n# Set specific configuration\n./setup.sh --password \"new-password\" --retention 30\n```\n\n### Environment Variables\n\nConfigure the tool using the `.env` file:\n\n```env\n# Required: Backup encryption password\nBACKUP_PASSWORD=your-secure-password-here\n\n# Optional: Self-hosted Convex configuration\nCONVEX_SELF_HOSTED_ADMIN_KEY=your-admin-key\nCONVEX_SELF_HOSTED_URL=your-convex-url\n\n# Optional: AWS S3 cloud storage (enables automatic S3 upload and local cleanup)\nAWS_REGION=us-east-1\nAWS_ACCESS_KEY_ID=your-access-key\nAWS_SECRET_ACCESS_KEY=your-secret-key\nAWS_BUCKET_NAME=your-backup-bucket\n\n# Optional: Backup retention policy (days)\nRETENTION_POLICY=14\n```\n\n### S3 Cloud Storage\n\nWhen AWS S3 is configured, the backup script will:\n1. Upload encrypted backups to S3 with organized folder structure: `convex-backups/YYYY/MM/DD/`\n2. Use `STANDARD_IA` storage class for cost optimization\n3. Verify successful upload before deleting local backup files\n4. Apply retention policy to both local and S3 backups\n5. Keep backups locally if S3 upload fails\n\n### Example Output\n\n```\n[2024-09-17 14:30:22] [INFO] === Convex Backup Script Started ===\n[2024-09-17 14:30:22] [INFO] Validating configuration...\n[2024-09-17 14:30:22] [SUCCESS] Configuration validation passed\n[2024-09-17 14:30:22] [INFO] Checking Convex access...\n[2024-09-17 14:30:23] [SUCCESS] Convex CLI is accessible\n[2024-09-17 14:30:23] [INFO] Starting backup creation...\n[2024-09-17 14:30:23] [INFO] Exporting Convex database...\n[2024-09-17 14:30:45] [SUCCESS] Database exported successfully (15MB)\n[2024-09-17 14:30:45] [INFO] Encrypting backup file...\n[2024-09-17 14:30:46] [SUCCESS] Backup file encrypted successfully\n[2024-09-17 14:30:46] [SUCCESS] 🎉 Backup completed successfully!\n```\n\n## Manual Restore\n\nTo manually decrypt and restore a backup:\n\n```bash\n# Decrypt the backup\nopenssl enc -aes-256-cbc -d -salt -pbkdf2 -iter 100000 -in ./backups/20240917143022.zip.enc -out restored-backup.zip -pass pass:your-password\n\n# Extract the backup\nunzip restored-backup.zip\n\n# Import back to Convex (refer to Convex documentation for import commands)\n```\n\n## Security Notes\n\n- 🔐 The `.env` file contains your encryption password and is excluded from version control\n- 🗂️ The `backups/` directory is also gitignored to prevent accidental commits\n- 🔒 Original unencrypted backup files are automatically deleted\n- 💾 Keep your encryption password safe - you'll need it to restore backups\n- 🛡️ Backup files have restrictive permissions (600) for security\n- 🚫 Lock files prevent concurrent backup operations\n- 📝 Detailed logging helps track all backup operations","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlockcuff%2Fconvex-backup-scripts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftlockcuff%2Fconvex-backup-scripts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlockcuff%2Fconvex-backup-scripts/lists"}