eazyBill: multi-tenant billing for ISPs

eazyBill runs the business side of small internet service providers: PPPoE and hotspot customers, packages, M-Pesa payments, RADIUS authentication, and MikroTik routers connected over OpenVPN. One platform owner runs it for many ISPs, and each ISP gets its own staff workspace and customer portal.

It is the product version of the billing platform I built for an ISP with 7,000+ active subscribers, which runs its billing, provisioning and support every day. A multi-tenant deployment is live at uplink.skylinknetworks.co.ke.

This repo is a showcase. The application code is private because it's a commercial product. This repo holds the architecture and the real deployment setup (CI/CD workflow, Docker Compose, Caddy, server setup and backup scripts). I'm happy to walk through the code on a call.

What it does

• Tenants: each ISP has its own customers, packages, routers, regions, staff roles, branding (name, logo, colour) and support contacts.
• PPPoE subscribers: monthly packages, invoices, automatic suspension on expiry and reactivation on payment.
• Hotspot users: a captive portal served by the router before the device is online, with M-Pesa STK, vouchers, and a PIN-protected wallet that up to five devices can spend from.
• Payments: M-Pesa (Daraja and Kopo Kopo), MTN MoMo and Selcom. An ISP can start with only a bank account, because customers pay through the platform into the ISP's bank.
• Network automation: FreeRADIUS handles login, speed limits and session expiry; the MikroTik RouterOS API pushes changes and reads live usage.
• Customer portal at my.<domain>/<isp>, with sign-in by one-time code.

Architecture

flowchart LR
  subgraph Internet
    staff[ISP staff] --> caddy
    cust[PPPoE customers] --> caddy
    hs[Hotspot users] --> caddy
    mpesa[M-Pesa / MoMo / Selcom] -- callbacks --> caddy
  end
  subgraph VPS["One VPS (Docker Compose)"]
    caddy[Caddy<br/>auto HTTPS, subdomain routing]
    caddy --> fe[Staff app<br/>Next.js]
    caddy --> portal[Customer portal<br/>Next.js]
    caddy --> api[API + crons<br/>Node.js / Express]
    caddy --> relay[Hotspot captive portal]
    api --> mongo[(MongoDB)]
    api --> redis[(Redis)]
    radius[FreeRADIUS] --> mysql[(RADIUS DB<br/>MySQL)]
    api --> mysql
    vpn[OpenVPN server]
  end
  routers[MikroTik routers<br/>at each ISP] -- OpenVPN tunnel --> vpn
  routers -- RADIUS via 10.8.0.1 --> radius
  api -- RouterOS API over VPN --> routers

Site	Service
<domain>, app.<domain>	landing page and staff workspace
my.<domain>/<isp>	customer portal
relay.<domain>	hotspot captive portal
vpn.<domain>:1194/tcp	routers' OpenVPN

Design decisions

• One set of images for any server. The domain lives only in server/.env; the API serves it at GET /api/platform. Frontends call /api on their own address, so there's no CORS and cookies stay first-party.
• Routers find the platform by name. They dial vpn.<domain> and reach RADIUS at 10.8.0.1 inside the tunnel, so moving to a new server is a DNS change, with nothing to reconfigure on hundreds of routers.
• RADIUS is never exposed. The firewall only accepts RADIUS traffic through the VPN.
• Payments are reconciled, not trusted. Callbacks can be lost, so scheduled jobs check pending payments with the provider before activating or failing them.
• The captive portal has no build step and no external assets. It is server-rendered HTML with inline CSS and JS, because before payment only the relay host is reachable and links are often weak.

Deployment (files in this repo)

• .github/workflows/deploy.yml: on push to main, it works out which services changed, builds only those Docker images in parallel, pushes them to GHCR, copies server/ to the VPS over SSH, and restarts only the changed containers. Nothing is built on the server. Roll back by pinning IMAGE_TAG to an earlier commit.
• server/docker-compose.yml: the whole platform as one Compose stack.
• server/Caddyfile: subdomain routing and automatic HTTPS.
• server/setup.sh: one-command, re-runnable setup of a fresh Ubuntu server: Docker, swap, firewall, generated secrets, registry login, nightly backup cron.
• server/backup.sh: nightly MongoDB archive, RADIUS dump and OpenVPN keys, kept for 14 days, with optional off-site copy through rclone.

Stack

Node.js, Express, Next.js, React, TypeScript, MongoDB, MySQL, Redis, FreeRADIUS, OpenVPN, MikroTik RouterOS API, Docker, GitHub Actions, GHCR, Caddy, Jest and Supertest (unit, integration and end-to-end tests).

---

Built by Charles Njoroge · github.com/c-njoro · linkedin.com/in/charles-njoroge-dev