docs: improve backup and restore guide for operators

docs/BACKUP_RESTORE.md

@@ -2,54 +2,106 @@
 
 Panduan backup dan pemulihan data untuk project `database-kesiswaan`.
 
-## Tujuan
+Dokumen ini dibuat supaya admin atau operator server bisa menjalankan backup rutin **tanpa perlu masuk ke UI aplikasi**.
-
+Fokusnya sederhana: **mudah dijalankan, mudah dicek hasilnya, dan mudah dipulihkan saat terjadi masalah**.
-Menyediakan mekanisme backup **tanpa UI aplikasi**, agar admin/server operator bisa menjalankan backup rutin langsung dari shell/cron.
-
-Yang diamankan:
-- database MySQL/MariaDB `database_kesiswaan`
-- file dokumen di `storage/app/public`
-- file `.env` (opsional, tapi sangat disarankan)
 
 ---
 
-## Struktur Script
+# 1. Yang Diamankan
 
-Semua script ada di folder:
+Mekanisme backup ini dirancang untuk mengamankan 3 komponen penting:
+
+1. **Database aplikasi**
+   - MySQL / MariaDB `database_kesiswaan`
+   - berisi data siswa, orang tua, dokumen, arsip, histori akademik, dan konfigurasi terkait
+
+2. **File dokumen**
+   - seluruh isi `storage/app/public`
+   - termasuk dokumen siswa, surat keluar, surat mutasi, dokumen kelulusan, branding, dan file upload lain
+
+3. **File `.env`**
+   - berisi konfigurasi aplikasi
+   - termasuk koneksi database dan pengaturan runtime penting
+   - sifatnya sensitif, jadi backup `.env` harus dijaga ketat
+
+---
+
+# 2. Script yang Tersedia
+
+Semua script berada di folder:
 
 ```bash
 /var/www/database-kesiswaan/scripts
 ```
 
-### 1. Backup database saja
+## A. Backup database saja
+
 ```bash
 ./scripts/backup-database-kesiswaan.sh
 ```
+
+Gunakan script ini jika:
+- hanya ingin mengamankan database
+- ingin backup lebih sering
+- ingin membuat snapshot data tanpa membackup file dokumen
+
 Output:
 - file `.sql.gz`
-- default lokasi: `/var/backups/database-kesiswaan/database`
 
-### 2. Backup dokumen saja
+Lokasi default:
-```bash
-./scripts/backup-dokumen-kesiswaan.sh
-```
-Output:
-- file `.tar.gz`
-- default lokasi: `/var/backups/database-kesiswaan/files`
 
-### 3. Backup penuh (direkomendasikan)
 ```bash
-./scripts/backup-full-kesiswaan.sh
+/var/backups/database-kesiswaan/database
 ```
-Output:
-- backup database
-- backup dokumen
-- salinan `.env`
-- manifest backup
 
 ---
 
-## Lokasi Backup Default
+## B. Backup dokumen saja
+
+```bash
+./scripts/backup-dokumen-kesiswaan.sh
+```
+
+Gunakan script ini jika:
+- hanya ingin mengamankan file dokumen
+- ingin copy/snapshot storage publik secara terpisah
+
+Output:
+- file `.tar.gz`
+
+Lokasi default:
+
+```bash
+/var/backups/database-kesiswaan/files
+```
+
+---
+
+## C. Backup penuh (direkomendasikan)
+
+```bash
+./scripts/backup-full-kesiswaan.sh
+```
+
+Ini adalah script utama yang paling direkomendasikan untuk backup rutin.
+
+Script ini akan:
+- backup database
+- backup dokumen
+- backup `.env`
+- membuat file manifest ringkas
+
+Output:
+- dump database `.sql.gz`
+- arsip dokumen `.tar.gz`
+- salinan `.env`
+- manifest `.txt`
+
+---
+
+# 3. Lokasi Backup Default
+
+Semua backup disimpan di:
 
 ```bash
 /var/backups/database-kesiswaan/
@@ -59,42 +111,85 @@ Output:
 └── manifests/
 ```
 
----
+Penjelasan:
-
+- `database/` → dump database
-## Retensi Default
+- `files/` → arsip dokumen/storage publik
-
+- `env/` → salinan `.env`
-Script menggunakan retensi default:
+- `manifests/` → catatan ringkas isi backup per timestamp
-
-```bash
-RETENTION_DAYS=14
-```
-
-Artinya backup lebih lama dari 14 hari akan dibersihkan otomatis.
-
-Kalau ingin ubah retensi saat menjalankan script:
-
-```bash
-RETENTION_DAYS=30 ./scripts/backup-full-kesiswaan.sh
-```
 
 ---
 
-## Menjalankan Manual
+# 4. Langkah Cepat untuk Admin
+
+Kalau admin hanya ingin menjalankan backup manual dengan cepat, cukup lakukan ini:
 
-### Backup penuh manual
 ```bash
 cd /var/www/database-kesiswaan
 chmod +x scripts/*.sh
 ./scripts/backup-full-kesiswaan.sh
 ```
 
-### Backup hanya database
+Kalau berhasil, akan muncul ringkasan lokasi file hasil backup.
+
+---
+
+# 5. Kapan Pakai Script yang Mana?
+
+## Gunakan `backup-full-kesiswaan.sh` jika:
+- backup harian rutin
+- backup sebelum update/deploy besar
+- backup sebelum migrasi server
+- backup sebelum perubahan data massal
+
+## Gunakan `backup-database-kesiswaan.sh` jika:
+- ingin snapshot database lebih sering
+- ingin memperkecil potensi kehilangan data antar backup harian
+
+## Gunakan `backup-dokumen-kesiswaan.sh` jika:
+- ingin backup file dokumen saja
+- sedang audit file upload
+- butuh arsip storage terpisah
+
+---
+
+# 6. Retensi Backup
+
+Default retensi backup adalah:
+
+```bash
+RETENTION_DAYS=14
+```
+
+Artinya file backup yang lebih lama dari 14 hari akan dibersihkan otomatis.
+
+Kalau ingin mengubah retensi saat menjalankan script:
+
+```bash
+RETENTION_DAYS=30 ./scripts/backup-full-kesiswaan.sh
+```
+
+Contoh di atas akan mempertahankan backup hingga 30 hari.
+
+---
+
+# 7. Menjalankan Backup Manual
+
+## Backup penuh
+
+```bash
+cd /var/www/database-kesiswaan
+./scripts/backup-full-kesiswaan.sh
+```
+
+## Backup database saja
+
 ```bash
 cd /var/www/database-kesiswaan
 ./scripts/backup-database-kesiswaan.sh
 ```
 
-### Backup hanya dokumen
+## Backup dokumen saja
+
 ```bash
 cd /var/www/database-kesiswaan
 ./scripts/backup-dokumen-kesiswaan.sh
@@ -102,47 +197,113 @@ cd /var/www/database-kesiswaan
 
 ---
 
-## Contoh Cron Rutin
+# 8. Contoh Hasil Backup Sukses
+
+Contoh output backup penuh:
+
+```bash
+Database: /var/backups/database-kesiswaan/database/database_kesiswaan-2026-04-14-010000.sql.gz
+Dokumen : /var/backups/database-kesiswaan/files/storage-public-2026-04-14-010000.tar.gz
+.env    : /var/backups/database-kesiswaan/env/env-2026-04-14-010000.backup
+Manifest: /var/backups/database-kesiswaan/manifests/backup-2026-04-14-010000.txt
+```
+
+Kalau output seperti ini muncul, berarti backup sudah berhasil dibuat.
+
+---
+
+# 9. Contoh Cron Rutin
+
+## Opsi paling sederhana: backup penuh setiap hari jam 01:00
 
-### Backup penuh setiap hari jam 01:00
 ```cron
 0 1 * * * cd /var/www/database-kesiswaan && /bin/bash ./scripts/backup-full-kesiswaan.sh >> /var/log/database-kesiswaan-backup.log 2>&1
 ```
 
-### Backup database saja setiap 6 jam
+Ini pilihan yang paling cocok untuk awal.
+
+---
+
+## Opsi lebih aman: database tiap 6 jam + backup penuh harian
+
+### Backup database tiap 6 jam
+
 ```cron
 0 */6 * * * cd /var/www/database-kesiswaan && /bin/bash ./scripts/backup-database-kesiswaan.sh >> /var/log/database-kesiswaan-db-backup.log 2>&1
 ```
 
-### Backup dokumen setiap hari jam 01:30
+### Backup penuh harian jam 01:00
+
 ```cron
-30 1 * * * cd /var/www/database-kesiswaan && /bin/bash ./scripts/backup-dokumen-kesiswaan.sh >> /var/log/database-kesiswaan-files-backup.log 2>&1
+0 1 * * * cd /var/www/database-kesiswaan && /bin/bash ./scripts/backup-full-kesiswaan.sh >> /var/log/database-kesiswaan-backup.log 2>&1
 ```
 
 ---
 
-## Restore Database
+# 10. Cara Memasang Cron
 
-Contoh restore dump database:
+Buka crontab user yang akan menjalankan backup:
+
+```bash
+crontab -e
+```
+
+Lalu tempel salah satu jadwal cron yang diinginkan.
+
+Setelah disimpan, cron akan berjalan otomatis sesuai jadwal.
+
+---
+
+# 11. Cara Cek Hasil Backup
+
+## Cek file hasil backup
+
+```bash
+ls -lah /var/backups/database-kesiswaan/database
+ls -lah /var/backups/database-kesiswaan/files
+ls -lah /var/backups/database-kesiswaan/env
+ls -lah /var/backups/database-kesiswaan/manifests
+```
+
+## Cek log cron
+
+```bash
+tail -f /var/log/database-kesiswaan-backup.log
+```
+
+atau:
+
+```bash
+tail -f /var/log/database-kesiswaan-db-backup.log
+```
+
+---
+
+# 12. Restore Database
+
+Untuk mengembalikan database dari file backup:
 
 ```bash
 gunzip -c /var/backups/database-kesiswaan/database/database_kesiswaan-YYYY-MM-DD-HHMMSS.sql.gz | mysql -u kesiswaan -p database_kesiswaan
 ```
 
-> Pastikan database target sudah ada dan kredensial benar.
+Catatan:
+- pastikan database tujuan sudah tersedia
+- pastikan user database punya izin import
+- pastikan file backup yang dipilih memang benar
 
 ---
 
-## Restore Dokumen
+# 13. Restore Dokumen
 
-Contoh restore dokumen:
+Untuk mengembalikan dokumen siswa dan file publik lain:
 
 ```bash
 mkdir -p /var/www/database-kesiswaan/storage/app/public
 tar -xzf /var/backups/database-kesiswaan/files/storage-public-YYYY-MM-DD-HHMMSS.tar.gz -C /var/www/database-kesiswaan/storage/app/public
 ```
 
-Lalu pastikan storage link tetap ada:
+Setelah itu jalankan:
 
 ```bash
 cd /var/www/database-kesiswaan
@@ -152,44 +313,109 @@ php artisan optimize:clear
 
 ---
 
-## Restore `.env`
+# 14. Restore File `.env`
 
-Kalau perlu mengembalikan `.env`:
+Kalau file `.env` perlu dipulihkan:
 
 ```bash
 cp /var/backups/database-kesiswaan/env/env-YYYY-MM-DD-HHMMSS.backup /var/www/database-kesiswaan/.env
 chmod 600 /var/www/database-kesiswaan/.env
 ```
 
+> Hati-hati: `.env` berisi data sensitif.
+
 ---
 
-## Checklist Setelah Restore
+# 15. Checklist Setelah Restore
+
+Setelah pemulihan selesai, cek hal berikut:
 
 - [ ] database berhasil di-restore
 - [ ] dokumen berhasil di-restore
 - [ ] `.env` benar
-- [ ] `php artisan optimize:clear` dijalankan
+- [ ] `php artisan optimize:clear` sudah dijalankan
 - [ ] `php artisan storage:link` valid
 - [ ] halaman login bisa dibuka
-- [ ] data siswa muncul
+- [ ] data siswa tampil
 - [ ] preview/download dokumen berjalan
 - [ ] portal publik berjalan normal
+- [ ] dokumen kelulusan bisa diakses bila tersedia
 
 ---
 
-## Rekomendasi Operasional
+# 16. Troubleshooting Ringan
+
+## A. Error `mysqldump: command not found`
+Pastikan `mysqldump` tersedia di server.
+Biasanya berasal dari package MySQL client / MariaDB client.
+
+## B. Error permission menulis ke `/var/backups/database-kesiswaan`
+Pastikan user yang menjalankan script punya izin tulis ke folder backup.
+
+Contoh:
+
+```bash
+mkdir -p /var/backups/database-kesiswaan
+chown -R $(whoami):$(whoami) /var/backups/database-kesiswaan
+```
+
+## C. Backup berhasil tapi file tidak ditemukan
+Cek:
+- path default backup
+- log cron
+- retensi jangan terlalu pendek
+
+## D. Restore dokumen berhasil tapi file tidak tampil di aplikasi
+Jalankan:
+
+```bash
+cd /var/www/database-kesiswaan
+php artisan storage:link
+php artisan optimize:clear
+```
+
+## E. Ingin simpan backup lebih lama
+Jalankan script dengan retensi lebih panjang:
+
+```bash
+RETENTION_DAYS=30 ./scripts/backup-full-kesiswaan.sh
+```
+
+---
+
+# 17. Rekomendasi Operasional
 
 1. Gunakan **backup penuh harian**.
-2. Simpan backup di disk/partisi yang cukup longgar.
+2. Kalau data aktif sering berubah, tambahkan **backup database tiap 6 jam**.
-3. Kalau memungkinkan, sinkronkan backup ke lokasi kedua (server lain / external storage).
+3. Simpan backup di lokasi yang tidak diexpose web server.
-4. Uji restore minimal sesekali, jangan hanya percaya backup berhasil dibuat.
+4. Kalau memungkinkan, salin backup ke lokasi kedua (external disk / server lain).
-5. Lindungi folder backup karena berisi data sensitif dan kemungkinan salinan `.env`.
+5. Uji restore sesekali, jangan hanya membuat backup tanpa pernah menguji pemulihannya.
+6. Lindungi folder backup karena berisi data sensitif.
 
 ---
 
-## Catatan Keamanan
+# 18. Catatan Keamanan
 
-- Folder backup bisa mengandung data sensitif.
+- Jangan expose `/var/backups/database-kesiswaan` ke publik.
-- Jangan expose `/var/backups/database-kesiswaan` ke web.
+- Jangan commit file backup ke GitHub.
-- Jangan commit backup ke GitHub.
+- Jangan bagikan isi `.env` backup ke sembarang pihak.
-- Jangan berikan izin baca sembarangan ke file backup `.env`.
+- File backup database dan dokumen berpotensi mengandung data pribadi siswa.
+
+---
+
+# 19. Rekomendasi Paling Praktis
+
+Kalau ingin paling sederhana dan aman, cukup lakukan dua hal ini:
+
+## Jalankan manual saat perlu
+```bash
+cd /var/www/database-kesiswaan
+./scripts/backup-full-kesiswaan.sh
+```
+
+## Pasang cron harian
+```cron
+0 1 * * * cd /var/www/database-kesiswaan && /bin/bash ./scripts/backup-full-kesiswaan.sh >> /var/log/database-kesiswaan-backup.log 2>&1
+```
+
+Dengan itu, aplikasi sudah punya fondasi backup operasional yang jauh lebih proper daripada backup manual sesekali tanpa pola.