TenantAtlas/specs/032-backup-scheduling-mvp/quickstart.md

Quickstart: Backup Scheduling MVP (032)

This is a developer/operator quickstart for running the scheduling MVP locally with Sail.

Prerequisites

• Laravel Sail running
• Database migrated
• Queue worker running
• Scheduler running (or run the dispatch command manually)

Local setup (Sail)

1. Start Sail

• ./vendor/bin/sail up -d

2. Run migrations

• ./vendor/bin/sail php artisan migrate

3. Start a queue worker

• ./vendor/bin/sail php artisan queue:work

Run the dispatcher manually (MVP)

Once a schedule exists, you can dispatch due runs:

• ./vendor/bin/sail php artisan tenantpilot:schedules:dispatch

Optional: limit dispatching to specific tenants:

• ./vendor/bin/sail php artisan tenantpilot:schedules:dispatch --tenant=<tenant_id_or_external_id>

Run the Laravel scheduler

Recommended operations model:

• Dev/local: run schedule:work in a separate terminal

  • ./vendor/bin/sail php artisan schedule:work

• Production/staging (Dokploy): cron every minute

  • * * * * * php artisan schedule:run

Create a schedule (Filament)

• Log into Filament admin
• Switch into a tenant context
• Create a Backup Schedule:
  • frequency: daily/weekly
  • time + timezone
  • policy_types: pick from supported types
  • retention_keep_last
  • include_foundations

Verify outcomes

• In the schedule list: check Last Run and Next Run
• In run history: verify status, duration, error_code/message
• For successful/partial runs: verify a linked BackupSet exists

Retention

• After a successful/partial run creates a BackupSet, the retention job runs asynchronously and soft-deletes older BackupSets so only the last N (per schedule) remain.

Notes

• Unknown policy_types cannot be saved; legacy DB values are handled fail-safe at runtime.
• Scheduled runs do not notify a user; interactive actions (Run now / Retry) should persist a DB notification for the acting user.
• Run now / Retry actions are available for operator+ roles.