WebGIS_Project/04/README.md

🗺️ WebGIS Persebaran Penduduk Miskin

Sistem Pemetaan Geospasial berbasis React + Node.js + PostgreSQL/PostGIS

---

📋 DAFTAR ISI

1. Prasyarat
2. Instalasi PostgreSQL + PostGIS di XAMPP
3. Setup Database
4. Setup Backend (Node.js)
5. Setup Frontend (React)
6. Menjalankan Aplikasi
7. Struktur Folder
8. API Endpoint Reference
9. 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:

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

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:

# Pastikan Anda ada di folder project
psql -U postgres -d webgis_kemiskinan -f database/schema.sql

Via Command Prompt:

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

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

cd webgis-kemiskinan\backend

Langkah 2: Install Dependensi

npm install

Langkah 3: Konfigurasi Environment

Salin file .env.example menjadi .env:

# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env

Edit file .env sesuai konfigurasi Anda:

# 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

mkdir uploads

Langkah 5: Test Koneksi

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:

cd webgis-kemiskinan\frontend

Langkah 2: Install Dependensi

npm install

Langkah 3: Jalankan Development Server

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

cd webgis-kemiskinan\backend
npm run dev

Terminal 2 – Frontend

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:

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

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

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:

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:

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

cd frontend
npm run build
# Output: folder dist/ siap di-deploy

Backend (Jalankan Tanpa nodemon)

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