Backup Server Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require moox/backup-server
   php artisan mooxbackupserver:install
   

   This publishes migrations, config, and sets up Filament resources.

2. Configure Spatie Backup Server:

   • Edit config/backup-server.php to define backup sources (e.g., databases, files).
   • Add SSH keys for remote servers in ~/.ssh/ or via config/backup-server.php.

3. First Use Case:

   • Navigate to /admin/backup-server (Filament UI).
   • Create a manual backup for a configured source (e.g., mysql or filesystem).
   • Verify backups appear in the "Backups" tab with status (e.g., completed, failed).

Where to Look First

• Filament UI: /resources/views/filament/backup-server/ (customize views if needed).
• Backup Definitions: config/backup-server.php (adjust sources, schedules, or storage paths).
• Logs: storage/logs/backup-server.log (debug issues).

Implementation Patterns

Core Workflows

1. Automated Backups:

   • Define schedules in config/backup-server.php:

     'schedules' => [
         'daily' => [
             'command' => 'backup:run --source=mysql --name=daily',
             'cron'   => '0 2 * * *',
         ],
     ],
     

   • Run via Artisan:

     php artisan schedule:run
     

2. Remote Server Backups:

   • Use SSH keys (add to ~/.ssh/authorized_keys on destination server).
   • Configure in config/backup-server.php:

     'connections' => [
         'remote-server' => [
             'type' => 'ssh',
             'host' => 'source-server.example.com',
             'username' => 'forge',
             'key' => '/path/to/private_key',
         ],
     ],
     

   • Reference in backup sources:

     'sources' => [
         'remote-mysql' => [
             'type' => 'database',
             'connection' => 'remote-server',
             'database' => 'app_db',
         ],
     ],
     

3. Filament Integration:

   • List Backups: Use the Backup resource to display all backups with metadata (size, duration, status).
   • Download/Restore: Add custom Filament actions to trigger downloads or restores:

     public static function getActions(Backup $record): array
     {
         return [
             Action::make('restore')
                 ->url(fn (Backup $record) => route('backups.restore', $record))
                 ->icon('heroicon-o-arrow-path'),
         ];
     }
     

4. Storage Backends:

   • Extend storage with S3, FTP, or custom drivers by publishing the config and modifying:

     'storage' => [
         'disks' => ['local', 's3'],
         'default' => 's3',
     ],
     

Pro Tips

• Testing: Use php artisan backup:run --dry-run to validate configurations without creating backups.
• Notifications: Extend the package to send Slack/Email alerts on backup failures via Filament notifications:

  event(new BackupFailed($backup));
  

• Custom Fields: Add metadata to backups by extending the Backup model:

  class Backup extends \Moox\BackupServer\Models\Backup
  {
      protected $casts = [
          'custom_metadata' => 'array',
      ];
  }
  

Gotchas and Tips

Pitfalls

1. SSH Key Permissions:

   • Ensure private keys have 600 permissions:

     chmod 600 ~/.ssh/private_key
     

   • Symptom: Backups fail silently with Connection refused or Permission denied.

2. Filament Caching:

   • Clear Filament cache after config changes:

     php artisan filament:cache-reset
     

   • Symptom: UI reflects old backup definitions.

3. Storage Paths:

   • Avoid spaces/special characters in backup paths (e.g., ~/Backups/My Backup).
   • Fix: Use absolute paths or URL-encoded names:

     'storage' => [
         'path' => '/backups/my_backup',
     ],
     

4. Large Backups:

   • Set max_execution_time in php.ini or use --chunk flag:

     php artisan backup:run --chunk=100
     

   • Symptom: Timeouts during backup creation.

Debugging

• Logs: Check storage/logs/backup-server.log for errors.
• Artisan Debug: Run backups with verbose output:

  php artisan backup:run --verbose
  

• SSH Debug: Enable verbose SSH:

  ssh -vvv forge@source-server.example.com
  

Extension Points

1. Custom Backup Sources:

   • Extend Moox\BackupServer\Backup\Sources\Source to add new source types (e.g., git repositories):

     class GitSource extends Source
     {
         public function getContents(): string
         {
             return shell_exec("git --git-dir={$this->path} archive --format=tar HEAD");
         }
     }
     

2. Pre/Post Hooks:

   • Add logic before/after backups via events:

     BackupStarting::dispatch($backup);
     BackupCompleted::dispatch($backup);
     

   • Listen in EventServiceProvider:

     public function boot()
     {
         BackupStarting::listen(function ($backup) {
             Log::info("Starting backup: {$backup->name}");
         });
     }
     

3. Filament Widgets:

   • Display backup stats in Filament dashboards:

     public static function getWidgets(): array
     {
         return [
             BackupStatsWidget::class,
         ];
     }
     

Config Quirks

• Default Storage: If storage.path is empty, backups default to storage/app/backups.

• Retention Policy: Configure in config/backup-server.php:

  'retention' => [
      'keep' => 30, // days
      'cleanup' => true,
  ],
  

  Run cleanup manually:

  php artisan backup:cleanup
  

• Environment Variables: Override config with .env:

  BACKUP_SERVER_STORAGE_PATH=/custom/backups
  BACKUP_SERVER_SCHEDULE_DAILY_CRON=0 3 * * *