novy/database-kesiswaan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5170e9a1f272418dfa53898f1aad51209b1373fd
database-kesiswaan/DEPLOY.md
T

10 KiB
Raw Blame History

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

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

Pastikan nilai berikut minimal:

upload_max_filesize = 8M
post_max_size = 64M
max_file_uploads = 50

Setelah diubah, reload Apache:

sudo systemctl reload apache2

Jika perubahan belum terbaca, lakukan restart:

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

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.

Reference in New Issue View Git Blame Copy Permalink