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
