database-kesiswaan/DEPLOY.md

# DEPLOY.md - Database Kesiswaan

Panduan ini dibuat supaya aplikasi **Database Kesiswaan** mudah dipindahkan dan dideploy ke server baru tanpa bergantung pada ingatan manual.

---

## 1. Ringkasan Arsitektur Deploy

Pisahkan 3 hal ini dengan jelas:

1. **Source code**
   - Disimpan di GitHub repository project
   - Berisi code Laravel, migration, seeder, assets, docs

2. **Environment & runtime**
   - File `.env`
   - Database MySQL / MariaDB
   - Folder `storage/app/public`
   - Cache, logs, session runtime

3. **Backup**
   - Dump database
   - Backup file upload / storage publik
   - Salinan `.env` yang aman

> GitHub adalah source of truth untuk **kode**, bukan untuk data produksi.

---

## 2. Kebutuhan Server

Minimal server baru perlu:

- Linux server (Ubuntu/Debian direkomendasikan)
- Web server: **Apache** atau **Nginx**
- PHP **8.2+**
- Composer
- Node.js + npm
- MySQL / MariaDB
- Git

### PHP extensions yang dibutuhkan

Minimal pastikan extension berikut aktif:

- bcmath
- ctype
- curl
- dom
- fileinfo
- filter
- gd
- intl
- mbstring
- openssl
- pdo
- pdo_mysql
- session
- tokenizer
- xml
- zip

Cek cepat:

```bash
php -m
```

---

## 3. Struktur Lokasi yang Disarankan

Contoh lokasi deploy:

```bash
/var/www/database-kesiswaan
```

Document root web server harus mengarah ke:

```bash
/var/www/database-kesiswaan/public
```

---

## 4. Fresh Deploy dari GitHub

### 4.1 Clone repository

```bash
cd /var/www
git clone https://github.com/novysan87/database-kesiswaan.git
cd database-kesiswaan
```

Atau pakai SSH:

```bash
git clone git@github.com:novysan87/database-kesiswaan.git
cd database-kesiswaan
```

---

### 4.2 Cara deploy yang direkomendasikan

Setelah `.env` siap, gunakan script deploy bawaan project:

```bash
./deploy.sh
```

Untuk staging / non-production:

```bash
APP_ENVIRONMENT=staging ./deploy.sh
```

Kalau perlu sekalian seed:

```bash
RUN_SEED=true ./deploy.sh
```

---

### 4.3 Alternatif manual (tanpa script)

#### Install dependency backend

```bash
composer install --no-dev --optimize-autoloader
```

Untuk server development / staging:

```bash
composer install
```

#### Install dependency frontend

```bash
npm install
npm run build
```

Kalau lingkungan development:

```bash
npm run dev
```

---

### 4.4 Siapkan file environment

Copy `.env.example` menjadi `.env`:

```bash
cp .env.example .env
```

Lalu edit:

```bash
nano .env
```

Minimal sesuaikan:

```env
APP_NAME="Database Kesiswaan"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://domain-anda.com

LOG_CHANNEL=stack
LOG_LEVEL=error

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=database_kesiswaan
DB_USERNAME=kesiswaan
DB_PASSWORD=PASSWORD_DB_ANDA

FILESYSTEM_DISK=public
SESSION_DRIVER=file
CACHE_STORE=file
QUEUE_CONNECTION=database
```

> Jangan commit `.env` ke GitHub.

---

### 4.5 Generate APP_KEY

```bash
php artisan key:generate
```

---

### 4.6 Jalankan migration

```bash
php artisan migrate --force
```

Kalau perlu data awal admin:

```bash
php artisan db:seed --force
```

> Perhatikan seeder aktif di project. Pastikan tidak menimpa data produksi yang sudah ada.

---

### 4.7 Buat symbolic link storage

```bash
php artisan storage:link
```

Tanpa ini, file upload publik seperti dokumen dan branding tidak akan tampil.

---

### 4.8 Konfigurasi limit upload PHP (wajib untuk bulk upload dokumen lulusan)

Jika server produksi akan menggunakan fitur **Bulk Upload Dokumen Kelulusan**, pastikan limit upload PHP untuk web server tidak terlalu kecil. Jika tidak disesuaikan, request upload bisa gagal lebih dulu dengan error **413 Content Too Large** sebelum Laravel memproses file.

Untuk environment Apache + PHP 8.3, edit file:

```bash
sudo nano /etc/php/8.3/apache2/php.ini
```

Pastikan nilai berikut minimal:

```ini
upload_max_filesize = 8M
post_max_size = 64M
max_file_uploads = 50
```

Setelah diubah, reload Apache:

```bash
sudo systemctl reload apache2
```

Jika perubahan belum terbaca, lakukan restart:

```bash
sudo systemctl restart apache2
```

Catatan:
- perubahan ini adalah **konfigurasi server**, bukan source code Laravel
- `git pull` saja **tidak cukup** untuk menyelesaikan masalah upload besar / multi-file
- setting di atas dibuat agar selaras dengan fitur bulk upload dokumen lulusan yang mendukung banyak file dalam satu batch

---

### 4.9 Atur permission

Pastikan web server user bisa menulis ke folder berikut:

- `storage/`
- `bootstrap/cache/`

Contoh untuk Apache (`www-data`):

```bash
chown -R www-data:www-data /var/www/database-kesiswaan
find /var/www/database-kesiswaan -type f -exec chmod 644 {} \;
find /var/www/database-kesiswaan -type d -exec chmod 755 {} \;
chmod -R 775 /var/www/database-kesiswaan/storage
chmod -R 775 /var/www/database-kesiswaan/bootstrap/cache
```

> Sesuaikan user/group web server jika bukan `www-data`.

---

## 5. Konfigurasi Web Server

### 5.1 Apache (contoh VirtualHost)

```apache
<VirtualHost *:80>
    ServerName database-kesiswaan.local
    DocumentRoot /var/www/database-kesiswaan/public

    <Directory /var/www/database-kesiswaan/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/database-kesiswaan-error.log
    CustomLog ${APACHE_LOG_DIR}/database-kesiswaan-access.log combined
</VirtualHost>
```

Lalu:

```bash
a2enmod rewrite
systemctl reload apache2
```

---

### 5.2 Nginx (contoh server block)

```nginx
server {
    listen 80;
    server_name domain-anda.com;
    root /var/www/database-kesiswaan/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}
```

---

## 6. Fresh Deploy dengan Data Produksi Lama

Kalau server baru bukan install kosong, tetapi pindahan dari server lama:

### 6.1 Pindahkan source code
- clone dari GitHub

### 6.2 Pindahkan `.env`
- copy `.env` lama, lalu sesuaikan domain / host DB bila perlu

### 6.3 Restore database
Gunakan dump SQL lama:

```bash
mysql -u USER_DB -p database_kesiswaan < backup.sql
```

### 6.4 Pindahkan storage publik
Yang wajib ikut:

- `storage/app/public/branding`
- `storage/app/public/student-documents`
- `storage/app/public/student-exit-letters`
- `storage/app/public/student-transfer-letters`
- file publik lain hasil upload runtime

Contoh copy:

```bash
rsync -avz /server-lama/var/www/database-kesiswaan/storage/app/public/ /var/www/database-kesiswaan/storage/app/public/
```

### 6.5 Jalankan ulang

```bash
php artisan storage:link
php artisan optimize:clear
npm run build
```

---

## 7. Update Deploy (setelah ada perubahan baru)

Kalau server sudah live dan ingin update dari GitHub:

```bash
cd /var/www/database-kesiswaan
git pull origin main
composer install --no-dev --optimize-autoloader
npm install
npm run build
php artisan migrate --force
php artisan optimize:clear
```

Kalau perlu cache ulang:

```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

> Jangan cache route/config terlalu cepat saat masih sering debugging. Gunakan setelah yakin stabil.

---

## 8. Backup yang Wajib Dipahami

Supaya aplikasi benar-benar bisa dipulihkan, backup yang dibutuhkan adalah:

### 8.1 Database
Contoh:

```bash
mysqldump -u USER_DB -p database_kesiswaan > backup-database-kesiswaan.sql
```

### 8.2 Storage publik
Contoh:

```bash
tar -czf backup-storage-public.tar.gz storage/app/public
```

### 8.3 File `.env`
Simpan terpisah dan aman. Jangan masuk GitHub.

---

## 9. Hal yang Tidak Boleh Masuk GitHub

Pastikan hal berikut tetap **tidak** masuk repository:

- `.env`
- `vendor/`
- `node_modules/`
- `storage/logs/*`
- `storage/framework/views/*`
- `storage/app/public/*` hasil upload runtime
- dump database
- file backup manual
- dokumen siswa produksi
- token / credential / password

---

## 10. Post-Deploy Checklist

Gunakan checklist ini setelah deploy ke server baru.

### A. Validasi dasar
- [ ] `composer install` sukses
- [ ] `npm run build` sukses
- [ ] `.env` sudah benar
- [ ] `php artisan key:generate` sudah dijalankan
- [ ] `php artisan migrate --force` sukses
- [ ] `php artisan storage:link` sukses
- [ ] permission `storage/` dan `bootstrap/cache/` benar

### B. Validasi web
- [ ] halaman login bisa dibuka
- [ ] dashboard bisa dibuka setelah login
- [ ] branding/logo tampil normal
- [ ] halaman publik pencarian siswa tampil
- [ ] halaman publik `lengkapi-data-siswa` tampil

### C. Validasi data
- [ ] data siswa muncul
- [ ] branding settings terbaca
- [ ] dokumen siswa bisa dipreview
- [ ] surat keluar/mutasi lama masih bisa diakses
- [ ] region data tersedia normal

### D. Validasi storage
- [ ] folder branding terbaca
- [ ] upload baru bisa dilakukan
- [ ] file lama tetap tersedia

### E. Validasi keamanan minimum
- [ ] `APP_DEBUG=false` di production
- [ ] `.env` tidak bisa diakses publik
- [ ] document root mengarah ke `public/`
- [ ] repo GitHub private

---

## 11. Troubleshooting Cepat

### Problem: logo / dokumen tidak muncul
Cek:

```bash
php artisan storage:link
ls -la public/storage
```

### Problem: error permission Laravel
Cek:

```bash
chown -R www-data:www-data /var/www/database-kesiswaan
chmod -R 775 storage bootstrap/cache
```

### Problem: perubahan view tidak muncul
Cek:

```bash
php artisan optimize:clear
```

### Problem: migration gagal
Cek koneksi DB di `.env` lalu jalankan:

```bash
php artisan migrate:status
```

### Problem: asset CSS/JS tidak tampil
Build ulang:

```bash
npm install
npm run build
```

---

## 12. Rekomendasi Lanjutan

Agar deploy makin nyaman ke depan, pertimbangkan langkah berikut:

- buat script `deploy.sh`
- buat script backup otomatis database + storage publik
- tambahkan `HEALTHCHECK.md` / SOP operasional
- siapkan server staging jika aplikasi makin besar
- pertimbangkan CI/CD setelah alur deploy manual sudah stabil

---

## 13. Ringkasan Singkat Perintah Deploy

### Fresh install

```bash
cd /var/www
git clone https://github.com/novysan87/database-kesiswaan.git
cd database-kesiswaan
cp .env.example .env
./deploy.sh
```

### Update deploy

```bash
cd /var/www/database-kesiswaan
git pull origin main
./deploy.sh
```

### Backup manual

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

---

Kalau nanti arsitektur aplikasi berubah signifikan, update file ini juga supaya tetap relevan.