Deploy Lago

Deploy and Host Lago on Railway

Lago is an open-source usage-based billing platform: your application posts usage events to its API, Lago turns them into billable metrics, prices them against subscription plans and credits, and issues invoices you collect through Stripe, Adyen or GoCardless. It is the metering layer teams reach for when a flat per-seat plan stops describing what they sell — AI products charging per token, infrastructure per GB, APIs per call. It is AGPLv3, so self-host Lago and your revenue data stays in your own database.

Deploy Lago on Railway and you get the full production topology, not a single container. The Rails API serves the REST and GraphQL endpoints; a React dashboard runs behind nginx; one Sidekiq worker handles invoicing, webhooks and integrations while a second is dedicated to event ingestion, so a heavy billing run never delays metering; a scheduler fires recurring billing jobs; and Gotenberg renders invoice PDFs. Behind them sit PostgreSQL 17 with the pg_partman extension, Redis for queues and cache, and an object storage bucket holding every generated PDF.

Getting Started with Lago on Railway

Set LAGO_ORG_NAME, LAGO_ORG_USER_EMAIL and LAGO_ORG_USER_PASSWORD when you deploy. Registration is disabled, so those three values create your organization and its first admin once the API finishes migrating, and they are the credentials you sign in with at the dashboard's URL.

Start in Billable metrics and create one matching something your product already counts: a code such as api_tokens with a sum aggregation over a property named tokens. Then create a Plan — a monthly price plus a charge on that metric — and a Customer, and assign the plan to them. Now send usage: copy your API key from Developers → API keys & ID and post an event:

curl -X POST https://your-api-domain.up.railway.app/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":{"transaction_id":"evt-1","external_subscription_id":"YOUR_SUB_ID","code":"api_tokens","properties":{"tokens":12500}}}'

Within seconds the subscription's Usage tab shows the units aggregated and what they cost — one round trip proving the API, the event worker, Redis and the database are wired correctly. Download the PDF of the subscription-fee invoice to confirm the renderer and object storage work too.

About Hosting Lago

Billing is the most painful part of a product to build and the most expensive to get wrong. Lago separates metering and pricing from payment processing: it owns the events, the pricing rules and the invoices, and hands the final amount to whichever provider you use. Teams self-host it because usage events are among the most sensitive data a company holds, and keeping them in your own PostgreSQL avoids handing a third party a full picture of customer behaviour.

What it gives you:

• Billable metrics with sum, count, max, unique count and weighted aggregations
• Standard, graduated, package, percentage and volume pricing
• Prepaid wallets with auto top-ups, coupons, add-ons and commitments
• Trials, upgrades, downgrades, proration, and anniversary or calendar billing
• Invoices with tax support, PDF output and a customer portal
• Webhooks and an idempotent REST API with official SDKs, plus an MCP server

The Railway architecture mirrors what Lago documents for production. The API is the only service your application talks to. Event ingestion gets its own Sidekiq worker so a month-end billing run cannot block incoming usage, while the general worker finalizes invoices, generates PDFs and delivers webhooks. PDFs are rendered by Gotenberg, a headless Chromium service, and written straight to object storage rather than a disk, which lets the API and worker scale independently.

Why Deploy Lago on Railway

Railway removes the operational work self-hosted billing normally brings:

• Every service, database, Redis instance and bucket set up in one click
• Private networking keeps the database, workers and PDF renderer off the internet
• The API and dashboard get managed TLS domains automatically
• Workers and the API scale independently, with no load balancer to configure

Common Use Cases

• AI and LLM products billing per input, output or reasoning token, with prepaid wallets that top up automatically
• Infrastructure and API companies charging for compute, storage or requests alongside a platform fee
• Hybrid SaaS pricing where a seat subscription carries metered overages above an included allowance
• Enterprise contracts with negotiated rates and commitments beside a self-serve tier

Dependencies for Lago

• getlago/api — API, Sidekiq workers and scheduler, one image with the role chosen per service
• getlago/front — React dashboard served by nginx
• getlago/lago-gotenberg — Gotenberg with Lago's invoice fonts, renders PDFs
• PostgreSQL 17 with pg_partman — every customer, plan, event and invoice. The extension is required: Lago's schema partitions its enriched events table
• Redis — Sidekiq queues, cache and real-time dashboard updates
• Object storage bucket — generated invoice PDFs

Environment Variables Reference

Deployment Dependencies

• Source: ,
• Documentation:
• Images: getlago/api, getlago/front, getlago/lago-gotenberg on Docker Hub

Hardware Requirements for Self-Hosting Lago

Event volume drives sizing: millions of events a month wants worker replicas before a bigger API.

Self-Hosting Lago

Locally, Lago ships a Compose file that starts every service:

git clone https://github.com/getlago/lago.git
cd lago
echo "LAGO_RSA_PRIVATE_KEY=\"$(openssl genrsa 2048 | base64 | tr -d '\n')\"" >> .env
docker compose up -d

The dashboard is then on port 80 and the API on port 3000. That RSA key is not optional — Lago signs webhooks and customer portal URLs with it and refuses to start without one. On Railway it is generated on first boot and shared across the services, so there is nothing for you to create. A hand-rolled deployment also needs PostgreSQL with pg_partman, Redis, and Gotenberg for PDFs.

Is Lago Free to Self-Host?

Lago's core is open source under AGPLv3 and free to run with no user or event caps. Lago Cloud and the enterprise edition add support, SSO, analytics and premium integrations on paid plans; the community edition covers metering, plans, subscriptions, wallets, invoicing and webhooks. On Railway you pay only for the compute, database and storage consumed.

FAQ

What is Lago? Lago is an open-source billing platform for usage-based and hybrid pricing. It meters usage, applies your pricing rules and produces invoices, replacing custom billing code or a closed platform like Stripe Billing or Chargebee.

What does this Railway template deploy? The API, the dashboard, a general worker, a dedicated event-ingestion worker, a scheduler, a Gotenberg PDF renderer, PostgreSQL 17 with pg_partman, Redis and an object storage bucket.

Why does it need PostgreSQL, Redis and object storage? PostgreSQL holds every customer, plan, event and invoice. Redis backs the Sidekiq queues doing invoicing and webhook delivery, and doubles as the cache. Object storage keeps generated PDFs, letting the API and worker run as separate services without sharing a disk.

Does Lago process payments itself? No. It calculates what each customer owes and hands that to Stripe, Adyen or GoCardless, or exposes it for manual collection. Card details never reach Lago.

How do I send usage events to self-hosted Lago? POST to /api/v1/events with your API key as a bearer token, including a unique transaction_id, the subscription's external id, the metric code and the properties it aggregates. Official SDKs cover Ruby, Python, JavaScript, Go, PHP and Java.

How do I scale Lago for higher event volume? Raise the replica count on the workers and the API. The scheduler is a singleton by design and stays at one replica. Lago also supports dedicated workers for the PDF, billing and webhook queues. To email invoices set LAGO_SMTP_ADDRESS and its credentials; without SMTP they stay downloadable from the dashboard.