database-kesiswaan/docs/BACKUP_RESTORE.md

# BACKUP_RESTORE.md - Database Kesiswaan

Panduan backup dan pemulihan data untuk project `database-kesiswaan`.

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**.

> **Catatan penting:** backup yang berhasil dibuat **belum otomatis berarti aman**. Backup baru benar-benar dipercaya kalau **pernah diuji restore** atau minimal diverifikasi integritas filenya. Prinsip sederhananya: **backup yang belum pernah dites restore = belum terbukti aman**.

---

# 1. Yang Diamankan

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
```

## 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`

Lokasi default:

```bash
/var/backups/database-kesiswaan/database
```

---

## 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/
├── database/
├── files/
├── env/
└── manifests/
```

Penjelasan:
- `database/` → dump database
- `files/` → arsip dokumen/storage publik
- `env/` → salinan `.env`
- `manifests/` → catatan ringkas isi backup per timestamp

---

# 4. Langkah Cepat untuk Admin

Kalau admin hanya ingin menjalankan backup manual dengan cepat, cukup lakukan ini:

```bash
cd /var/www/database-kesiswaan
chmod +x scripts/*.sh
./scripts/backup-full-kesiswaan.sh
```

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 dokumen saja

```bash
cd /var/www/database-kesiswaan
./scripts/backup-dokumen-kesiswaan.sh
```

---

# 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

```cron
0 1 * * * cd /var/www/database-kesiswaan && /bin/bash ./scripts/backup-full-kesiswaan.sh >> /var/log/database-kesiswaan-backup.log 2>&1
```

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 penuh harian 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
```

---

# 10. Cara Memasang Cron

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
```

Catatan:
- pastikan database tujuan sudah tersedia
- pastikan user database punya izin import
- pastikan file backup yang dipilih memang benar

---

# 13. 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
```

Setelah itu jalankan:

```bash
cd /var/www/database-kesiswaan
php artisan storage:link
php artisan optimize:clear
```

---

# 14. Restore File `.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.

---

# 15. Verifikasi Backup Setelah Dibuat

Setelah backup selesai dibuat, sangat disarankan melakukan verifikasi ringan:

## A. Cek integritas file backup database
```bash
gzip -t /var/backups/database-kesiswaan/database/nama-file.sql.gz
```

## B. Cek isi awal dump database
```bash
gunzip -c /var/backups/database-kesiswaan/database/nama-file.sql.gz | head
```

## C. Cek isi arsip dokumen
```bash
tar -tzf /var/backups/database-kesiswaan/files/nama-file.tar.gz | head
```

## D. Cek file `.env` backup
```bash
ls -lah /var/backups/database-kesiswaan/env
```

Verifikasi ringan ini membantu memastikan file backup tidak rusak secara kasat mata.
Namun, verifikasi terbaik tetap **uji restore** ke lokasi atau database test.

---

# 16. Checklist Setelah Restore

Setelah pemulihan selesai, cek hal berikut:

- [ ] database berhasil di-restore
- [ ] dokumen berhasil di-restore
- [ ] `.env` benar
- [ ] `php artisan optimize:clear` sudah dijalankan
- [ ] `php artisan storage:link` valid
- [ ] halaman login bisa dibuka
- [ ] data siswa tampil
- [ ] preview/download dokumen berjalan
- [ ] portal publik berjalan normal
- [ ] dokumen kelulusan bisa diakses bila tersedia

---

# 17. 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
```

---

# 18. Rekomendasi Operasional

1. Gunakan **backup penuh harian**.
2. Kalau data aktif sering berubah, tambahkan **backup database tiap 6 jam**.
3. Simpan backup di lokasi yang tidak diexpose web server.
4. Kalau memungkinkan, salin backup ke lokasi kedua (external disk / server lain).
5. Uji restore sesekali, jangan hanya membuat backup tanpa pernah menguji pemulihannya.
6. Lindungi folder backup karena berisi data sensitif.

---

# 19. Catatan Keamanan

- Jangan expose `/var/backups/database-kesiswaan` ke publik.
- Jangan commit file backup ke GitHub.
- Jangan bagikan isi `.env` backup ke sembarang pihak.
- File backup database dan dokumen berpotensi mengandung data pribadi siswa.

---

# 20. 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.