Prerequisites

• VPS — Ubuntu 22.04 LTS, minimum 2GB RAM, 2 vCPU, 40GB SSD
• Domain — e.g. billing.yourisp.co.ke pointed at your VPS IP
• Ports open — 22, 80, 443, 1812/UDP, 1813/UDP, 3799/UDP
• M-Pesa Daraja — sandbox or production app credentials

Step by step

sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs git nginx mysql-server certbot python3-certbot-nginx ufw
node --version  # should show v20.x

cd /var/www
sudo git clone https://github.com/yourrepo/isp-billing.git
cd isp-billing
sudo npm install
sudo cp .env.example .env
sudo nano .env   # fill in your DB, M-Pesa, RADIUS values

sudo mysql -u root -p
-- In MySQL shell:
CREATE DATABASE isp_billing;
CREATE DATABASE radius;
CREATE USER 'billing'@'localhost' IDENTIFIED BY 'strongpassword';
GRANT ALL ON isp_billing.* TO 'billing'@'localhost';
GRANT ALL ON radius.*      TO 'billing'@'localhost';
FLUSH PRIVILEGES;
EXIT;

sudo apt install -y freeradius freeradius-mysql
# Download and run setup script from admin panel:
# Settings → FreeRADIUS → Download Setup Script
chmod +x setup-freeradius.sh
sudo bash setup-freeradius.sh

sudo npm install -g pm2
pm2 start src/app.js --name isp-billing
pm2 startup && pm2 save  # auto-start on reboot

server {
    server_name billing.yourisp.co.ke;

    location / {
        root /var/www/isp-admin/dist;
        try_files $uri /index.html;
    }
    location /api/ {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    location ~ ^/(hotspot|provision) {
        proxy_pass http://localhost:3000;
    }
}
# Then run:
sudo certbot --nginx -d billing.yourisp.co.ke

sudo ufw allow 22 && sudo ufw allow 80 && sudo ufw allow 443
sudo ufw allow 1812/udp   # RADIUS auth
sudo ufw allow 1813/udp   # RADIUS accounting
sudo ufw allow 3799/udp   # CoA disconnect
sudo ufw enable

M-Pesa (Safaricom Daraja)

Uses the Daraja Lipa Na M-Pesa Online (STK Push) API. The customer receives a payment prompt on their phone and enters their M-Pesa PIN to confirm.

Configuration

Go to Settings → Payments → M-Pesa Settings and fill in:

Field	Where to get it	Example
Consumer Key	Safaricom Developer Portal → your app	Ku0dqAdnz...
Consumer Secret	Safaricom Developer Portal → your app	CCZW7l8Wk...
Shortcode	Your M-Pesa paybill or till number	174379
Passkey	Daraja portal → Lipa na M-Pesa	bfb279f9...
Callback URL	Your domain (must be HTTPS)	https://billing.yourisp.co.ke/api/payments/mpesa/callback

Airtel Money

Uses the Airtel Africa Collection API. The customer receives a USSD prompt and enters their Airtel Money PIN. No STK push — the prompt appears automatically on their phone.

Configuration

Go to Settings → Payments → Airtel Settings:

Field	Where to get it
Client ID	developers.airtel.africa → your app → Key Management
Client Secret	developers.airtel.africa → your app → Key Management
Callback URL	Your domain: https://billing.yourisp.co.ke/api/payments/airtel/callback
Country	KE for Kenya
Currency	KES for Kenya Shillings

Switching providers

In Settings → Payments, click the card for the provider you want to activate. Only one can be active at a time. All new payments will use the active provider immediately — no restart required.

Payment flow

# Admin-initiated (PPPoE customer)
Admin clicks "Collect Payment"
  → POST /api/payments/initiate
  → M-Pesa STK push / Airtel USSD to customer phone
  → Customer enters PIN
  → Safaricom/Airtel POSTs to callback URL
  → Customer activated, invoice generated, SMS sent

# Customer self-service (Hotspot)
Customer connects to WiFi
  → Redirected to hotspot portal
  → Selects package, enters phone
  → Pays via M-Pesa/Airtel
  → Auto-logged into hotspot

Router wizard — 3 steps

Step 1: Create router record

In Routers → Add Router, enter:

• Name — e.g. "Westlands Estate"
• Service types — PPPoE, Hotspot, or both
• Ethernet ports — ports to add to the billing bridge (e.g. ether2, ether3)
• Anti-sharing — enable TTL-based tethering prevention

Step 2: Provision via terminal

Click Generate Command. Copy the one-line command and paste it into your MikroTik terminal (via Winbox or SSH):

The MikroTik fetches a signed script from your server, creates an API user, and calls back with its IP and credentials. The router record updates automatically — you will see it go from Unprovisioned to Provisioned.

Step 3: Configure services

Click Configure Services to start the automated setup. A live log streams each step:

• Creates billing-bridge and assigns gateway IP
• Adds your ethernet ports to the bridge
• Sets up DHCP pool (10.10.10.10 – 10.10.10.254)
• Adds RADIUS server pointing to your VPS
• Starts PPPoE server on the bridge
• Uploads hotspot login page and starts hotspot server
• Applies firewall rules

Network defaults

Setting	Default value	Configurable
Bridge name	billing-bridge	No
Bridge gateway	10.10.10.1/24	Yes — .env
DHCP range	10.10.10.10 – 10.10.10.254	Yes — .env
RADIUS timeout	3 seconds	No
CoA port	3799/UDP	No

Requirements

• RouterOS 6.49+ or 7.x
• RouterOS API enabled on port 8728
• MikroTik must be able to reach your VPS on ports 80/443 and 3000

Application

Variable	Required	Default	Description
APP_PORT	optional	3000	Port the Node.js server listens on
APP_ENV	optional	development	Set to production on VPS
APP_NAME	optional	ISP Billing	Used in SMS/email messages
JWT_SECRET	required	—	64-char random hex string for JWT signing
JWT_EXPIRES_IN	optional	7d	Admin session duration

Database

Variable	Required	Description
DB_HOST	required	MySQL host for billing database
DB_NAME	required	Billing database name (e.g. isp_billing)
DB_USER	required	MySQL username
DB_PASSWORD	required	MySQL password
RADIUS_DB_HOST	required	MySQL host for RADIUS database (can be same as DB_HOST)
RADIUS_DB_NAME	required	RADIUS database name (e.g. radius)
RADIUS_DB_USER	required	RADIUS DB username
RADIUS_DB_PASSWORD	required	RADIUS DB password

RADIUS & Provisioning

Variable	Required	Description
RADIUS_IP	required	IP of your FreeRADIUS server. Use 127.0.0.1 if on same VPS.
RADIUS_SHARED_SECRET	required	Must match clients.conf and MikroTik RADIUS config
PROVISION_BASE_URL	required	Public URL of your server, e.g. https://billing.yourisp.co.ke/provision
PROVISION_SECRET	required	JWT secret for signing provisioning tokens

M-Pesa

Variable	Required	Description
MPESA_CONSUMER_KEY	required	From Safaricom Daraja portal
MPESA_CONSUMER_SECRET	required	From Safaricom Daraja portal
MPESA_SHORTCODE	required	Paybill or till number
MPESA_PASSKEY	required	Lipa Na M-Pesa passkey from Daraja
MPESA_CALLBACK_URL	required	Must be public HTTPS URL
MPESA_ENV	optional	sandbox or production

Airtel Money

Variable	Required	Description
AIRTEL_CLIENT_ID	required	From Airtel Developer Portal
AIRTEL_CLIENT_SECRET	required	From Airtel Developer Portal
AIRTEL_CALLBACK_URL	required	Public HTTPS URL for payment results
AIRTEL_ENV	optional	sandbox or production
AIRTEL_COUNTRY	optional	KE for Kenya
AIRTEL_CURRENCY	optional	KES for Kenya Shillings

SMS & Email

Variable	Required	Description
SMS_ENABLED	optional	true or false
AT_USERNAME	optional	Africa's Talking username (sandbox for testing)
AT_API_KEY	optional	Africa's Talking API key
AT_SENDER_ID	optional	Branded sender ID (max 11 chars, must be registered)
EMAIL_ENABLED	optional	true or false
EMAIL_HOST	optional	SMTP server host
EMAIL_PORT	optional	SMTP port (587 for TLS)
EMAIL_USER	optional	SMTP username
EMAIL_PASS	optional	SMTP password or app password

MikroTik provisioning

Host is unreachable when running provision command

The MikroTik cannot reach your server. Check in order:

• Is the server URL correct in PROVISION_BASE_URL? No trailing slash, no extra spaces.
• Can the MikroTik reach port 80/443? Test: /tool fetch url="https://billing.yourisp.co.ke/health" output=user
• Is your VPS firewall allowing port 80/443? Run sudo ufw status
• Is AP isolation enabled on the Wi-Fi the MikroTik is connected to? Disable it on your router.

Provision token expired

Tokens are valid for 1 hour. Click Generate Command again in the admin panel to get a fresh token.

FreeRADIUS

FreeRADIUS fails to start — unknown module rest

sudo rm -f /etc/freeradius/3.0/mods-enabled/rest
sudo service freeradius restart

Too many keys — MySQL error on startup

Sequelize's alter: true has added duplicate indexes. Fix in MySQL:

-- Find duplicate indexes
SELECT TABLE_NAME, INDEX_NAME, COUNT(*)
FROM INFORMATION_SCHEMA.STATISTICS
WHERE TABLE_SCHEMA = 'isp_billing'
GROUP BY TABLE_NAME, INDEX_NAME
HAVING COUNT(*) > 1;

-- Drop duplicates (example)
ALTER TABLE Settings DROP INDEX settings_category_key_2;

Then set APP_ENV=production in .env to prevent alter: true running again.

MikroTik: UNKNOWNREPLY !empty error

This is normal — RouterOS returns !empty for commands that succeed but return no data (like set commands). It is handled as a success automatically in the current version. If you see it, update mikrotikService.js to the latest version.

Payments

M-Pesa callback not received

• Callback URL must be HTTPS — Safaricom does not call HTTP endpoints in production
• URL must be publicly accessible — test with curl https://billing.yourisp.co.ke/api/payments/mpesa/callback from any machine
• Check Safaricom Daraja portal for delivery logs
• Check your logs: pm2 logs isp-billing | grep "M-Pesa callback"

STK push sent but customer not activated

The callback was not received or payment failed. Check:

• Payment record in admin panel — look at status field (pending/completed/failed)
• If status is pending after 2 minutes, Safaricom callback failed — check callback URL
• If status is failed, customer cancelled or had insufficient funds

Hotspot portal

Portal loads but "network connection error"

The hotspot client cannot reach port 3000. Add it to the walled garden:

/ip/hotspot/walled-garden/ip/add action=accept dst-address=YOUR_SERVER_IP
/ip/hotspot/walled-garden/ip/add action=accept protocol=tcp dst-port=3000

Or better — run your app on port 80 so walled garden rules are not needed. Set APP_PORT=80 and update Nginx.

Getting logs

# Live app logs
pm2 logs isp-billing

# FreeRADIUS debug mode (shows every auth attempt)
sudo pkill -9 freeradius && sudo freeradius -X

# Nginx error log
sudo tail -f /var/log/nginx/error.log

# MySQL slow queries
sudo tail -f /var/log/mysql/error.log