Add deployment, backup, and project documentation
This commit is contained in:
@@ -0,0 +1,542 @@
|
||||
# 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 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.
|
||||
Reference in New Issue
Block a user