Backup and Restore

Creating regular backups and knowing how to restore them is essential for protecting your Zodula application data. This comprehensive guide covers everything you need to know about backing up and restoring your application.

Why Backup and Restore?

Backups protect your data from:

• Accidental deletion - Human errors happen
• Data corruption - System failures can corrupt files
• Migration issues - Schema changes might cause problems
• Hardware failures - Disk failures can lose data
• Security incidents - Ransomware or other attacks

Quick Start

Creating a Backup

The simplest way to create a backup:

nailgun backup

This creates a timestamped backup in the .zodula_backup directory.

Restoring from Backup

Interactive mode (recommended):

nailgun restore

Direct mode (if you know the backup file):

nailgun restore --file /path/to/backup.zip

Understanding Backups

What Gets Backed Up

Your backup includes all data in the .zodula_data directory:

• Database files - All your application data
• Configuration files - App settings and preferences
• User data - User accounts, roles, and permissions
• Application state - Current state of your application
• Custom files - Any files stored in your app

Backup Process

When you run nailgun backup, the system:

1. Checks for data - Verifies .zodula_data directory exists
2. Creates backup directory - Sets up .zodula_backup if needed
3. Compresses data - Creates a timestamped ZIP file
4. Shows information - Displays backup size and location
5. Lists existing backups - Shows all available backups

Backup Naming Convention

Backups are automatically named with timestamps:

zodula-backup-2023-12-21T10-30-45-123Z.zip

Format: zodula-backup-YYYY-MM-DDTHH-MM-SS-sssZ.zip

When to Create Backups

Before Major Changes

Always backup before:

• Running migrations - Schema changes can be risky
• Updating Zodula - New versions might have breaking changes
• Deploying to production - Protect your live data
• Making major configuration changes - Settings modifications
• Experimenting with new features - Test safely

Regular Schedule

Create backups:

• Daily - For active development projects
• Weekly - For stable applications
• Before releases - Before deploying new versions
• After major milestones - When significant work is completed

Backup Management

Viewing Available Backups

# The backup command shows existing backups
$ nailgun backup

📋 Existing backups (3 total):
  1. zodula-backup-2023-12-21T10-30-45-123Z.zip (15.23 MB, 2023-12-21)
  2. zodula-backup-2023-12-20T15-20-30-456Z.zip (12.45 MB, 2023-12-20)
  3. zodula-backup-2023-12-19T09-15-20-789Z.zip (11.87 MB, 2023-12-19)

Backup Storage

Backups are stored in:

.zodula_backup/
├── zodula-backup-2023-12-21T10-30-45-123Z.zip
├── zodula-backup-2023-12-20T15-20-30-456Z.zip
└── zodula-backup-2023-12-19T09-15-20-789Z.zip

Understanding Restore

When to Restore

You might need to restore when:

• Data corruption - Files become unreadable or damaged
• Accidental deletion - Important data was deleted
• Migration failures - Schema changes caused problems
• System crashes - Hardware or software failures
• Testing changes - Reverting to a known good state
• Environment setup - Creating development environments

Restore Process

Interactive Restore

The safest way to restore:

$ nailgun restore

📋 Found 3 backup(s):
  1. zodula-backup-2023-12-21T10-30-45-123Z.zip (15.23 MB, 2023-12-21)
  2. zodula-backup-2023-12-20T15-20-30-456Z.zip (12.45 MB, 2023-12-20)
  3. zodula-backup-2023-12-19T09-15-20-789Z.zip (11.87 MB, 2023-12-19)

? Select a backup to restore: zodula-backup-2023-12-21T10-30-45-123Z.zip
? Are you sure you want to restore from /path/to/backup.zip? Yes

🔄 Restoring backup...
📦 Extracting backup...
✅ Backup restored successfully!
📁 Restored to: /path/to/.zodula_data
📊 Directory size: 15.23 MB

Direct Restore

If you know the backup file path:

$ nailgun restore --file /path/to/backup.zip

📁 Using backup file: /path/to/backup.zip
? Are you sure you want to restore from /path/to/backup.zip? Yes

🔄 Restoring backup...
📦 Extracting backup...
✅ Backup restored successfully!

What Happens During Restore

1. Lists available backups (in interactive mode)
2. Asks for confirmation - Prevents accidental data loss
3. Removes existing data - Deletes current .zodula_data directory
4. Extracts backup - Unzips the backup file
5. Verifies restoration - Ensures files were extracted correctly
6. Runs migrations - Applies any necessary database updates

⚠️ Important Warnings

Data Loss Warning: Restoring will completely replace your current .zodula_data directory. All existing data will be lost.

Always create a backup before restoring to avoid losing recent changes.

Common Scenarios

Scenario 1: Data Corruption

Problem: Your application data is corrupted and won't start.

Solution:

1. Create a backup of current state (if possible)
2. Restore from the most recent good backup
3. Verify the application works
4. Re-enter any data since the backup

Scenario 2: Accidental Deletion

Problem: You accidentally deleted important data.

Solution:

1. Stop making changes immediately
2. Restore from backup before the deletion
3. Check what data was lost
4. Re-enter any new data since backup

Scenario 3: Migration Failure

Problem: A migration caused issues and broke your app.

Solution:

1. Restore from backup before the migration
2. Investigate the migration issue
3. Fix the migration or skip it
4. Re-run migrations carefully

Scenario 4: Development Environment Setup

Problem: You need to set up a development environment.

Solution:

1. Create a new project directory
2. Restore from a production backup
3. Modify configuration for development
4. Start development server

Best Practices

Backup Best Practices

1. Regular Schedule - Create backups before major changes
2. Multiple Locations - Don't rely on a single backup location
3. Test Restores - Verify your backups work by testing restoration
4. Monitor Space - Keep track of disk space usage
5. Retention Policy - Keep recent backups, archive important ones

Restore Best Practices

1. Create Backup First - Always backup current state before restoring
2. Stop Application - Ensure no processes are using the data
3. Read Prompts - Don't skip confirmation steps
4. Test After Restore - Verify the application works correctly
5. Document Changes - Record what was restored and why

Advanced Strategies

Automated Backups

Create a backup script:

#!/bin/bash
# backup-script.sh

PROJECT_DIR="/path/to/your/project"
BACKUP_DIR="/path/to/backup/storage"
DATE=$(date +%Y%m%d_%H%M%S)

cd $PROJECT_DIR
nailgun backup

# Copy to remote location
cp .zodula_backup/*.zip $BACKUP_DIR/

# Keep only last 7 days
find $BACKUP_DIR -name "*.zip" -mtime +7 -delete

Cloud Storage Integration

Upload backups to cloud storage:

# Example with AWS S3
aws s3 cp .zodula_backup/latest-backup.zip s3://your-bucket/backups/

Testing Your Restore Process

Test your restore process regularly:

# Create a test directory
mkdir test-restore
cd test-restore

# Restore a backup
nailgun restore --file ../path/to/backup.zip

# Test the application
nailgun dev

# Clean up
cd ..
rm -rf test-restore

Troubleshooting

Common Backup Issues

Backup fails with "No space left"

# Check disk space
df -h

# Clean up old backups
rm .zodula_backup/old-backup.zip

Permission denied errors

# Check permissions
ls -la .zodula_data
ls -la .zodula_backup

# Fix permissions if needed
chmod 755 .zodula_data
chmod 755 .zodula_backup

Common Restore Issues

"Backup file not found"

# Check file path
ls -la /path/to/backup.zip

# Use absolute path
nailgun restore --file /full/path/to/backup.zip

"Backup file is corrupted"

# Test backup integrity
unzip -t backup-file.zip

# Try a different backup
nailgun restore

"Not enough disk space"

# Check available space
df -h

# Clean up space
rm old-files.zip

Security Considerations

Backup Security

• Secure storage - Store backups in secure locations
• Access control - Limit who can access backup files
• Encryption - Encrypt sensitive backups

Restore Security

• Verify source - Ensure backup files are from trusted sources
• Scan for malware - Check backups for security issues
• Audit access - Log who restores what and when

Next Steps

After mastering backup and restore:

• Deployment strategies - Production deployment
• CLI backup command - Advanced backup options
• CLI restore command - Advanced restore options

Summary

Backup and restore are essential skills for data protection. Remember to:

• ✅ Create regular backups before major changes
• ✅ Test your restore process regularly
• ✅ Store backups in multiple secure locations
• ✅ Always backup before restoring
• ✅ Read all confirmation prompts carefully
• ✅ Test the application after restoration

Your data is valuable - protect it with regular backups and know how to restore it when needed!