DevOps

/laravel-agent:backup:setup

Configure automated backups using spatie/laravel-backup

Overview

The /backup:setup command configures a comprehensive backup solution using the popular spatie/laravel-backup package. It handles package installation, configuration, notification setup, scheduling, and health monitoring for your Laravel application's database and files.

Usage

/laravel-agent:backup:setup [--destination=<local|s3|gcs|dropbox>] [--notify=<mail|slack|discord>]

Examples

# Interactive setup with prompts
/laravel-agent:backup:setup

# Setup with S3 destination
/laravel-agent:backup:setup --destination=s3

# Setup with S3 and Slack notifications
/laravel-agent:backup:setup --destination=s3 --notify=slack

# Setup with local storage and email notifications
/laravel-agent:backup:setup --destination=local --notify=mail

What Gets Configured

A complete backup setup includes the following components:

Component Location Description
Package composer.json spatie/laravel-backup installed via Composer
Configuration config/backup.php Backup sources, destinations, and cleanup settings
Filesystem Disk config/filesystems.php S3/GCS/Dropbox disk configuration if needed
Schedule app/Console/Kernel.php or bootstrap/app.php Automated backup, cleanup, and monitoring tasks
Environment .env Backup credentials and notification settings
Health Checks config/backup.php Maximum age and storage monitoring

Interactive Setup

When run without arguments, the command prompts you for configuration choices:

1. Backup Destination

  • Local storage - Store backups in the app's storage directory
  • Amazon S3 - Use AWS S3 for remote backup storage
  • Google Cloud Storage - Use GCS buckets for backups
  • Dropbox - Store backups in Dropbox
  • SFTP - Upload backups to an SFTP server

2. What to Backup

  • Full - Both database and files (recommended)
  • Database only - Faster, smaller backups for DB changes
  • Files only - Application files without database

3. Notification Channel

  • Email - Send notifications via Laravel's mail system
  • Slack - Post backup status to Slack channel
  • Discord - Send notifications to Discord webhook
  • None - Skip notifications (not recommended for production)

4. Backup Schedule

  • Daily - Recommended for most applications (1:30 AM)
  • Every 6 hours - For frequently changing data
  • Weekly - For rarely changing applications
  • Custom - Define your own cron schedule

5. Retention Policy

  • Standard - 7 daily, 4 weekly, 4 monthly backups
  • Minimal - 3 daily, 2 weekly backups (saves storage)
  • Extended - 14 daily, 8 weekly, 12 monthly backups

Configuration Details

Backup Sources

The configuration specifies what to include and exclude from backups:

<?php

return [
    'backup' => [
        'source' => [
            'files' => [
                'include' => [
                    base_path(),
                ],
                'exclude' => [
                    base_path('vendor'),
                    base_path('node_modules'),
                    storage_path('logs'),
                    storage_path('framework'),
                    base_path('.git'),
                ],
            ],
            'databases' => [
                'mysql',
            ],
        ],
    ],
];

Backup Destinations

Configure where backups should be stored. For S3, add a disk in config/filesystems.php:

<?php

// config/filesystems.php
'disks' => [
    's3-backup' => [
        'driver' => 's3',
        'key' => env('AWS_BACKUP_ACCESS_KEY_ID'),
        'secret' => env('AWS_BACKUP_SECRET_ACCESS_KEY'),
        'region' => env('AWS_BACKUP_DEFAULT_REGION', 'us-east-1'),
        'bucket' => env('AWS_BACKUP_BUCKET'),
        'url' => env('AWS_BACKUP_URL'),
        'endpoint' => env('AWS_BACKUP_ENDPOINT'),
    ],
];

Notification Configuration

Configure multiple notification channels for different backup events:

<?php

'notifications' => [
    'notifications' => [
        \Spatie\Backup\Notifications\Notifications\BackupHasFailedNotification::class => ['mail', 'slack'],
        \Spatie\Backup\Notifications\Notifications\BackupWasSuccessfulNotification::class => ['mail'],
        \Spatie\Backup\Notifications\Notifications\UnhealthyBackupWasFoundNotification::class => ['mail', 'slack'],
    ],

    'slack' => [
        'webhook_url' => env('BACKUP_SLACK_WEBHOOK_URL', ''),
    ],

    'discord' => [
        'webhook_url' => env('BACKUP_DISCORD_WEBHOOK_URL', ''),
    ],
];

Health Monitoring

Automatic checks ensure backups are fresh and not consuming too much storage:

<?php

'monitor_backups' => [
    [
        'name' => env('APP_NAME', 'laravel-backup'),
        'disks' => ['local', 's3-backup'],
        'health_checks' => [
            \Spatie\Backup\Tasks\Monitor\HealthChecks\MaximumAgeInDays::class => 1,
            \Spatie\Backup\Tasks\Monitor\HealthChecks\MaximumStorageInMegabytes::class => 5000,
        ],
    ],
];

Cleanup Strategy

Configure automatic cleanup to manage storage efficiently:

<?php

'cleanup' => [
    'strategy' => \Spatie\Backup\Tasks\Cleanup\Strategies\DefaultStrategy::class,

    'default_strategy' => [
        'keep_all_backups_for_days' => 7,
        'keep_daily_backups_for_days' => 16,
        'keep_weekly_backups_for_weeks' => 8,
        'keep_monthly_backups_for_months' => 4,
        'keep_yearly_backups_for_years' => 2,
        'delete_oldest_backups_when_using_more_megabytes_than' => 5000,
    ],
];

Environment Variables

The command adds these variables to your .env file:

# Backup configuration
BACKUP_ARCHIVE_PASSWORD=your-secure-password
BACKUP_NOTIFICATION_EMAIL=admin@yoursite.com

# Slack notifications (optional)
BACKUP_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# Discord notifications (optional)
BACKUP_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# S3 Backup destination (if using S3)
AWS_BACKUP_ACCESS_KEY_ID=your-access-key
AWS_BACKUP_SECRET_ACCESS_KEY=your-secret-key
AWS_BACKUP_DEFAULT_REGION=us-east-1
AWS_BACKUP_BUCKET=your-backup-bucket

Scheduled Tasks

The command adds these scheduled tasks to your application:

<?php

// app/Console/Kernel.php or bootstrap/app.php
$schedule->command('backup:clean')->daily()->at('01:00');
$schedule->command('backup:run')->daily()->at('01:30');
$schedule->command('backup:monitor')->daily()->at('03:00');

// Or for database-only backups (faster)
$schedule->command('backup:run --only-db')->daily()->at('01:30');

Available Commands

After setup, these Artisan commands become available:

# Run full backup (database + files)
php artisan backup:run

# Database only backup (faster)
php artisan backup:run --only-db

# Files only backup
php artisan backup:run --only-files

# List all backups
php artisan backup:list

# Check backup health
php artisan backup:monitor

# Clean old backups according to retention policy
php artisan backup:clean

Example Output

After successful configuration, you'll see a summary like this:

## Backup Configuration Complete

### Package Installed
- spatie/laravel-backup

### Configuration
- **Destination**: S3 (your-backup-bucket)
- **Content**: Full (database + files)
- **Schedule**: Daily at 01:30
- **Notifications**: Slack

### Environment Variables Added
BACKUP_ARCHIVE_PASSWORD=
BACKUP_SLACK_WEBHOOK_URL=
AWS_BACKUP_BUCKET=
AWS_BACKUP_ACCESS_KEY_ID=
AWS_BACKUP_SECRET_ACCESS_KEY=

### Commands Available
php artisan backup:run          # Run backup now
php artisan backup:run --only-db  # Database only
php artisan backup:list         # List all backups
php artisan backup:monitor      # Check health
php artisan backup:clean        # Clean old backups

### Schedule Added
- backup:clean - Daily at 01:00
- backup:run - Daily at 01:30
- backup:monitor - Daily at 03:00

### Next Steps
1. Add credentials to .env
2. Run `php artisan backup:run` to test
3. Verify backup in destination
4. Test restore procedure

Best Practices

  1. Use remote storage - Store backups off-site (S3, GCS) to protect against server failure
  2. Enable encryption - Set BACKUP_ARCHIVE_PASSWORD to encrypt backup archives
  3. Monitor health - Always enable notifications to catch backup failures
  4. Test restores - Regularly test restoration to verify backup integrity
  5. Exclude temporary files - Don't backup logs, cache, or vendor directories
  6. Use database-only for frequent backups - Run backup:run --only-db every few hours if needed
  7. Monitor storage costs - Adjust retention policy based on your budget and needs
  8. Set up monitoring alerts - Use Laravel Horizon or other tools to ensure cron is running

Backup Security

The setup includes several security features:

  • Password protection - Archives are encrypted with BACKUP_ARCHIVE_PASSWORD
  • Secure credentials - Cloud storage keys are stored in .env, never committed to git
  • Excluded sensitive data - Logs and temporary files are automatically excluded
  • Access control - Use IAM roles with minimal required permissions for cloud storage

Troubleshooting

  • Backup too large - Use --only-db flag or adjust exclusions in config
  • Timeout errors - Increase PHP max_execution_time or split into DB/files backups
  • S3 permission errors - Ensure IAM user has PutObject, GetObject, ListBucket permissions
  • Notifications not sending - Verify webhook URLs and mail configuration
  • Backups not running - Ensure cron is properly configured and running

See Also