Hotspot Management System

A comprehensive WiFi billing system with M-Pesa integration, loan management, and MikroTik hotspot control.

Screenshots

!connections and payments Dashboard view showing user connections and payments.

!Billing interface and loan options Billing interface with M-Pesa integration and loan options.

!Admin dashboard Admin dashboard.

!Admin panel overview Admin panel overview.

Features

• 🔐 Secure Authentication - JWT-based user authentication
• 💳 M-Pesa Integration - Mobile money payments for WiFi access
• 💰 Loan System - Credit-based WiFi access for users
• 🌐 MikroTik Integration - Automated hotspot user management
• 📊 Admin Dashboard - Real-time monitoring and management
• 📱 Responsive UI - Modern React/Next.js frontend
• 🔄 Real-time Updates - WebSocket notifications

Quick Deploy to Render

🚀 One-Click Deploy

1. Fork this repository to your GitHub account

1. Connect to Render:

1. Configure Environment Secrets:

| Variable | Description | Example | |----------|-------------|---------| | JWT_SECRET | Secure random string for JWT | your-secure-random-jwt-secret | | ADMIN_USERNAME | Admin login username | admin | | ADMIN_PASSWORD | Admin login password | secure_password_123 | | ADMIN_EMAIL | Admin email | [email protected] | | MPESA_CONSUMER_KEY | M-Pesa API key | From Safaricom Portal | | MPESA_CONSUMER_SECRET | M-Pesa API secret | From Safaricom Portal | | MPESA_SHORTCODE | Your M-Pesa shortcode | 123456 | | MPESA_PASSKEY | M-Pesa passkey | From Safaricom Portal | | MIKROTIK_HOST | MikroTik router IP | 192.168.88.1 | | MIKROTIK_USER | MikroTik username | admin | | MIKROTIK_PASSWORD | MikroTik password | your_password |

1. Deploy:

Local Development

Prerequisites

• Node.js 18+
• PostgreSQL (or use Docker)
• Git

Setup

# Clone repository
git clone <your-repo-url>
cd wifi_billing
Install dependencies
npm install
Copy environment file
cp .env.example .env
Configure your environment variables in .env
Generate Prisma client
npx prisma generate
Run database migrations
npx prisma db push
Start development server
npm run dev
Start frontend (in another terminal)
cd frontend && npm run dev

Project Structure

wifi_billing/
├── config/          # Database and service configurations
├── routes/          # API endpoints
├── services/        # Business logic
├── middleware/      # Authentication and security
├── prisma/          # Database schema and migrations
├── frontend/        # Next.js React application
├── src/            # Shared utilities (logger, etc.)
└── logs/           # Application logs

API Documentation

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login

Payments

• POST /pay - Initiate M-Pesa payment
• POST /api/mpesa/callback - M-Pesa callback handler

Loans

• GET /loans/eligibility - Check loan eligibility
• POST /loans/request - Request a loan
• POST /loans/repay/initiate/:loanId - Initiate loan repayment

Admin

• GET /api/admin/summary - Dashboard summary
• GET /admin/payments - Payment history

Environment Variables

See .env.example for all required environment variables.

Deployment Options

• Render (Recommended): One-click cloud deployment
• Docker: Containerized deployment
• PM2: Process management for VPS
• Manual: Direct Node.js deployment

Production Deployment Guide

Prerequisites

• Node.js 18+
• PostgreSQL 15+
• PM2 (for process management)
• Docker & Docker Compose (optional)
• Linux/Windows server with at least 2GB RAM

Quick Start

1. Clone and setup:

git clone <repository>
   cd wifi_billing
   cp .env.example .env  # Configure your environment variables

1. Run deployment script:

./deploy.sh

1. Start with PM2:

npm run pm2:start

Environment Variables

Create a .env file with the following variables:

# Server
PORT=5000
NODE_ENV=production
Database (PostgreSQL)
DATABASE_URL=postgresql://user:password@localhost:5432/wifi_billing
Security
JWT_SECRET=your-secure-random-jwt-secret-here
Admin Credentials
ADMIN_USERNAME=your_admin_username
ADMIN_PASSWORD=your_secure_admin_password
[email protected]
M-Pesa Integration
MPESA_ENABLED=true
MPESA_CONSUMER_KEY=your_mpesa_consumer_key
MPESA_CONSUMER_SECRET=your_mpesa_consumer_secret
MPESA_SHORTCODE=your_mpesa_shortcode
MPESA_PASSKEY=your_mpesa_passkey
MPESA_CALLBACK_URL=https://yourdomain.com/api/mpesa/callback
MikroTik Integration
MIKROTIK_ENABLED=true
MIKROTIK_HOST=192.168.88.1
MIKROTIK_USER=your_mikrotik_user
MIKROTIK_PASSWORD=your_mikrotik_password
MIKROTIK_PORT=8728
Loan Configuration
LOAN_WIFI_DURATION_HOURS=1

Deployment Options

Option 1: Render (Recommended for Cloud)

Render provides managed PostgreSQL and automatic deployments from Git.

Setup Steps:

1. Connect Repository:

1. Configure Secrets:

JWT_SECRET: your-secure-random-jwt-secret
   ADMIN_USERNAME: your_admin_username
   ADMIN_PASSWORD: your_secure_admin_password
   ADMIN_EMAIL: [email protected]
   MPESA_CONSUMER_KEY: your_mpesa_consumer_key
   MPESA_CONSUMER_SECRET: your_mpesa_consumer_secret
   MPESA_SHORTCODE: your_mpesa_shortcode
   MPESA_PASSKEY: your_mpesa_passkey
   MPESA_CALLBACK_URL: https://your-render-app.onrender.com/api/mpesa/callback
   MIKROTIK_ENABLED: true
   MIKROTIK_HOST: your_mikrotik_ip
   MIKROTIK_USER: your_mikrotik_username
   MIKROTIK_PASSWORD: your_mikrotik_password
   MIKROTIK_PORT: 8728

1. Deploy:

Benefits:

• ✅ Free tier available
• ✅ Managed PostgreSQL
• ✅ Automatic SSL certificates
• ✅ Global CDN
• ✅ Automatic deployments on git push

Option 2: PM2 (Self-hosted)

# Install PM2 globally
npm install -g pm2
Start application
npm run pm2:start
Check status
npm run pm2:monit
View logs
npm run pm2:logs

Option 3: Docker Compose (Self-hosted)

# Build and start
docker-compose up -d
View logs
docker-compose logs -f app
Stop
docker-compose down

Option 4: Direct Node.js (Development)

# Start
npm start
Or with PM2
pm2 start index.js --name wifi-billing

Database Setup

1. Create PostgreSQL database:

CREATE DATABASE wifi_billing;
   CREATE USER wifi_user WITH PASSWORD 'secure_password';
   GRANT ALL PRIVILEGES ON DATABASE wifi_billing TO wifi_user;

1. Run migrations:

npx prisma db push

Security Checklist

• [ ] Change default JWT secret
• [ ] Use strong admin passwords
• [ ] Configure firewall (allow only ports 80, 443, 5000)
• [ ] Enable SSL/TLS with Let's Encrypt
• [ ] Set up log rotation
• [ ] Configure backup strategy
• [ ] Monitor system resources
• [ ] Set up fail2ban for SSH protection

Monitoring

# PM2 monitoring
npm run pm2:monit
Application health check
curl http://localhost:5000/welcome
Database connection
npx prisma db execute --file check-db.sql

Backup Strategy

# Database backup
pg_dump wifi_billing > backup_$(date +%Y%m%d_%H%M%S).sql
Application logs
tar -czf logs_$(date +%Y%m%d).tar.gz logs/

Troubleshooting

Common Issues

1. Database connection fails:

1. M-Pesa callbacks not working:

1. MikroTik connection issues:

Logs Location

• Application logs: logs/
• PM2 logs: ~/.pm2/logs/
• System logs: /var/log/

Performance Tuning

• Set Node.js memory limit: node --max-old-space-size=1024 index.js
• Configure PostgreSQL connection pool
• Enable gzip compression
• Set up Redis for session storage (future enhancement)

Support

For issues, check:

1. Application logs
2. PM2 status: pm2 status
3. Database connectivity
4. Network configuration

Security Features

• JWT authentication with expiration
• Rate limiting on sensitive endpoints
• Input validation and sanitization
• SQL injection prevention
• XSS protection
• Helmet.js security headers
• CORS configuration

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Project Admin ⚡

mwakidenis

Contributors

I extend my heartfelt gratitude for any invaluable contribution to this project! Your efforts play a pivotal role in elevating the repo to greater heights.

Support

For support, strictly create an issue in the GitHub repository. Am done up to the point of testing with real Mikrotik RB750UPr, Currently am working on DDOS management on the system. Contact me only for paid consultations regarding Mpesa-Based_Wi-Fi-Hotspot_Billing_System repository.