Laravel Backup Server Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require spatie/laravel-backup-server
   php artisan vendor:publish --provider="Spatie\BackupServer\BackupServerServiceProvider"
   

   Publish the config file (config/backup-server.php) and migrations.

2. Configure Destinations Define a storage disk in config/filesystems.php (e.g., backup_disk with local driver) and create a Destination model:

   use Spatie\BackupServer\Models\Destination;
   
   Destination::create([
       'name' => 'primary_backup',
       'disk_name' => 'backup_disk',
       'capacity_in_mb' => 100000, // Optional: Set capacity for monitoring
   ]);
   

3. Add a Source Register a remote server as a source (via backup-server:sources table or Tinker):

   use Spatie\BackupServer\Models\Source;
   
   Source::create([
       'name' => 'production_app',
       'ssh_host' => 'user@remote-server.com',
       'backup_hour' => 3, // Run backups at 3 AM
       'includes' => ['/var/www/html', '/etc/nginx'],
       'excludes' => ['/var/www/html/storage/logs'],
       'pre_backup_commands' => ['mysqldump -u root -p db_name > /tmp/db_backup.sql'],
       'post_backup_commands' => ['rm /tmp/db_backup.sql'],
   ]);
   

4. Run a Backup Manually trigger a backup for a source:

   php artisan backup-server:backup production_app
   

   Or schedule it hourly via Laravel’s scheduler:

   // app/Console/Kernel.php
   protected function schedule(Schedule $schedule) {
       $schedule->command('backup-server:dispatch-backups')->hourly();
   }
   

5. Verify Backups Check source/destination health:

   php artisan backup-server:list --sortBy=healthy
   php artisan backup-server:list-destinations
   

Implementation Patterns

Workflows

1. Centralized Backup Management

   • Use the Backup Server as a single point to manage backups for multiple Laravel projects (e.g., staging, production).
   • Example: Configure a Destination for each environment (e.g., production_backups, staging_backups) and route sources accordingly.

2. Incremental Backups with Rsync

   • Leverage rsync for efficient transfers. Only changed files are copied; identical files use hard links to save space.
   • Tip: Exclude large, static files (e.g., /node_modules) from includes to reduce backup size.

3. Pre/Post-Backup Automation

   • Use pre_backup_commands to:
     • Dump databases (mysqldump, pg_dump).
     • Archive logs or temporary files.
   • Use post_backup_commands to:
     • Clean up temporary files.
     • Trigger post-backup scripts (e.g., notify monitoring tools).

4. Health Monitoring

   • Schedule a cron job to check source/destination health daily:

     php artisan backup-server:monitor-health
     

   • Pause notifications for sources during maintenance:

     Source::find(1)->update(['pause_notifications_until' => now()->addHours(2)]);
     

5. Cleanup Strategy

   • Automate cleanup via Laravel scheduler:

     $schedule->command('backup-server:cleanup')->daily();
     

   • Configure retention policies in Destination models (e.g., keep backups for 30 days).

6. Search and Restore

   • Locate files across backups:

     php artisan backup-server:find-files production_app "*.env"
     php artisan backup-server:find-content production_app "SECRET_KEY"
     

   • Restore files manually by copying from the destination disk (e.g., /storage/backup_disk/<source-id>/backup-<timestamp>/).

Integration Tips

1. Database Backups

   • Since the package doesn’t backup databases directly, use pre_backup_commands to dump databases to a file (e.g., /tmp/db_backup.sql) and include the file in includes.
   • Example:

     'pre_backup_commands' => [
         'mysqldump -u root -p db_name > /tmp/db_backup.sql',
         'gzip /tmp/db_backup.sql',
     ],
     'includes' => ['/tmp/db_backup.sql.gz'],
     'post_backup_commands' => ['rm /tmp/db_backup.sql.gz'],
     

2. Notifications

   • Extend notifications to include custom channels (e.g., Telegram, PagerDuty) using Laravel Notification Channels.
   • Example for Slack:

     // config/backup-server.php
     'notifications' => [
         \Spatie\BackupServer\Notifications\Notifications\BackupFailedNotification::class => ['mail', 'slack'],
     ],
     'slack' => [
         'webhook_url' => env('SLACK_WEBHOOK_URL'),
         'channel' => '#alerts',
     ],
     

3. SSH Key Management

   • Use SSH keys for authentication. Store private keys securely (e.g., Laravel’s config/backup-server.php or a secrets manager like AWS Secrets Manager).
   • Example:

     // config/backup-server.php
     'ssh' => [
         'private_key_path' => '/path/to/private_key',
         'passphrase' => env('SSH_KEY_PASSPHRASE'),
     ],
     

4. Testing Backups

   • Test backups by restoring a file to a staging environment:

     # Copy a file from backup to local
     cp /storage/backup_disk/<source-id>/backup-*/path/to/file /tmp/restored_file
     

   • Use rsync to verify integrity:

     rsync -avz --delete user@remote-server.com:/path/to/source /tmp/local_copy
     

5. Scaling Destinations

   • For large-scale deployments, use multiple Destination models with different disks (e.g., s3, local with different paths).
   • Example:

     Destination::create([
         'name' => 's3_backups',
         'disk_name' => 's3',
         'capacity_in_mb' => null, // S3 capacity is managed externally
     ]);
     

Gotchas and Tips

Pitfalls

1. SSH Connection Issues

   • Problem: Backups fail due to SSH authentication errors.
   • Fix:
     • Ensure the SSH key has the correct permissions (chmod 600 /path/to/private_key).
     • Verify the ssh_host format in Source models (e.g., user@hostname or hostname with ssh_username in config).
     • Test SSH manually:

       ssh -i /path/to/private_key user@remote-server.com
       

2. Permission Denied on Destination

   • Problem: The backup server can’t write to the destination disk.
   • Fix:
     • Ensure the Laravel storage directory has the correct permissions:

       chown -R www-data:www-data /storage/backup_disk
       chmod -R 755 /storage/backup_disk
       

     • For S3, verify the IAM user has PutObject permissions.

3. Hard Link Limitations

   • Problem: Restoring files from backups may fail if hard links are broken (e.g., after moving backups).
   • Fix:
     • Avoid moving backup directories after creation.
     • For critical restores, copy files instead of relying on hard links:

       cp -r /storage/backup_disk/<source-id>/backup-* /tmp/restore_target
       

4. Large Backup Size Calculations

   • Problem: Backups hang during size calculation for large directories.
   • Fix:
     • Increase the timeout in config/backup-server.php:

       'backup_size_calculation_timeout_in_seconds' => 3600, // 1 hour
       

     • Exclude large directories from backups (e.g., /var/lib/docker).

5. Notification Delays

   • Problem: Notifications are delayed or not sent.
   • Fix:
     • Check the pause_notifications_until field in sources table.
     • Verify the notifiable class in config/backup-server.php is correct.
     • Test notifications manually:

       php artisan backup-server:notify-healthy-sources
       

6. Rsync Overhead

   • Problem: rsync transfers are slow or fail for large files.
   • Fix:
     • Use compression:

       'rsync_options' => ['-z'], // Enable compression