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 toexclude
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
) ornull
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.
2. Create a backup
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