# Backup & restore

## What is backed up

Every night at 02:00 (Asia/Dubai) one **AES-256 encrypted** zip goes to the `backups` disk
(`storage/app/backups/almasa-cms/`), and to S3 as well if it is configured. Each zip contains:

| Inside the zip | What it is |
|---|---|
| `db-dumps/mysql-almasa_cms.sql` | Full database: contracts, users, settings, history, audit log |
| `storage/app/private/…` | Contract documents, payment proofs, generated report files |
| `storage/app/public/branding/…` | Logo uploaded in the Settings Center |
| `.env` | Server configuration, including `APP_KEY` |

Retention: all backups for 7 days, then daily for 16 days, weekly for 8 weeks, monthly for 4 months and
yearly for 2 years, capped at `BACKUP_MAX_STORAGE_MB`. A health check runs every day at 08:00, and
failures show up as in-app alerts and on **System → Backups**.

> **Two secrets you must keep off the server:** `BACKUP_ARCHIVE_PASSWORD` opens the zip, and `APP_KEY`
> decrypts the settings stored inside the database. The `.env` inside the zip contains `APP_KEY`, but you
> need the archive password to open the zip in the first place. Store both in a password manager or a
> sealed envelope.

## Restore (the whole system)

Use this after a server loss, or to move to a new server.

1. **Prepare the server** with [DEPLOYMENT.md](DEPLOYMENT.md) §1–§6. Stop before `migrate --seed`.
2. **Get the archive:** copy the latest zip from S3 or the old server to the new one. For example:
   ```bash
   scp 2026-10-04-02-00-00.zip almasa@new-server:/tmp/
   ```
3. **Unpack it.** The archive is AES-256 encrypted, which the standard `unzip` can't open, so use 7-Zip:
   ```bash
   sudo apt -y install 7zip
   mkdir /tmp/restore && cd /tmp/restore
   7z x /tmp/2026-10-04-02-00-00.zip        # asks for BACKUP_ARCHIVE_PASSWORD
   ```
4. **Restore `.env`:** copy `/tmp/restore/.env` to `/var/www/almasa/.env`. Keep the same `APP_KEY`.
   Change DB, Redis or URL values only if they differ on the new server.
5. **Restore the database:**
   ```bash
   mysql -u almasa -p almasa_cms < /tmp/restore/db-dumps/mysql-almasa_cms.sql
   ```
6. **Restore the files:**
   ```bash
   cd /var/www/almasa
   rsync -a /tmp/restore/storage/app/private/ storage/app/private/
   rsync -a /tmp/restore/storage/app/public/branding/ storage/app/public/branding/
   sudo chown -R almasa:www-data storage && sudo chmod -R ug+rwX storage
   ```
7. **Finish:**
   ```bash
   php artisan migrate --force            # only applies migrations newer than the backup
   php artisan optimize && php artisan filament:optimize && php artisan storage:link
   php artisan queue:restart
   ```
8. **Check:** sign in, open a few contracts and download one document, then check that
   **System → System health** is green.
9. **Clean up:** `rm -rf /tmp/restore /tmp/*.zip`. These files contain the full database.

## Restore only the database to a past point

Use this, for example, to undo a bad bulk import. First put the site in maintenance mode
(`php artisan down`) and take a fresh backup with **Back up now**, so you can return to the current state.
Then do steps 3 and 5 above and run `php artisan up`.

## Recover a single document or record

You don't need to restore over live data:
1. Unpack the archive as in step 3.
2. Import the dump into a **separate** database, e.g. `restore_check`.
3. Copy just the rows or files you need.
4. Drop the scratch database and delete `/tmp/restore`.

Deleted contracts are soft-deleted and can be restored from the app without any backup (**Contracts →
filter: Deleted**). Only a Super Admin can permanently delete one.

## Restore drill (recommended every 3 months)

Unpack the latest archive on any machine and import the dump into a scratch database. Then compare row
counts with production, e.g. `select count(*) from contracts;`. The drill was run on 2026-10-04: the archive
decrypted, the dump imported, and the contract and audit row counts matched.
