Backups & Restore

Regular backups are critical for protecting your Admin Bud-E data. This includes:

• User accounts and API keys
• Credit balances
• Usage history
• Projects and budgets
• Provider and route configurations
• Pricing rules

What Gets Backed Up

Admin Bud-E stores all data in an SQLite database file (typically admin_bude.db or similar).

Contents:

• Users table (usernames, keys, credits)
• Projects table (budgets, allowances, common pools)
• Usage logs table (requests, timestamps, costs)
• Providers table (names, URLs, credentials)
• Routes table (priorities, models)
• Pricing table (costs per model)

INFO

The SQLite file is self-contained — you can copy it to another server and restore the entire system.

Creating Backups

Method 1: Admin UI (Recommended)

1. Log into Admin Bud-E dashboard
2. Navigate to Maintenance
3. Click Download Backup
4. Save the file (e.g., backup_2024-12-15.db)

Benefits:

• Simple (no command line)
• Consistent snapshot (safe during operation)
• Includes integrity check

Method 2: Manual File Copy

If you have SSH access to the server:

# Stop the service (ensures consistency)
sudo systemctl stop admin-bude.service

# Copy the database
cp /opt/bud-e/school-bud-e-middleware/admin_bude.db /tmp/backup_$(date +%Y-%m-%d).db

# Restart the service
sudo systemctl start admin-bude.service

# Download to your computer
scp user@server:/tmp/backup_2024-12-15.db ~/backups/

WARNING

Copying the database while the service is running may result in a corrupted backup. Always stop the service first, or use the Admin UI method.

Method 3: Automated Script

Create a cron job for daily backups:

#!/bin/bash
# /opt/bud-e/backup.sh

DATE=$(date +%Y-%m-%d)
BACKUP_DIR="/opt/bud-e/backups"
DB_PATH="/opt/bud-e/school-bud-e-middleware/admin_bude.db"

# Create backup directory if it doesn't exist
mkdir -p "$BACKUP_DIR"

# Stop service
systemctl stop admin-bude.service

# Copy database
cp "$DB_PATH" "$BACKUP_DIR/backup_$DATE.db"

# Restart service
systemctl start admin-bude.service

# Compress backup
gzip "$BACKUP_DIR/backup_$DATE.db"

# Delete backups older than 30 days
find "$BACKUP_DIR" -name "backup_*.db.gz" -mtime +30 -delete

echo "Backup completed: backup_$DATE.db.gz"

Make executable and schedule:

chmod +x /opt/bud-e/backup.sh

# Add to crontab (runs daily at 2 AM)
sudo crontab -e
# Add line:
0 2 * * * /opt/bud-e/backup.sh >> /var/log/admin-bude-backup.log 2>&1

Backup Frequency

Minimum:

• Weekly — For low-usage deployments (testing, small groups)

Recommended:

• Daily — For production (schools, companies)

Optimal:

• Daily automated + Manual before major changes (migrations, bulk user imports, pricing updates)

Backup Storage

Local Storage (Short-Term)

Keep recent backups on the server:

• Last 7 days: Daily backups
• Last 4 weeks: Weekly backups

Path: /opt/bud-e/backups/

DANGER

Local-only backups do not protect against:

• Server hardware failure
• Datacenter fire/flood
• Ransomware (if it spreads to backups)

Always maintain off-site backups.

Off-Site Storage (Long-Term)

Copy backups to a separate location:

Options:

1. Your Computer

   • Download weekly via Admin UI
   • Store in organized folders (by year/month)

2. Cloud Storage

   • Google Drive (encrypted folder)
   • Dropbox
   • Amazon S3 (with encryption)
   • Backblaze B2

3. Network Storage (NAS)

   • If your organization has a NAS
   • Automated sync via rsync or similar

4. External Hard Drive

   • Monthly copy to USB drive
   • Store in safe location

Encryption

Always encrypt backups that leave your server.

Method 1: GPG Encryption

# Encrypt backup
gpg --symmetric --cipher-algo AES256 backup_2024-12-15.db
# Creates: backup_2024-12-15.db.gpg

# Decrypt (when needed)
gpg --decrypt backup_2024-12-15.db.gpg > backup_2024-12-15.db

Method 2: 7-Zip (Windows/Mac/Linux)

# Encrypt with password
7z a -p -mhe=on backup_2024-12-15.db.7z backup_2024-12-15.db

# Extract
7z x backup_2024-12-15.db.7z

Method 3: Built-in Encryption (Cloud Services)

• Google Drive: Enable encryption at rest (automatic)
• Dropbox: Enable zero-knowledge encryption (Dropbox Vault)
• Amazon S3: Enable server-side encryption (SSE-S3 or SSE-KMS)

TIP

Store encryption passwords in a password manager (not in plain text).

Naming Convention

Use clear, consistent names:

Pattern: backup_YYYY-MM-DD_[optional-description].db

Examples:

• backup_2024-12-15.db (regular daily backup)
• backup_2024-12-31_end-of-year.db (special milestone)
• backup_2024-11-20_before-migration.db (before major change)

Benefits:

• Chronologically sortable
• Easy to identify purpose
• Scripts can filter by date pattern

Restoring Backups

Before You Restore

Ask yourself:

1. What are you restoring? (full database, specific users, usage logs?)
2. When was the backup taken? (data added after this point will be lost)
3. Why are you restoring? (accidental deletion, corruption, migration?)

DANGER

Restoring a backup overwrites the current database. All data added after the backup was taken will be permanently lost.

Full Restore via Admin UI

1. Log into Admin Bud-E dashboard
2. Navigate to Maintenance
3. Click Restore from Backup
4. Select your backup file (.db file)
5. Confirm (read the warning carefully)
6. Wait for upload and processing
7. Log out and log back in to verify

Full Restore via Command Line

If the Admin UI is unavailable:

# Stop the service
sudo systemctl stop admin-bude.service

# Backup current database (just in case)
cp /opt/bud-e/school-bud-e-middleware/admin_bude.db /tmp/current_db_backup.db

# Copy your backup file to the server (if not already there)
scp ~/backups/backup_2024-12-15.db user@server:/tmp/

# Replace the database
cp /tmp/backup_2024-12-15.db /opt/bud-e/school-bud-e-middleware/admin_bude.db

# Fix permissions
chown $USER:$USER /opt/bud-e/school-bud-e-middleware/admin_bude.db
chmod 644 /opt/bud-e/school-bud-e-middleware/admin_bude.db

# Restart the service
sudo systemctl start admin-bude.service

# Check status
sudo systemctl status admin-bude.service

Partial Restore (Advanced)

To restore only specific data (e.g., one user), you'll need SQLite tools:

# Extract user from backup
sqlite3 backup_2024-12-15.db "SELECT * FROM users WHERE username='teacher-smith';" > teacher_smith.sql

# Import into current database
sqlite3 admin_bude.db < teacher_smith.sql

WARNING

Partial restores require SQL knowledge. Test in a staging environment first.

Testing Restores

Don't wait for disaster to test your backups.

Monthly Restore Test

1. Set up a test environment (separate server or local VM)
2. Copy the latest backup
3. Restore it to the test environment
4. Verify:
   • Users exist and can authenticate
   • Credit balances are correct
   • Usage logs are intact
   • Providers and routes work
5. Document any issues

Benefits:

• Confirms backups are valid
• Identifies restore problems before disaster
• Trains admins on restore procedure

Backup Verification

After creating a backup, verify its integrity:

Method 1: File Size Check

# Typical database size: 10 MB - 500 MB (depends on usage history)
ls -lh backup_2024-12-15.db

# Compare to previous backups (should be similar or slightly larger)
ls -lh /opt/bud-e/backups/

Red flag: Backup is much smaller than expected (possible corruption or incomplete copy).

Method 2: SQLite Integrity Check

sqlite3 backup_2024-12-15.db "PRAGMA integrity_check;"
# Should output: ok

If not "ok": Backup is corrupted. Re-create it.

Method 3: Test Restore (Staging)

Best verification: Restore to a test environment and confirm functionality.

Retention Policy

Define how long to keep backups:

Example policy:

• Daily backups: Keep for 7 days
• Weekly backups: Keep for 4 weeks
• Monthly backups: Keep for 12 months
• Yearly backups: Keep indefinitely (or per legal requirements)

Implementation:

# In your backup script, add cleanup:
# Keep daily backups for 7 days
find "$BACKUP_DIR" -name "backup_*.db.gz" -mtime +7 -delete

# Keep weekly backups (first of each week) for 4 weeks
# Keep monthly backups (first of each month) for 12 months
# (Requires more complex logic, or manual curation)

Disaster Recovery Plan

Scenario: Your server crashes and is unrecoverable.

Step-by-Step Recovery

1. Provision new server:

• Same specs (2-4 vCPU, 4-8 GB RAM, Ubuntu LTS)
• Same region (EU, for compliance)

2. Install Admin Bud-E:

• Follow Installation Guide
• Stop before starting the service

3. Restore backup:

# Copy your latest backup to the new server
scp ~/backups/backup_2024-12-15.db.gpg newserver:/tmp/

# Decrypt
gpg --decrypt /tmp/backup_2024-12-15.db.gpg > /opt/bud-e/school-bud-e-middleware/admin_bude.db

# Fix permissions
chown $USER:$USER /opt/bud-e/school-bud-e-middleware/admin_bude.db
chmod 644 /opt/bud-e/school-bud-e-middleware/admin_bude.db

4. Start service:

sudo systemctl start admin-bude.service
sudo systemctl status admin-bude.service

5. Verify:

• Log into Admin UI
• Check user count
• Review credit balances
• Test a request from frontend

6. Update DNS (if domain changed):

• Point admin.yourschool.edu to new server IP
• Update TLS certificate

7. Notify users:

• "Service restored on new infrastructure"
• "No data loss" (if backup was recent)

Total downtime: 1-4 hours (depending on complexity).

Common Issues

Issue: Backup File is 0 KB

Cause: Service was running during copy, or disk full.

Solution:

1. Stop service before copying
2. Check disk space: df -h
3. Re-create backup

Issue: Restore Fails with "Database Locked"

Cause: Service is still running.

Solution:

1. Stop service: sudo systemctl stop admin-bude.service
2. Retry restore
3. Restart service

Issue: Restored Database Seems Old

Cause: Wrong backup file used.

Solution:

1. Check backup filename (date)
2. Compare database row counts:

   sqlite3 admin_bude.db "SELECT COUNT(*) FROM usage_logs;"

3. Use the correct (most recent) backup

Issue: Cannot Decrypt Backup

Cause: Lost password or wrong encryption method.

Solution:

• Try all known passwords
• Check if GPG vs. 7-Zip vs. other
• If password is lost and backup is encrypted: backup is unrecoverable

DANGER

Always store backup passwords securely. Test decryption regularly.

Compliance and Legal

GDPR Considerations

Backups contain personal data (usernames, usage logs).

Requirements:

1. Secure storage (encrypted, access-controlled)
2. Retention limits (don't keep forever)
3. Right to erasure (users can request deletion)

Handling erasure requests:

• Delete from live database immediately
• Backups can be retained for a short period (e.g., 30 days for recovery)
• After that, either:
  • Delete old backups
  • Anonymize data in future backups

Audit Trails

For compliance, maintain a backup log:

Date	Backup File	Created By	Stored Where	Verified
2024-12-15	backup_2024-12-15.db.gpg	Admin Alice	Google Drive	Yes
2024-12-14	backup_2024-12-14.db.gpg	Automated	Google Drive	Yes
2024-12-13	backup_2024-12-13.db.gpg	Automated	Google Drive	Yes

Keep this log secure (spreadsheet, ticketing system, or log file).

Best Practices Summary

1. Automate daily backups
2. Store off-site (encrypted)
3. Test restores monthly
4. Verify backup integrity (size, SQLite check)
5. Rotate old backups (retention policy)
6. Encrypt before uploading to cloud
7. Document restore procedure (this page + your specific setup)
8. Keep backup passwords secure (password manager)
9. Monitor backup job success (check logs weekly)
10. Review and update backup strategy annually

Next Steps

• Set up automated backup script
• Test restore procedure
• Configure off-site storage
• Review maintenance operations