Backups

UNIT3D offers built in backup tools, available through the web dashboard or via Artisan commands, allowing you to create, manage, and restore your application snapshots.

1. Configuration

Customize config/backup.php in your editor and adjust settings as needed; inline notes outline the available configuration parameters.

Key structure:

backup
- name
- source
  - files
    
    Specifies which directories and files to include and which to exclude in the backup.
```
    'include' => [
        base_path(),
     ],

    'exclude' => [
        base_path(),
        base_path('vendor'),
        base_path('node_modules'),
        base_path('storage'),
        base_path('public/vendor/joypixels'),
     ],
```
    - follow_links
    - ignore_unreadable_directories
    - relative_path
  - databases
    
    Specifies the database connections to back up.
- database_dump_compressor
  
  Compressor class (e.g. Spatie\DbDumper\Compressors\GzipCompressor::class) or null to disable.
- destination
  
  Defines the storage location for backup files.
- temporary_directory
Staging directory for temporary files.
notifications

Define when and how backup events trigger alerts via mail, Slack, or custom channels.
monitor_backups

Detect backup issues; triggers UnhealthyBackupWasFound when needed.

cleanup

Define how long to keep backups and when to purge old archives.

strategy

default_strategy

Keeps all backups for 7 days; then retains daily backups for 16 days, weekly for 8 weeks, monthly for 4 months, and yearly for 2 years. Deletes old backups exceeding 5000 MB.

    '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,

security

Ensure that only someone with your APP_KEY can decrypt and restore snapshots.

You can access the built-in Backups dashboard from the Staff menu. It shows each backup’s status, health, size, and count, and lets administrators launch unscheduled full, database, or files-only backups instantly. Another approach is to use the command line.

[!IMPORTANT] Backups initiated via the Staff Dashboard buttons may timeout on very large installations.

The following artisan commands are available:
```
php artisan backup:run
```
Creates a timestamped ZIP of application files and database.
```
php artisan backup:run --only-db
```
Creates a timestamped ZIP containing only the database.
```
php artisan backup:run --only-files
```
Creates a timestamped ZIP containing only application files.

3. Viewing backup list

List existing backups:
```
php artisan backup:list
```

4. Restoring a backup

[!WARNING] Always test backup restoration procedures on a non‑critical environment before applying to production. Incorrect restoration can lead to data loss or service disruption.

Install prerequisites (Debian/Ubuntu):

sudo apt update && sudo apt install p7zip-full -y

Retrieve your application key:
```
grep '^APP_KEY=' /var/www/html/.env
```
Extract the outer archive (enter APP_KEY when prompted):
```
7z x [UNIT3D]YYYY-MM-DD-HH-MM-SS.zip
```
Unzip inner archive, if generated:
```
7z x backup.zip
```

[!NOTE] Full backups will contain two parts; the files backup and a database backup or dump file.

Restoring the files backup:

Copy restored files to webroot:

sudo cp -a ~/tempBackup/var/www/html/. /var/www/html/

Fix file permissions:

sudo chown -R www-data:www-data /var/www/html
sudo find /var/www/html -type f -exec chmod 664 {} \;
sudo find /var/www/html -type d -exec chmod 775 {} \;

Restoring the database backup:

Retrieve your database credentials:
```
grep '^DB_' /var/www/html/.env
```

Restore your database:

mysql -u unit3d -p unit3d < ~/tempBackup/db-dumps/mysql-unit3d.sql

5. Reset & Cleanup

After restoring backups, ensure to reset configurations and clean up temporary files to maintain system integrity.

Fix permissions:

sudo chown -R www-data:www-data /var/www/html
sudo find /var/www/html -type f -exec chmod 664 {} \;
sudo find /var/www/html -type d -exec chmod 775 {} \;

Reinstall Node dependencies & rebuild (if assets need it):

sudo rm -rf node_modules && sudo bun install && sudo bun run build

Clear caches & restart services:

cd /var/www/html
sudo php artisan set:all_cache
sudo systemctl restart php8.4-fpm
sudo php artisan queue:restart

UNIT3D Documentation