Laravel Backup Server Laravel Package

Getting Started

Minimal Setup

1. Install the package on both the backup server and client applications:

   composer require spatie/laravel-backup-server
   

2. Publish configurations on both server and clients:

   php artisan vendor:publish --provider="Spatie\BackupServer\BackupServerServiceProvider" --tag="config"
   

3. Configure the server (config/backup-server.php):

   'storage' => storage_path('app/backups'),
   'allowed_clients' => ['client1.example.com', 'client2.example.com'],
   

4. Configure a client (config/backup-server.php):

   'server_url' => 'https://backup.example.com',
   'client_id' => 'client1.example.com',
   'client_secret' => env('BACKUP_CLIENT_SECRET'),
   

First Use Case: Sending a Backup

1. On the client, run a backup via laravel-backup:

   php artisan backup:run
   

2. Automate upload by adding a post-backup hook in app/Console/Kernel.php:

   protected function schedule(Schedule $schedule)
   {
       $schedule->command('backup:run')->daily();
       $schedule->command('backup-server:upload')->after('backup:run');
   }
   

Implementation Patterns

Centralized Backup Workflow

1. Client-Side:

   • Use laravel-backup to generate backups locally.
   • Configure backup-server to upload to the central server:

     'backup_server' => [
         'enabled' => true,
         'upload_after_backup' => true,
     ],
     

   • Automate with Laravel Scheduler or cron jobs.

2. Server-Side:

   • Store backups in a structured directory (e.g., storage/backups/{client_id}/{backup_name}.zip).
   • Validate clients via allowed_clients in config.
   • Clean up old backups using Laravel Backup’s retention policies:

     'retention' => [
         'keep_backups' => 30,
         'keep_days' => 365,
     ],
     

Multi-Environment Management

• Shared Config: Use environment variables for secrets (e.g., BACKUP_CLIENT_SECRET).
• Environment-Specific Clients: Deploy the same server package across staging, production, etc., with distinct client_ids.
• Tagging Backups: Extend the client config to include metadata:

  'backup_server' => [
      'tags' => ['production', 'database'],
  ],
  

Integration with Monitoring

• Log Uploads: Use Laravel’s logging to track uploads:

  \Log::info('Backup uploaded to server', ['client' => $clientId, 'backup' => $backupName]);
  

• Health Checks: Add a route to verify backup server connectivity:

  Route::get('/backup-health', function () {
      return response()->json(['status' => \Spatie\BackupServer\BackupServer::checkHealth()]);
  });
  

Gotchas and Tips

Common Pitfalls

1. Authentication Failures:

   • Ensure client_id and client_secret match the server’s allowed_clients and their respective secrets.
   • Debug: Check server logs for 403 Forbidden errors if uploads fail silently.

2. Storage Permissions:

   • The server’s storage/backups directory must be writable by the web server user (e.g., www-data or nginx).
   • Fix: Run chmod -R 755 storage/backups or adjust ownership:

     sudo chown -R www-data:www-data storage/backups
     

3. Large Backup Files:

   • Uploads may time out or fail due to PHP’s max_execution_time or post_max_size.
   • Workaround: Increase limits in php.ini or split backups into smaller chunks using laravel-backup's split_backup option.

4. Client-Side Configuration Overrides:

   • Client configs in config/backup-server.php override server defaults. Test locally before deploying:

     'server_url' => env('BACKUP_SERVER_URL', 'https://backup.example.com'),
     

Debugging Tips

• Enable Verbose Logging: Add to config/logging.php:

  'channels' => [
      'backup' => [
          'driver' => 'single',
          'path' => storage_path('logs/backup.log'),
          'level' => 'debug',
      ],
  ],
  

  Then log manually:

  \Log::debug('Backup upload started', ['data' => $backupData]);
  

• Test Uploads Locally: Use the backup-server:test-upload command to simulate uploads without affecting production:

  php artisan backup-server:test-upload --client=client1.example.com
  

Extension Points

1. Custom Storage: Override the default storage by binding a custom Spatie\BackupServer\Storage\Storage implementation in the server’s AppServiceProvider:

   public function register()
   {
       $this->app->bind(
           \Spatie\BackupServer\Storage\Storage::class,
           \App\CustomBackupStorage::class
       );
   }
   

2. Pre/Post-Processing: Extend the BackupServer class to add logic before/after uploads:

   namespace App\Services;
   
   use Spatie\BackupServer\BackupServer as BaseBackupServer;
   
   class BackupServer extends BaseBackupServer
   {
       protected function beforeUpload($backup)
       {
           // Encrypt the backup before upload
           $this->encryptBackup($backup);
       }
   }
   

   Then bind it in AppServiceProvider:

   $this->app->bind(\Spatie\BackupServer\BackupServer::class, \App\Services\BackupServer::class);
   

3. Web Interface: Use the backup-server:list command to build a custom dashboard for managing backups:

   Route::get('/backups', function () {
       return \Spatie\BackupServer\BackupServer::listBackups();
   });