Add server requirements documentation

2026-04-12 08:13:31 +00:00
parent 33a74298b1
commit b29c591285
2 changed files with 434 additions and 4 deletions
@@ -86,13 +86,19 @@ Project ini dibuat untuk membantu operasional sekolah dalam satu panel administr

 ## Requirement Minimum

- PHP 8.2+
- Composer
- Node.js + npm
+- PHP 8.3
+- Composer 2.x
+- Node.js 20 LTS + npm
 - MySQL / MariaDB
 - Git
 - Web server Apache atau Nginx

+Requirement server lengkap beserta command install untuk **Ubuntu 22.04** tersedia di:
+
+```bash
+SERVER_REQUIREMENTS.md
+```
+
 ---

 ## Instalasi Lokal / Fresh Setup
@@ -177,7 +183,13 @@ Lokasi backup default:

 ## Deploy ke Server Baru

-Panduan lengkap ada di file:
+Sebelum deploy, baca dulu requirement server di:
+
+```bash
+SERVER_REQUIREMENTS.md
+```
+
+Lalu lanjut ke panduan deploy lengkap di:

 ```bash
 DEPLOY.md
@@ -0,0 +1,418 @@
+# SERVER_REQUIREMENTS.md - Database Kesiswaan
+
+Panduan ini menjelaskan **requirement server** dan **perintah instalasi** yang dibutuhkan agar aplikasi **Database Kesiswaan** bisa berjalan dengan benar di **Ubuntu 22.04 LTS** tanpa aaPanel.
+
+Fokus file ini adalah:
+- versi software yang direkomendasikan
+- package yang wajib diinstall
+- extension PHP yang dibutuhkan aplikasi
+- requirement Node.js / npm untuk build asset frontend
+- Composer untuk dependency PHP
+- command verifikasi environment setelah instalasi
+
+---
+
+## 1. Target Environment
+
+Dokumen ini diasumsikan untuk:
+
+- **OS**: Ubuntu 22.04 LTS
+- **Web server**: Nginx atau Apache
+- **PHP**: 8.3
+- **Database**: MySQL / MariaDB
+- **Node.js**: 20 LTS
+- **Composer**: 2.x
+
+> Aplikasi ini sudah terbukti butuh Node modern untuk Vite build, dan butuh extension PHP tertentu agar Composer + Laravel bisa jalan normal.
+
+---
+
+## 2. Requirement Utama Aplikasi
+
+### PHP
+Gunakan:
+- **PHP 8.3**
+
+### PHP Extensions wajib
+Minimal extension yang harus tersedia:
+
+- bcmath
+- curl
+- dom
+- fileinfo
+- gd
+- intl
+- mbstring
+- openssl
+- pdo
+- pdo_mysql
+- tokenizer
+- xml
+- zip
+
+### Node.js
+Gunakan:
+- **Node.js 20 LTS**
+
+> Vite di project ini tidak kompatibel dengan Node 18.x lama pada deploy yang diuji. Minimal aman gunakan Node 20.
+
+### npm
+- ikut dari Node.js 20
+- pastikan `npm` bisa install dependency project dan menjalankan `npm run build`
+
+### Composer
+Gunakan:
+- **Composer 2.x**
+
+### Database
+- MySQL 8+ atau MariaDB yang kompatibel
+- database, username, dan password harus disiapkan sebelum migrate
+
+---
+
+## 3. Instalasi Paket Dasar Ubuntu 22
+
+Jalankan:
+
+```bash
+sudo apt update
+sudo apt install -y software-properties-common curl git unzip ca-certificates lsb-release apt-transport-https gnupg
+```
+
+---
+
+## 4. Instal PHP 8.3 di Ubuntu 22
+
+Karena Ubuntu 22 default belum selalu menyediakan PHP 8.3 standar, gunakan repository Ondrej PHP.
+
+### 4.1 Tambahkan repository PHP
+```bash
+sudo add-apt-repository ppa:ondrej/php -y
+sudo apt update
+```
+
+### 4.2 Install PHP 8.3 + extension yang dibutuhkan
+```bash
+sudo apt install -y \
+php8.3 \
+php8.3-cli \
+php8.3-fpm \
+php8.3-common \
+php8.3-bcmath \
+php8.3-curl \
+php8.3-gd \
+php8.3-intl \
+php8.3-mbstring \
+php8.3-mysql \
+php8.3-xml \
+php8.3-zip
+```
+
+> `php8.3-xml` penting karena menyediakan `ext-dom` dan `ext-xml`, yang dibutuhkan Composer package di aplikasi ini.
+
+### 4.3 Verifikasi PHP
+```bash
+php -v
+php -m | grep -E 'bcmath|curl|dom|fileinfo|gd|intl|mbstring|pdo_mysql|xml|zip'
+```
+
+Minimal pastikan output memuat:
+- dom
+- xml
+- pdo_mysql
+- mbstring
+- curl
+- zip
+- intl
+- gd
+- bcmath
+
+---
+
+## 5. Install Composer 2.x
+
+### 5.1 Download installer Composer
+```bash
+cd /tmp
+curl -sS https://getcomposer.org/installer -o composer-setup.php
+```
+
+### 5.2 Install Composer ke system
+```bash
+sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
+```
+
+### 5.3 Verifikasi Composer
+```bash
+composer --version
+```
+
+Target aman:
+- Composer 2.x
+
+---
+
+## 6. Install Node.js 20 LTS + npm
+
+Gunakan NodeSource.
+
+### 6.1 Tambahkan repository Node.js 20
+```bash
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+```
+
+### 6.2 Install Node.js
+```bash
+sudo apt install -y nodejs
+```
+
+### 6.3 Verifikasi Node dan npm
+```bash
+node -v
+npm -v
+```
+
+Target aman:
+- `node -v` → `v20.x.x`
+- `npm -v` → versi bawaan Node 20
+
+> Jangan deploy app ini dengan Node 18 lawas jika Vite build sudah terbukti meminta Node 20+.
+
+---
+
+## 7. Install Web Server
+
+Pilih salah satu.
+
+### Opsi A - Nginx
+```bash
+sudo apt install -y nginx
+```
+
+### Opsi B - Apache
+```bash
+sudo apt install -y apache2
+```
+
+Kalau pakai Apache, aktifkan rewrite:
+
+```bash
+sudo a2enmod rewrite
+sudo systemctl restart apache2
+```
+
+---
+
+## 8. Install Database Server
+
+### Opsi A - MySQL
+```bash
+sudo apt install -y mysql-server
+```
+
+### Opsi B - MariaDB
+```bash
+sudo apt install -y mariadb-server
+```
+
+Lalu buat database dan user aplikasi.
+
+Contoh MySQL/MariaDB:
+
+```sql
+CREATE DATABASE database_kesiswaan CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'kesiswaan'@'localhost' IDENTIFIED BY 'PASSWORD_ANDA';
+GRANT ALL PRIVILEGES ON database_kesiswaan.* TO 'kesiswaan'@'localhost';
+FLUSH PRIVILEGES;
+```
+
+> Sesuaikan nama database/user/password sesuai `.env` deploy.
+
+---
+
+## 9. Requirement Runtime Laravel
+
+Agar aplikasi berjalan normal setelah install package di atas, pastikan:
+
+### 9.1 Document root web server
+Harus mengarah ke:
+
+```bash
+/var/www/database-kesiswaan/public
+```
+
+Bukan ke root project.
+
+### 9.2 Permission folder
+Laravel harus bisa menulis ke:
+- `storage/`
+- `bootstrap/cache/`
+
+Contoh:
+
+```bash
+sudo 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 {} \;
+sudo chmod -R 775 /var/www/database-kesiswaan/storage
+sudo chmod -R 775 /var/www/database-kesiswaan/bootstrap/cache
+```
+
+### 9.3 Storage link
+```bash
+cd /var/www/database-kesiswaan
+php artisan storage:link
+```
+
+Tanpa ini, file branding, dokumen, dan file upload publik tidak akan tampil.
+
+---
+
+## 10. Verifikasi Requirement Setelah Instalasi
+
+Setelah semua paket terpasang, cek dengan command berikut:
+
+### PHP
+```bash
+php -v
+php -m | sort
+```
+
+### Composer
+```bash
+composer --version
+```
+
+### Node / npm
+```bash
+node -v
+npm -v
+```
+
+### Database
+```bash
+mysql --version
+```
+
+### Web server
+```bash
+nginx -v
+```
+atau
+```bash
+apache2 -v
+```
+
+---
+
+## 11. Checklist Requirement Sebelum Deploy Aplikasi
+
+Sebelum clone project dan jalankan deploy, pastikan:
+
+- [ ] Ubuntu 22.04 sudah update
+- [ ] PHP 8.3 terinstall
+- [ ] extension PHP wajib sudah aktif
+- [ ] Composer 2.x terinstall
+- [ ] Node.js 20 LTS terinstall
+- [ ] npm berjalan normal
+- [ ] MySQL / MariaDB terinstall
+- [ ] database aplikasi sudah dibuat
+- [ ] web server terinstall
+- [ ] user web server punya akses ke folder aplikasi
+
+---
+
+## 12. Error Umum yang Pernah Muncul dan Artinya
+
+### Error: `vite: command not found`
+Penyebab:
+- dependency npm belum terinstall
+- `node_modules` belum ada
+
+Solusi:
+```bash
+npm install
+```
+
+---
+
+### Error: `Vite requires Node.js version 20.19+ or 22.12+`
+Penyebab:
+- Node.js terlalu lama
+
+Solusi:
+- upgrade ke Node.js 20 LTS
+
+---
+
+### Error: `Cannot find native binding` saat `npm run build`
+Penyebab:
+- optional dependency npm gagal terpasang dengan benar
+
+Solusi:
+```bash
+rm -rf node_modules package-lock.json
+npm install
+npm run build
+```
+
+---
+
+### Error Composer: `ext-dom` missing / `ext-xml` missing
+Penyebab:
+- PHP XML extension belum ada
+
+Solusi:
+```bash
+sudo apt install -y php8.3-xml
+```
+
+---
+
+### Error Laravel migrate: `could not find driver`
+Penyebab:
+- `pdo_mysql` belum aktif
+
+Solusi:
+```bash
+sudo apt install -y php8.3-mysql
+```
+
+---
+
+## 13. Ringkasan Command Install Cepat
+
+Kalau Mas ingin jalur cepat untuk menyiapkan server Ubuntu 22 dari nol:
+
+```bash
+sudo apt update
+sudo apt install -y software-properties-common curl git unzip ca-certificates lsb-release apt-transport-https gnupg
+sudo add-apt-repository ppa:ondrej/php -y
+sudo apt update
+sudo apt install -y \
+php8.3 php8.3-cli php8.3-fpm php8.3-common \
+php8.3-bcmath php8.3-curl php8.3-gd php8.3-intl \
+php8.3-mbstring php8.3-mysql php8.3-xml php8.3-zip \
+nginx mysql-server
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+cd /tmp
+curl -sS https://getcomposer.org/installer -o composer-setup.php
+sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
+```
+
+---
+
+## 14. Setelah Requirement Beres
+
+Setelah requirement server ini aman, baru lanjut ke:
+
+- clone repository
+- copy `.env`
+- jalankan `./deploy.sh`
+
+Panduan deploy langkah penuh ada di:
+
+```bash
+DEPLOY.md
+```