Backup Bridge

A secure bridge, visual control dashboard, and multi-database backup agent for Laravel applications.

English | Bahasa Indonesia

📌 Overview

Conventional backup solutions (such as spatie/laravel-backup) excel at generating archive files locally on a single server. However, in enterprise environments managing dozens or hundreds of distributed applications, teams often need a centralized backup workflow that:

1. Pulls backups remotely without exposing raw SSH access or public database ports.
2. Verifies file integrity using streaming SHA-256 checksums.
3. Transfers archives to centralized NAS storage (QNAP / Synology / S3) or WebDAV (Nextcloud / ownCloud) via autonomous worker services.
4. Receives round-trip audit confirmation callbacks from external workers.
5. Provides a ready-to-use Visual Web Dashboard in the browser with zero complex admin panel dependencies.

Backup Bridge bridges the gap between individual Laravel apps and centralized backup orchestrators.

✨ Features

• 🗄️ Multi-Database Support: Automatic detection for MySQL, PostgreSQL (pg_dump), and SQLite (zero-dependency file snapshot), with full backward compatibility for spatie/laravel-backup.
• 📦 Public Attachments Backup: Automatically compresses public storage directories (storage/app/public) into a clean .zip archive.
• 🖥️ Built-in Control Dashboard: Responsive web interface (/admin/backups) to trigger manual backups, download dumps, copy SHA-256 hashes, and monitor worker sync status.
• ⚡ Universal Architecture Support: Works out of the box with Full-Stack Blade, Headless REST API, and Laravel Inertia.js (?json=1).
• 🔐 Hardened Security:
  • Constant-time X-API-Key verification (hash_equals) to prevent timing attacks.
  • Path-traversal protection and shell parameter sanitization.
  • Backups stored in protected private storage (storage/app/private/).
• 📡 Audit Callback Feedback Loop: Dedicated endpoint (POST /api/service-reports) receiving sync status and error logs from puller workers.
• 💻 Complete Artisan CLI: Commands including app-backup:run, app-backup:status, app-backup:install, and app-backup:key-generate.

🏗️ Architecture

⚠️ Important: How Backups are Triggered

[!IMPORTANT] Does installing this package immediately create a backup?

Not immediately. While this package is highly Plug and Play in terms of setup and auto-configuration, it operates as a Bridge / Agent rather than an instant background cron running upon composer require.

Backups are executed only when triggered via one of the 4 execution methods below.

🚀 Step-by-Step Setup Guide

1. Install via Composer

2. Run Automatic Installation (One-Command Setup)

This command automatically publishes the configuration and generates a cryptographically secure API key directly into your .env file:

3. Secure Web Dashboard in Production

By default, the dashboard uses the ['web'] middleware group. To restrict access to authenticated administrators in production, update config/app-backup.php:

4. Choose Your Backup Execution Method

Select the workflow that matches your infrastructure architecture:

🔄 4 Ways to Trigger / Run Backups

Method 1: Centralized Automation via Remote Worker (Recommended for Multi-App / NAS)

Use the companion microservice @putuwahyu29/backup-puller-worker. The worker handles scheduled pulls, verification, and uploads without placing ongoing cron load on your web server:

1. Copy the generated APP_BACKUP_API_KEY from your application's .env.
2. Add your application to the worker's apps.json:

The worker will automatically trigger fresh backups via API, verify the streaming SHA-256 hash, compress them into ZIP, and upload them to your QNAP NAS or Nextcloud/WebDAV.

Method 2: Local Scheduled Automation via Laravel Scheduler (CRON)

If you do not use an external worker and want the Laravel application to regularly back up locally on its own server:

For Laravel 11 / 12 / 13 (routes/console.php):

For Laravel 10 (app/Console/Kernel.php):

(Ensure your server's system cron has ` php /path-to-app/artisan schedule:run >> /dev/null 2>&1` configured)*.

Method 3: Manual via Web Dashboard

1. Open your browser and navigate to: http://your-app-domain.test/admin/backups
2. Click "Generate Database Backup" or "Generate Attachments Backup".
3. The backup file will be created on the fly, ready for instant download or SHA-256 inspection.

Method 4: Manual via Artisan CLI

Execute directly from your terminal:

🗄️ Server Requirements & Multi-Database Config

The default native driver reads your active database connection (config('database.default')):

A. MySQL / MariaDB

• Requirement: mysqldump binary available on the server / container host PATH.
• Environment (.env):

B. PostgreSQL

• Requirement: pg_dump binary installed on the server / container.
• Environment (.env):

C. SQLite

• Requirement: Zero external dependencies! Directly copies a snapshot of the .sqlite file.
• Environment (.env):

D. Public Attachments Archive

• Requirement: PHP ext-zip extension (ZipArchive) enabled.

🖥️ Usage in Laravel Inertia.js (Vue/React)

The dashboard controller provides a JSON API response when requested with Accept: application/json or query ?json=1:

🔌 API Endpoints for Remote Puller Worker

Protected by the X-API-Key HTTP header:

🛡️ Security

If you discover any security vulnerabilities, please contact the maintainers directly and avoid opening public issues before a patch is published.

📄 License

This package is open-source software licensed under the MIT License.
Developed by Putu Wahyu & Contributors.