svc-billing 💳

Usage-based billing and subscription management — open-source, metered, and fully sovereign.

---

✨ Overview

svc-billing deploys Lago — the open-source alternative to Stripe Billing and Chargebee — as the metering and subscription engine for the Generate One platform. Lago provides usage-based billing, subscription plans, invoicing, coupons, and webhook-driven payment orchestration. As a self-hosted solution, all billing data stays on the platform with no per-transaction SaaS fees. Lago's REST API and webhooks integrate directly with the platform's payment processors and customer portals.

🏗️ Architecture

graph TB
    Browser([Browser / API Client]) -->|HTTPS| TF[Traefik\nReverse Proxy]
    TF -->|Rails API| API[lago-api\nRails :3000]
    TF -->|React UI| FE[lago-front\nReact SPA]

    API -->|:5432| PG[(PostgreSQL\nsvc-infra shared)]
    API -->|:6379| VK[(Valkey/Redis\nsvc-infra shared)]

    Worker[lago-worker\nSidekiq Background Jobs] -->|DB + cache| PG
    Worker --> VK

    API -->|S3 API| S3[(Garage S3\nInvoice storage)]
    API -->|webhooks| Ext([Payment Processors\nStripe / PayPal])

    Clock[lago-clock\nScheduled jobs] --> PG
    Clock --> VK

🚀 Quick Start

# Clone the repo (Forgejo source of truth)
git clone https://git.generate.one/generate-one/svc-billing.git
cd svc-billing

# Start the full billing stack
docker compose up -d

# View API logs
docker compose logs -f lago-api

# View worker logs (invoice generation, webhooks)
docker compose logs -f lago-worker

# Check all services are healthy
docker compose ps

📦 Services

Service	Image	Port	Description
lago-api	getlago/api:latest	3000 (internal)	Rails REST API — plans, subscriptions, invoices, events
lago-front	getlago/front:latest	80 (internal)	React SPA — billing dashboard and customer management
lago-worker	getlago/api:latest	—	Sidekiq background jobs (invoicing, webhooks, emails)
lago-clock	getlago/api:latest	—	Scheduled jobs (recurring billing, subscription renewals)

🔧 Configuration

Variable	Description	Default
DATABASE_URL	PostgreSQL connection URI	—
REDIS_URL	Valkey/Redis URL (shared infra)	—
LAGO_RSA_PRIVATE_KEY	RSA key for JWT signing	—
SECRET_KEY_BASE	Rails secret key	—
LAGO_FRONT_URL	Frontend public URL	https://billing.generate.one
LAGO_API_URL	API public URL	https://billing-api.generate.one
ENCRYPTION_PRIMARY_KEY	Data encryption primary key	—
ENCRYPTION_DETERMINISTIC_KEY	Deterministic encryption key	—
ENCRYPTION_KEY_DERIVATION_SALT	Key derivation salt	—
S3_*	Garage S3 config for invoice storage	—
SMTP_*	Email config for invoices and receipts	—

🔗 Dependencies

Depends On

• svc-infra — PostgreSQL (billing database) + Valkey cache
• svc-infra — Garage S3 for invoice PDF storage
• svc-email / Postal — transactional email for invoices and receipts
• svc-auth / Authentik — OIDC SSO for billing dashboard

Depended On By

• product / g1-app — integrates Lago API for customer billing management
• svc-automation / n8n — billing event webhooks trigger workflow automations
• Payment processors (Stripe, etc.) — connect via Lago's payment provider integrations

📊 Key Lago Concepts

Concept	Description
Billable Metrics	Usage events (API calls, tokens, compute hours)
Plans	Subscription tiers with charges (flat + usage-based)
Subscriptions	Customer plan assignments with billing periods
Coupons	Percentage or fixed-amount discounts
Invoices	Auto-generated, PDF-ready billing documents
Webhooks	Real-time events for payment processor integration

🛡️ Part of Generate One

Generate One — AI infrastructure that answers to you.

Self-hosted, sovereign AI platform. generate.one

Coolify project: svc-billing (o0cwwsckokkcw04sk8kw808w)