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:

php -m

---

3. Struktur Lokasi yang Disarankan

Contoh lokasi deploy:

/var/www/database-kesiswaan

Document root web server harus mengarah ke:

/var/www/database-kesiswaan/public

---

4. Fresh Deploy dari GitHub

4.1 Clone repository

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

Atau pakai SSH:

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:

./deploy.sh

Untuk staging / non-production:

APP_ENVIRONMENT=staging ./deploy.sh

Kalau perlu sekalian seed:

RUN_SEED=true ./deploy.sh

---

4.3 Alternatif manual (tanpa script)

Install dependency backend

composer install --no-dev --optimize-autoloader

Untuk server development / staging:

composer install

Install dependency frontend

npm install
npm run build

Kalau lingkungan development:

npm run dev

---

4.4 Siapkan file environment

Copy .env.example menjadi .env:

cp .env.example .env

Lalu edit:

nano .env

Minimal sesuaikan:

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

php artisan key:generate

---

4.6 Jalankan migration

php artisan migrate --force

Kalau perlu data awal admin:

php artisan db:seed --force

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

---

4.7 Buat symbolic link storage

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):

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)

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

a2enmod rewrite
systemctl reload apache2

---

5.2 Nginx (contoh server block)

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:

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:

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

6.5 Jalankan ulang

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:

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:

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:

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

8.2 Storage publik

Contoh:

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:

php artisan storage:link
ls -la public/storage

Problem: error permission Laravel

Cek:

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

Problem: perubahan view tidak muncul

Cek:

php artisan optimize:clear

Problem: migration gagal

Cek koneksi DB di .env lalu jalankan:

php artisan migrate:status

Problem: asset CSS/JS tidak tampil

Build ulang:

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

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

Update deploy

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

Backup manual

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

---

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