Self-Hosting
PimaBill is open source (AGPL-3.0). You can run the whole platform yourself, with no limits on organisations, customers or invoices. Everything below is free.
What you need
- A Linux server with Docker and Docker Compose (2 GB of memory is enough to start)
- A domain for the API and one for the dashboard, behind a reverse proxy with TLS
- SMTP credentials for emails (invoices, password resets, invitations)
- Your own account with at least one payment provider (Flutterwave, Paystack, Stripe, MTN MoMo, Airtel Money, Yo! Payments, PayPal and more)
Install
curl -O https://raw.githubusercontent.com/pimabill/billing/main/docker-compose.prod.yml
curl -O https://raw.githubusercontent.com/pimabill/billing/main/.env.example
cp .env.example .env
Fill in .env. These are required:
| Setting | What it is |
|---|---|
CENTRAL_DB_PASSWORD, TENANT_DB_PASSWORD | Database passwords (openssl rand -hex 24) |
JWT_SECRET, JWT_REFRESH_SECRET | Session signing secrets, different from each other (openssl rand -hex 32) |
ENCRYPTION_KEY | Encrypts provider credentials and database URLs (openssl rand -hex 32); keep a copy: without it they cannot be read |
API_URL, DASHBOARD_URL | Your public addresses, e.g. https://api.example.com and https://app.example.com |
EMAIL_HOST, EMAIL_PORT, EMAIL_USER, EMAIL_PASSWORD, EMAIL_FROM | SMTP |
Then start it:
docker compose -f docker-compose.prod.yml up -d
The API listens on port 4000 and the dashboard on 4002 (change them with API_PORT and DASHBOARD_PORT). Put both behind your reverse proxy; nginx.conf.example in the repository is a starting point. Database migrations run on start, and each organisation gets its own database when it signs up.
Updating
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
Back up the two PostgreSQL volumes and your .env before updating. Releases and what changed are on the GitHub releases page.
Branding
BRAND_NAME, BRAND_LOGO, BRAND_TAGLINE, BRAND_PRIMARY and BRAND_SUPPORT_EMAIL put your own name on emails, invoices and the API reference.
A sandbox
Run a second deployment with SANDBOX_MODE=true for testing with providers' test accounts, and give your live dashboard a switch to it. See Sandbox.
What is different from the cloud
| Self-hosted | Cloud | |
|---|---|---|
| Price | Free | Free up to 1,000 customers; Growth, with no limits, $15 a month or the same in your currency (UGX 55,000, KES 1,900, NGN 22,000, …); Enterprise on request |
| Limits | None | Per plan; see Plan limits and access |
| Payment providers | Your own accounts | Your own accounts, plus managed payments |
| Managed payments | Not available | Included: get paid without a payment provider account of your own |
| Servers, updates, backups | Yours | Ours |
Managed payments are a service run by the cloud: it takes payments for you and pays you out, with review and payouts handled by us. A self-hosted deployment always uses its own provider accounts. Connect them in Settings → Payment providers.