Deploy and Host Lago-self-hosted on Railway

Lago is the open-source billing and metering platform for usage-based pricing, subscriptions, and automated invoicing. It's the tool teams reach for when flat per-seat pricing doesn't fit, and they need to actually meter what customers use.

About Hosting Lago-self-hosted

Billing systems sit in a strange spot. They're not customer-facing in the way your product is, but they handle some of the most sensitive data in your business: invoices, payment records, usage history, sometimes the exact API keys or account details tied to how a customer gets charged. That's exactly the kind of thing worth keeping on infrastructure you control rather than routing through a third party.

The financial argument for self-hosting Lago specifically is unusually strong compared to most self-hosted tools in this project, because most billing platforms don't charge a flat SaaS fee, they charge a percentage of your own revenue. Stripe Billing runs roughly 0.7% of billing volume with no base fee. Chargebee's Performance tier is $599 a month plus a 0.75% overage rate that climbs toward 1% as you scale. A company processing $500K a month in subscriptions pays Stripe Billing something like $3,500 a month just for the billing layer, and that number only grows as the business grows. Self-hosted Lago has no revenue-percentage fee at all. Your cost is a flat infrastructure bill, completely decoupled from how much you actually bill your own customers.

Here's the thing worth knowing before you deploy this specific template: Lago's full docker-compose.yml documents a more elaborate production shape, Postgres with the pg_partman extension, a dedicated Sidekiq worker, a scheduled "clock" process, and a Gotenberg service for PDF invoices, split out for horizontal scaling. This template deploys the simpler, proven shape instead: Postgres, Redis, API, and frontend, four services, using the API image's own default startup command, which self-migrates and runs the full app in one process. This matches Railway's own real, live reference deployment. If you're running high invoice volume and want dedicated background workers, Lago's own docs cover adding them.

Common Use Cases

Usage-based SaaS billing: Meter API calls, compute time, or any custom event, and bill customers based on real usage instead of flat seats.
Hybrid pricing models: Combine a flat subscription fee with metered overage charges in a single plan.
Automated invoice generation: Generate and send invoices automatically as billing cycles close, no manual invoicing.
Prepaid credits and wallets: Let customers prepay for usage credits that draw down as they consume, common in AI/API-heavy products.
Revenue analytics: Track MRR, churn, and usage trends natively instead of exporting billing data to a separate BI tool.
Payment provider orchestration: Route charges through Stripe, Adyen, or other providers while keeping the billing logic itself under your control.

Dependencies for Lago-self-hosted Hosting

Postgres, for storing organizations, customers, plans, invoices, and usage events.
Redis, for background jobs and application caching.

Deployment Dependencies

Reference: Lago GitHub Repository, Lago Self-Hosted Docs, Lago's docker-compose.yml.

Implementation Details

This template runs getlago/api:v1.51.0 and getlago/front:v1.51.0, pinned to the exact versions confirmed against Lago's current official release, matched to each other since Lago's API and frontend are version-locked together. The API's Dockerfile deliberately doesn't override the image's own default start command, confirmed via getlago/lago-api's real source to run database migrations and start the Rails server together in one process, no separate migration step needed.

How Lago Compares to the Alternatives

Vs. Stripe Billing: Stripe Billing is deeply integrated with Stripe's payment processing and genuinely easy to get started with. But its pricing scales as a percentage of your own billing volume forever, there's no ceiling. Lago trades some of that turnkey integration for a flat, predictable infrastructure cost that doesn't grow just because your business does.

Vs. Chargebee: Chargebee is a mature, feature-rich platform, but it's closed-source SaaS only, and its pricing tiers plus overage percentage add up fast at scale. Lago is fully open-source, self-hostable, and modifiable if you need to customize billing logic in ways a closed platform won't let you.

Vs. building billing in-house: This is the comparison that catches most teams off guard. Billing logic has deeply subtle edge cases, proration when a customer upgrades mid-cycle, timezone handling for billing period boundaries, currency rounding that has to reconcile exactly. Lago has already solved these problems in production; a custom-built billing system tends to rediscover each one the hard way, usually via a support ticket from an angry customer.

Getting Started

First boot takes a couple of minutes, the API runs its own database migrations on startup before it's actually usable. Watch for the API service's healthcheck to go green before assuming something's stuck.

Once your Railway domain for the frontend loads, you'll see Lago's signup screen. Create your organization, this becomes the top-level entity all your billing configuration lives under. The account you create here becomes your workspace admin.

From the dashboard, your first real step is usually creating a billable metric, the definition of what you're actually measuring (API calls, GB processed, seats, whatever your product's usage unit is). From there, build a plan that references that metric, either pure usage-based pricing or a hybrid with a flat base fee plus metered overage.

Test the full loop before trusting it with real customers: create a test customer, attach them to your new plan, send a few usage events via the API, and confirm an invoice actually generates correctly at the end of a billing period. This is the single most important thing to verify on this simpler single-process deployment shape, since background-job-dependent behavior is exactly what a split worker/clock architecture would otherwise isolate.

One thing worth testing deliberately: redeploy the Postgres service once, early, before you have real customer billing data you'd be upset to lose, and confirm everything survives. That's real proof the persistent volume is correctly configured.

Why Deploy Lago-self-hosted on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Lago-self-hosted on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Frequently Asked Questions

Does this template include a dedicated worker or clock service?

No, this deploys the simpler four-service shape (Postgres, Redis, API, frontend), matching Railway's own real reference deployment. Lago's fuller docker-compose.yml documents a split worker/clock/PDF architecture meant for larger-scale, horizontally-scaled setups, worth adding if you're processing high invoice volume and want dedicated background processing.

How do I know if I actually need the split worker/clock setup instead of this simpler one?

Watch for symptoms rather than guessing upfront: if invoices consistently take a long time to appear after a billing period closes, or scheduled billing runs feel delayed under real load, that's the signal to look at Lago's docs for splitting workers out. For most small-to-mid-size deployments, the single-process default is genuinely sufficient, don't add complexity you haven't confirmed you need.

Does PDF generation for invoices work without a separate Gotenberg service?

Lago's full production setup uses a dedicated Gotenberg service for PDF rendering at scale. Test this directly after deploying, if your usage doesn't need it, LAGO_DISABLE_PDF_GENERATION is also a real supported setting if you want invoices without PDF attachments.

What is the LAGO_RSA_PRIVATE_KEY for, and do I really need to generate one myself?

It signs outgoing webhooks so receiving systems can verify they actually came from your Lago instance. Yes, it needs to be a real generated RSA key (openssl genrsa 2048 | base64), not the placeholder value shown in Lago's own example configuration.

Will my billing data survive a redeploy?

Yes, all data (organizations, customers, invoices, usage events) lives in Postgres on a persistent volume, independent of every app service's own redeploys.

Do I need a payment provider connected to use Lago?

Not strictly, you can track usage, generate invoices, and manage billing logic without connecting a payment provider. Connecting Stripe, Adyen, or another provider is what lets Lago actually charge customers automatically.

Is Lago's pricing engine capable of the same complexity as Stripe or Chargebee?

Yes, tiered pricing, graduated pricing, package pricing, hybrid subscription-plus-usage models, and prepaid credits are all supported natively, this isn't a stripped-down alternative, it's a genuinely full-featured billing engine.