add files
This commit is contained in:
luthfihadinugroho79
+504
@@ -0,0 +1,504 @@
|
||||
# 🗺️ WebGIS Persebaran Penduduk Miskin
|
||||
|
||||
**Sistem Pemetaan Geospasial berbasis React + Node.js + PostgreSQL/PostGIS**
|
||||
|
||||
---
|
||||
|
||||
## 📋 DAFTAR ISI
|
||||
|
||||
1. [Prasyarat](#prasyarat)
|
||||
2. [Instalasi PostgreSQL + PostGIS di XAMPP](#instalasi-postgresql--postgis)
|
||||
3. [Setup Database](#setup-database)
|
||||
4. [Setup Backend (Node.js)](#setup-backend)
|
||||
5. [Setup Frontend (React)](#setup-frontend)
|
||||
6. [Menjalankan Aplikasi](#menjalankan-aplikasi)
|
||||
7. [Struktur Folder](#struktur-folder)
|
||||
8. [API Endpoint Reference](#api-endpoint-reference)
|
||||
9. [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## ✅ PRASYARAT
|
||||
|
||||
Sebelum mulai, pastikan sudah terinstal:
|
||||
|
||||
| Software | Versi Minimum | Link Download |
|
||||
|----------|--------------|---------------|
|
||||
| **XAMPP** | 8.0+ | https://www.apachefriends.org |
|
||||
| **Node.js** | 18.x LTS | https://nodejs.org |
|
||||
| **PostgreSQL** | 14+ | https://www.postgresql.org/download |
|
||||
| **PostGIS** | 3.x | Diinstal via Stack Builder |
|
||||
| **Git** (opsional) | any | https://git-scm.com |
|
||||
|
||||
> ⚠️ **PENTING**: PostgreSQL dan PostGIS TIDAK termasuk dalam XAMPP standar.
|
||||
> XAMPP hanya menyediakan MySQL/MariaDB. Kita install PostgreSQL secara terpisah.
|
||||
|
||||
---
|
||||
|
||||
## 🐘 INSTALASI POSTGRESQL + POSTGIS
|
||||
|
||||
### Langkah 1: Install PostgreSQL
|
||||
|
||||
1. Download PostgreSQL dari https://www.postgresql.org/download/windows/
|
||||
2. Jalankan installer, ikuti wizard:
|
||||
- Port: **5432** (default)
|
||||
- Password superuser: catat dengan baik (contoh: `postgres123`)
|
||||
- Locale: sesuaikan (Indonesian)
|
||||
3. ✅ Centang "Stack Builder" di akhir instalasi
|
||||
|
||||
### Langkah 2: Install PostGIS via Stack Builder
|
||||
|
||||
1. Stack Builder otomatis terbuka setelah instalasi PostgreSQL
|
||||
2. Pilih server PostgreSQL Anda
|
||||
3. Expand kategori **Spatial Extensions**
|
||||
4. Centang **PostGIS** (versi terbaru)
|
||||
5. Klik Next dan ikuti proses download + instalasi
|
||||
6. Saat diminta "Create spatial database", **LEWATI** (kita buat manual)
|
||||
|
||||
### Langkah 3: Verifikasi Instalasi
|
||||
|
||||
Buka **SQL Shell (psql)** dari Start Menu:
|
||||
```sql
|
||||
-- Login dengan user postgres
|
||||
Password: [password yang Anda buat]
|
||||
|
||||
-- Cek PostGIS
|
||||
SELECT PostGIS_version();
|
||||
-- Output: "3.x USE_GEOS=1 ..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ SETUP DATABASE
|
||||
|
||||
### Langkah 1: Buat Database
|
||||
|
||||
Buka **pgAdmin 4** (tersedia di Start Menu setelah install PostgreSQL):
|
||||
|
||||
1. Klik kanan **Databases** → **Create** → **Database**
|
||||
2. Isi nama: `webgis_kemiskinan`
|
||||
3. Klik **Save**
|
||||
|
||||
**ATAU** via SQL Shell (psql):
|
||||
```sql
|
||||
CREATE DATABASE webgis_kemiskinan;
|
||||
\c webgis_kemiskinan
|
||||
```
|
||||
|
||||
### Langkah 2: Jalankan Script SQL
|
||||
|
||||
**Via pgAdmin 4:**
|
||||
1. Klik dua kali database `webgis_kemiskinan`
|
||||
2. Klik kanan → **Query Tool**
|
||||
3. Buka file: `database/schema.sql` (dari folder project)
|
||||
4. Klik tombol **▶ Execute** (F5)
|
||||
|
||||
**Via psql:**
|
||||
```bash
|
||||
# Pastikan Anda ada di folder project
|
||||
psql -U postgres -d webgis_kemiskinan -f database/schema.sql
|
||||
```
|
||||
|
||||
**Via Command Prompt:**
|
||||
```cmd
|
||||
cd C:\xampp\htdocs\webgis-kemiskinan
|
||||
"C:\Program Files\PostgreSQL\14\bin\psql.exe" -U postgres -d webgis_kemiskinan -f database\schema.sql
|
||||
```
|
||||
|
||||
### Langkah 3: Verifikasi Database
|
||||
|
||||
```sql
|
||||
-- Di pgAdmin Query Tool atau psql:
|
||||
\c webgis_kemiskinan
|
||||
|
||||
-- Cek tabel
|
||||
\dt
|
||||
|
||||
-- Output yang diharapkan:
|
||||
-- tabel_rumah_ibadah
|
||||
-- tabel_penduduk
|
||||
-- tabel_anggota_keluarga
|
||||
|
||||
-- Cek data dummy
|
||||
SELECT nama, jenis FROM tabel_rumah_ibadah;
|
||||
SELECT nama_kepala_keluarga FROM tabel_penduduk;
|
||||
|
||||
-- Cek PostGIS aktif
|
||||
SELECT PostGIS_version();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ SETUP BACKEND
|
||||
|
||||
### Langkah 1: Masuk ke Folder Backend
|
||||
|
||||
```bash
|
||||
cd webgis-kemiskinan\backend
|
||||
```
|
||||
|
||||
### Langkah 2: Install Dependensi
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Langkah 3: Konfigurasi Environment
|
||||
|
||||
Salin file `.env.example` menjadi `.env`:
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
copy .env.example .env
|
||||
|
||||
# Linux/Mac
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit file `.env` sesuai konfigurasi Anda:
|
||||
|
||||
```env
|
||||
# Server
|
||||
PORT=5000
|
||||
NODE_ENV=development
|
||||
|
||||
# Database PostgreSQL
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_NAME=webgis_kemiskinan
|
||||
DB_USER=postgres
|
||||
DB_PASSWORD=postgres123 ← GANTI dengan password Anda
|
||||
|
||||
# CORS
|
||||
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
|
||||
|
||||
# Upload
|
||||
UPLOAD_DIR=uploads
|
||||
MAX_FILE_SIZE=5242880
|
||||
|
||||
# Nominatim
|
||||
NOMINATIM_URL=https://nominatim.openstreetmap.org
|
||||
NOMINATIM_USER_AGENT=WebGIS-Kemiskinan/1.0
|
||||
```
|
||||
|
||||
### Langkah 4: Buat Folder Upload
|
||||
|
||||
```bash
|
||||
mkdir uploads
|
||||
```
|
||||
|
||||
### Langkah 5: Test Koneksi
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Output yang diharapkan:
|
||||
```
|
||||
🚀 Server berjalan di http://localhost:5000
|
||||
✅ Terhubung ke PostgreSQL + PostGIS
|
||||
📡 Mode: development
|
||||
```
|
||||
|
||||
Test via browser atau Postman:
|
||||
```
|
||||
GET http://localhost:5000/api/health
|
||||
```
|
||||
Response: `{"status":"ok","timestamp":"..."}`
|
||||
|
||||
---
|
||||
|
||||
## 🎨 SETUP FRONTEND
|
||||
|
||||
### Langkah 1: Masuk ke Folder Frontend
|
||||
|
||||
Buka terminal/CMD **baru**:
|
||||
|
||||
```bash
|
||||
cd webgis-kemiskinan\frontend
|
||||
```
|
||||
|
||||
### Langkah 2: Install Dependensi
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Langkah 3: Jalankan Development Server
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
VITE v5.x.x ready in 800ms
|
||||
|
||||
➜ Local: http://localhost:3000/
|
||||
➜ Network: http://192.168.x.x:3000/
|
||||
```
|
||||
|
||||
### Langkah 4: Buka di Browser
|
||||
|
||||
Buka: **http://localhost:3000**
|
||||
|
||||
---
|
||||
|
||||
## 🚀 MENJALANKAN APLIKASI (RINGKASAN)
|
||||
|
||||
Setiap kali ingin menjalankan aplikasi, buka **2 terminal terpisah**:
|
||||
|
||||
### Terminal 1 – Backend
|
||||
```bash
|
||||
cd webgis-kemiskinan\backend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Terminal 2 – Frontend
|
||||
```bash
|
||||
cd webgis-kemiskinan\frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Lalu buka browser: **http://localhost:3000**
|
||||
|
||||
---
|
||||
|
||||
## 📁 STRUKTUR FOLDER
|
||||
|
||||
```
|
||||
webgis-kemiskinan/
|
||||
│
|
||||
├── 📂 database/
|
||||
│ └── schema.sql # Script SQL lengkap (jalankan pertama kali)
|
||||
│
|
||||
├── 📂 backend/
|
||||
│ ├── package.json
|
||||
│ ├── .env.example # Salin ke .env dan isi konfigurasi
|
||||
│ ├── .env # Konfigurasi lokal Anda (jangan di-commit)
|
||||
│ └── src/
|
||||
│ ├── server.js # Entry point Express
|
||||
│ ├── config/
|
||||
│ │ └── database.js # Koneksi PostgreSQL Pool
|
||||
│ ├── controllers/
|
||||
│ │ ├── rumahIbadahController.js # CRUD + geospasial ibadah
|
||||
│ │ ├── pendudukController.js # CRUD + auto-assign ibadah
|
||||
│ │ ├── geocodeController.js # Reverse geocoding Nominatim
|
||||
│ │ └── dashboardController.js # Statistik & agregasi
|
||||
│ ├── routes/
|
||||
│ │ ├── rumahIbadah.js
|
||||
│ │ ├── penduduk.js
|
||||
│ │ ├── geocode.js
|
||||
│ │ ├── upload.js
|
||||
│ │ └── dashboard.js
|
||||
│ ├── middleware/
|
||||
│ │ └── upload.js # Multer file upload config
|
||||
│ └── uploads/ # Folder penyimpanan file upload
|
||||
│
|
||||
└── 📂 frontend/
|
||||
├── package.json
|
||||
├── vite.config.js # Proxy API ke backend
|
||||
├── index.html
|
||||
└── src/
|
||||
├── main.jsx # React entry point
|
||||
├── App.jsx # Router + Layout utama
|
||||
├── index.css # Global styles (dark theme)
|
||||
├── services/
|
||||
│ └── api.js # Axios API client
|
||||
└── pages/
|
||||
├── DashboardPage.jsx # Statistik & grafik
|
||||
├── MapPage.jsx # Peta interaktif Leaflet
|
||||
├── RumahIbadahPage.jsx # CRUD rumah ibadah
|
||||
└── PendudukPage.jsx # CRUD penduduk miskin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📡 API ENDPOINT REFERENCE
|
||||
|
||||
### Rumah Ibadah
|
||||
|
||||
| Method | Endpoint | Deskripsi |
|
||||
|--------|----------|-----------|
|
||||
| GET | `/api/rumah-ibadah` | Semua rumah ibadah. Query: `?jenis=Masjid` |
|
||||
| GET | `/api/rumah-ibadah/:id` | Detail + statistik penduduk |
|
||||
| GET | `/api/rumah-ibadah/terdekat` | Query: `?lat=X&lng=Y&limit=5` |
|
||||
| POST | `/api/rumah-ibadah` | Tambah baru |
|
||||
| PUT | `/api/rumah-ibadah/:id` | Update |
|
||||
| DELETE | `/api/rumah-ibadah/:id` | Hapus |
|
||||
|
||||
### Penduduk Miskin
|
||||
|
||||
| Method | Endpoint | Deskripsi |
|
||||
|--------|----------|-----------|
|
||||
| GET | `/api/penduduk` | Semua. Query: `?status_bantuan=true&limit=50` |
|
||||
| GET | `/api/penduduk/:id` | Detail + anggota keluarga |
|
||||
| POST | `/api/penduduk` | Tambah (multipart/form-data, auto-assign ibadah) |
|
||||
| PUT | `/api/penduduk/:id` | Update (multipart/form-data) |
|
||||
| PATCH | `/api/penduduk/:id/status` | Update status bantuan saja |
|
||||
| DELETE | `/api/penduduk/:id` | Hapus |
|
||||
|
||||
### Lainnya
|
||||
|
||||
| Method | Endpoint | Deskripsi |
|
||||
|--------|----------|-----------|
|
||||
| GET | `/api/geocode/reverse` | Query: `?lat=X&lng=Y` |
|
||||
| POST | `/api/upload` | Upload file (form field: `file`) |
|
||||
| GET | `/api/dashboard/statistik` | Data statistik dashboard |
|
||||
| GET | `/api/health` | Health check server |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 TROUBLESHOOTING
|
||||
|
||||
### ❌ Error: "ECONNREFUSED – Cannot connect to database"
|
||||
|
||||
**Penyebab:** PostgreSQL tidak berjalan atau password salah.
|
||||
|
||||
**Solusi:**
|
||||
1. Buka **Services** Windows (services.msc)
|
||||
2. Cari **postgresql-x64-14** → Klik **Start**
|
||||
3. Atau di Command Prompt: `net start postgresql-x64-14`
|
||||
4. Periksa password di file `.env`
|
||||
|
||||
---
|
||||
|
||||
### ❌ Error: "extension 'postgis' does not exist"
|
||||
|
||||
**Penyebab:** PostGIS belum terinstal atau belum diaktifkan di database.
|
||||
|
||||
**Solusi:**
|
||||
```sql
|
||||
-- Di pgAdmin, koneksi ke database webgis_kemiskinan
|
||||
CREATE EXTENSION IF NOT EXISTS postgis;
|
||||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Error: "npm: command not found"
|
||||
|
||||
**Penyebab:** Node.js belum terinstal atau belum ada di PATH.
|
||||
|
||||
**Solusi:**
|
||||
1. Download Node.js LTS dari https://nodejs.org
|
||||
2. Install dengan pilih "Add to PATH"
|
||||
3. Restart Command Prompt / terminal
|
||||
4. Test: `node --version` dan `npm --version`
|
||||
|
||||
---
|
||||
|
||||
### ❌ Error: "Port 5000 already in use"
|
||||
|
||||
**Solusi:**
|
||||
```cmd
|
||||
# Temukan proses yang menggunakan port 5000
|
||||
netstat -ano | findstr :5000
|
||||
|
||||
# Kill proses (ganti XXXX dengan PID)
|
||||
taskkill /PID XXXX /F
|
||||
```
|
||||
ATAU ganti port di `.env`: `PORT=5001`
|
||||
|
||||
---
|
||||
|
||||
### ❌ Peta tidak muncul (blank/grey)
|
||||
|
||||
**Penyebab:** Leaflet CSS tidak termuat dengan benar.
|
||||
|
||||
**Solusi:**
|
||||
Pastikan di file yang menggunakan Leaflet ada:
|
||||
```js
|
||||
import 'leaflet/dist/leaflet.css';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Reverse Geocoding gagal
|
||||
|
||||
**Penyebab:** Nominatim rate limit (max 1 request/detik) atau tidak ada internet.
|
||||
|
||||
**Solusi:**
|
||||
- Tunggu beberapa detik lalu coba kembali
|
||||
- Nominatim memerlukan koneksi internet aktif
|
||||
- Isi alamat secara manual jika offline
|
||||
|
||||
---
|
||||
|
||||
### ❌ Upload file gagal
|
||||
|
||||
**Penyebab:** Folder `uploads` tidak ada.
|
||||
|
||||
**Solusi:**
|
||||
```bash
|
||||
cd backend
|
||||
mkdir uploads
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌐 INTEGRASI XAMPP (Apache sebagai Reverse Proxy Opsional)
|
||||
|
||||
Jika ingin mengakses via `http://localhost/webgis` (tanpa port):
|
||||
|
||||
1. Aktifkan **mod_proxy** di XAMPP:
|
||||
Edit `C:\xampp\apache\conf\httpd.conf`, hilangkan tanda `#` dari:
|
||||
```
|
||||
LoadModule proxy_module modules/mod_proxy.so
|
||||
LoadModule proxy_http_module modules/mod_proxy_http.so
|
||||
```
|
||||
|
||||
2. Tambahkan konfigurasi di `httpd-vhosts.conf`:
|
||||
```apache
|
||||
<VirtualHost *:80>
|
||||
ProxyPass /api http://localhost:5000/api
|
||||
ProxyPassReverse /api http://localhost:5000/api
|
||||
DocumentRoot "C:/xampp/htdocs/webgis-kemiskinan/frontend/dist"
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
3. Build frontend: `cd frontend && npm run build`
|
||||
|
||||
4. Restart Apache di XAMPP Control Panel
|
||||
|
||||
---
|
||||
|
||||
## 📦 BUILD UNTUK PRODUCTION
|
||||
|
||||
### Frontend (Build Statis)
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
# Output: folder dist/ siap di-deploy
|
||||
```
|
||||
|
||||
### Backend (Jalankan Tanpa nodemon)
|
||||
```bash
|
||||
cd backend
|
||||
npm start
|
||||
# Atau dengan PM2: pm2 start src/server.js --name webgis-backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 TIPS PENGGUNAAN
|
||||
|
||||
1. **Menambah Rumah Ibadah**: Masuk ke menu "Rumah Ibadah" → Klik "Tambah" → Klik peta untuk memilih lokasi → Alamat otomatis terisi → Simpan
|
||||
|
||||
2. **Menambah Penduduk**: Masuk ke menu "Penduduk Miskin" → Klik "Tambah" → Klik peta untuk memilih lokasi rumah → Sistem otomatis menentukan rumah ibadah terdekat
|
||||
|
||||
3. **Melihat di Peta**: Masuk ke menu "Peta Interaktif" → Gunakan filter untuk menyaring tampilan → Klik marker untuk melihat detail
|
||||
|
||||
4. **Update Status Bantuan**: Di tabel Penduduk, klik tombol ✓ untuk toggle status sudah/belum dibantu
|
||||
|
||||
5. **Lokasi Saya**: Di halaman peta, klik tombol kompas 📍 untuk menampilkan posisi Anda
|
||||
|
||||
---
|
||||
|
||||
## 📄 LISENSI
|
||||
|
||||
MIT License – Bebas digunakan untuk keperluan pendidikan dan sosial.
|
||||
|
||||
---
|
||||
|
||||
*Dibuat dengan ❤️ untuk membantu pemetaan dan penanganan kemiskinan di Indonesia*
|
||||
Reference in New Issue
Block a user