From 0d73ee1db35d57d70a412de5ac7b4fb0018829a6 Mon Sep 17 00:00:00 2001 From: mwpn Date: Wed, 17 Dec 2025 10:48:59 +0700 Subject: [PATCH] docs: Add deployment guide dan fix vendor installation instructions --- DEPLOYMENT.md | 183 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 50 ++++++++++++-- 2 files changed, 229 insertions(+), 4 deletions(-) create mode 100644 DEPLOYMENT.md diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 0000000..c468f4c --- /dev/null +++ b/DEPLOYMENT.md @@ -0,0 +1,183 @@ +# Deployment Guide - Production + +## ⚠️ PENTING: Vendor Folder + +**Vendor folder TIDAK di-commit ke git repository!** + +Setiap kali deploy atau pull code baru, **WAJIB** jalankan: +```bash +composer install --no-dev --optimize-autoloader +``` + +## 🚀 Quick Deployment Steps + +### 1. First Time Deployment + +```bash +# 1. Clone repository +cd /www/wwwroot/api.btekno.cloud +git clone https://git.btekno.cloud/kangmin/api-btekno.git api + +# 2. Masuk ke folder project +cd api + +# 3. WAJIB: Install dependencies +composer install --no-dev --optimize-autoloader + +# 4. Setup environment +cp .env.example .env +nano .env # Edit dengan konfigurasi production + +# 5. Apply migrations +mysql -u sql_retribusi -p sql_retribusi < migrations/001_create_audit_logs.sql +mysql -u sql_retribusi -p sql_retribusi < migrations/002_create_hourly_summary.sql +mysql -u sql_retribusi -p sql_retribusi < migrations/003_create_realtime_events.sql + +# 6. Set permissions +chown -R www:www /www/wwwroot/api.btekno.cloud/api +chmod -R 755 /www/wwwroot/api.btekno.cloud/api +``` + +### 2. Update Deployment (Setelah Pull Code) + +```bash +# 1. Pull latest code +cd /www/wwwroot/api.btekno.cloud/api +git pull origin main + +# 2. WAJIB: Update dependencies (jika ada perubahan composer.json) +composer install --no-dev --optimize-autoloader + +# 3. Regenerate autoloader +composer dump-autoload --optimize + +# 4. Clear cache (jika ada) +# Tidak ada cache untuk project ini, skip +``` + +### 3. Setup aaPanel + +1. **Create Website**: + - Domain: `api.btekno.cloud` + - DocumentRoot: `/www/wwwroot/api.btekno.cloud/api/public` + - PHP Version: 8.2 atau 8.3 + +2. **PHP Settings**: + - Enable `extension=pdo_mysql` + - Enable `extension=mbstring` + - Memory limit: 256M (minimum) + +3. **Nginx/Apache Config**: + - Enable rewrite rules + - Point to `public/` directory + +## 🔧 Environment Configuration + +Edit `.env` file: + +```env +APP_ENV=production +APP_DEBUG=false + +# Database +DB_HOST=localhost +DB_NAME=sql_retribusi +DB_USER=sql_retribusi +DB_PASS=your_secure_password + +# JWT +JWT_SECRET=generate-random-secure-string-here +JWT_TTL_SECONDS=3600 +JWT_ISSUER=api-btekno + +# API Key +RETRIBUSI_API_KEY=generate-secure-api-key-here +``` + +**Generate secure keys:** +```bash +# JWT Secret (min 32 characters) +openssl rand -base64 32 + +# API Key +openssl rand -hex 32 +``` + +## 📋 Cron Jobs Setup + +Setup di aaPanel → Cron: + +```cron +# Daily summary (run at 1 AM every day) +0 1 * * * cd /www/wwwroot/api.btekno.cloud/api && /www/server/php/83/bin/php bin/daily_summary.php + +# Hourly summary (run at 1 AM every day) +0 1 * * * cd /www/wwwroot/api.btekno.cloud/api && /www/server/php/83/bin/php bin/hourly_summary.php +``` + +**Note**: Ganti `/www/server/php/83/bin/php` dengan path PHP yang sesuai di server Anda. + +## ✅ Verification + +Setelah deployment, test endpoint: + +```bash +# Health check +curl https://api.btekno.cloud/health + +# Should return: +# {"status":"ok","time":1735123456} +``` + +## 🐛 Common Issues + +### Error: vendor/autoload.php not found +**Cause**: Vendor folder belum di-install +**Solution**: +```bash +cd /www/wwwroot/api.btekno.cloud/api +composer install --no-dev --optimize-autoloader +``` + +### Error: Database connection failed +**Cause**: Database config salah di `.env` +**Solution**: +- Cek `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASS` di `.env` +- Test koneksi: `mysql -u sql_retribusi -p sql_retribusi` + +### Error: JWT secret not set +**Cause**: `JWT_SECRET` kosong di `.env` +**Solution**: Generate dan set JWT_SECRET di `.env` + +### Error: Permission denied +**Cause**: File permission salah +**Solution**: +```bash +chown -R www:www /www/wwwroot/api.btekno.cloud/api +chmod -R 755 /www/wwwroot/api.btekno.cloud/api +``` + +## 📊 Monitoring + +- Check logs: `/www/wwwroot/api.btekno.cloud/api/logs/` (jika ada) +- Check PHP error log di aaPanel +- Monitor database size dan performance +- Monitor realtime_events table (cleanup old data jika perlu) + +## 🔄 Rollback + +Jika ada masalah setelah update: + +```bash +# 1. Rollback ke commit sebelumnya +cd /www/wwwroot/api.btekno.cloud/api +git log --oneline # Lihat commit history +git checkout + +# 2. Reinstall dependencies +composer install --no-dev --optimize-autoloader + +# 3. Test endpoint +curl https://api.btekno.cloud/health +``` + diff --git a/README.md b/README.md index 562c2a8..ef275c3 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ Sistem API Retribusi berbasis Slim Framework 4 dengan arsitektur modular untuk i ## 🔧 Installation +### Development + 1. Clone repository: ```bash git clone https://git.btekno.cloud/kangmin/api-btekno.git @@ -44,10 +46,50 @@ mysql -u your_user -p your_database < migrations/002_create_hourly_summary.sql mysql -u your_user -p your_database < migrations/003_create_realtime_events.sql ``` -5. Setup web server: - - DocumentRoot: `public/` - - PHP 8.2+ - - Enable mod_rewrite (Apache) atau nginx config +### Production Deployment (aaPanel) + +**PENTING: Vendor folder TIDAK di-commit ke git. Harus di-install di server!** + +1. Clone atau pull repository: +```bash +cd /www/wwwroot/api.btekno.cloud/api +git pull origin main +``` + +2. **WAJIB: Install dependencies** (ini yang menyebabkan error jika di-skip): +```bash +composer install --no-dev --optimize-autoloader +``` + +3. Setup environment: +```bash +cp .env.example .env +nano .env # Edit dengan konfigurasi production +``` + +4. Apply migrations (jika belum): +```bash +mysql -u sql_retribusi -p sql_retribusi < migrations/001_create_audit_logs.sql +mysql -u sql_retribusi -p sql_retribusi < migrations/002_create_hourly_summary.sql +mysql -u sql_retribusi -p sql_retribusi < migrations/003_create_realtime_events.sql +``` + +5. Setup web server (aaPanel): + - DocumentRoot: `/www/wwwroot/api.btekno.cloud/api/public` + - PHP Version: 8.2 atau 8.3 + - Enable rewrite rules + +6. Set permissions: +```bash +chown -R www:www /www/wwwroot/api.btekno.cloud/api +chmod -R 755 /www/wwwroot/api.btekno.cloud/api +``` + +### Troubleshooting + +**Error: vendor/autoload.php not found** +- **Solusi**: Jalankan `composer install --no-dev --optimize-autoloader` di server +- Vendor folder tidak di-commit ke git, harus di-install manual di setiap environment ## 📁 Struktur Project