Deploy and Host Lago on Railway

Deploy Lago on Railway to self-host an open-source metering and usage-based billing platform built for product-led SaaS companies — the same engine PayPal, Mistral AI, and Groq use to invoice usage events, manage subscriptions, and orchestrate payments. Self-host Lago when you outgrow Stripe Billing, Chargebee, or Recurly's rigid subscription primitives and need credits, wallets, hybrid plans, or progressive billing on infrastructure you own.

This Railway template runs the full Lago stack: a custom Postgres image (getlago/postgres-partman:15.0-alpine) with the pg_partman extension for event partitioning, a Railway-managed Redis for Sidekiq queues and Rails caching, the getlago/api:v1.45.2 image deployed three ways (API web server, Sidekiq worker, and clockwork scheduler), and the getlago/front:v1.45.2 Single Page Application with nginx. Encryption keys, JWT signing keys, and the Rails secret are pre-generated and shared across API/Worker/Clock so every deploy works out of the box.

Getting Started with Lago on Railway

After the deploy turns green, open the Front service's public domain — that is the Lago dashboard. Sign in with the bootstrap admin email and password set during migrate.sh via LAGO_ORG_USER_EMAIL and LAGO_ORG_USER_PASSWORD. The seed organization (controlled by LAGO_ORG_NAME) and a usable API key (LAGO_ORG_API_KEY) are created on the first deploy by bundle exec rails signup:seed_organization. From there, model your first billable metric, attach it to a plan, create a customer, and post a usage event to the API at https://${{API.RAILWAY_PUBLIC_DOMAIN}}/api/v1/events with Authorization: Bearer . The Sidekiq worker handles event aggregation and invoice creation asynchronously; the Clock service fires nightly subscription billing jobs.

About Hosting Lago

Lago is the open-source billing layer behind product-led B2B SaaS — its core job is turning streams of usage events into accurate invoices and revenue records, regardless of pricing model. Unlike Stripe Billing or Chargebee, every aggregation rule, plan, and pricing tier lives in your own database, queryable and forkable.

Key features available in the self-hosted edition:

• Usage-based, subscription, hybrid, and credit-based pricing on the same plan
• Wallet, prepaid credits, and progressive billing primitives
• Webhook + GraphQL API for every customer, subscription, and event mutation
• Plug-in payment processors (Stripe, GoCardless, Adyen) and tax engines
• Sidekiq-backed job queue with retry semantics for high-volume usage ingestion

Architecture note: this template separates API, Worker, and Clock so high-traffic event ingestion does not starve background billing jobs.

Why Deploy Lago on Railway

Skip provisioning Postgres-with-extensions, Redis, and four Rails processes by hand:

• One-click bring-up of all 6 Lago services with cross-service variables pre-wired
• Custom getlago/postgres-partman image deployed automatically — no extension hunting
• Encryption keys, JWT RSA key, and Rails secret generated on first deploy
• ./scripts/migrate.sh runs as preDeployCommand on every API push
• Pay only for what you use — no per-seat or per-invoice billing platform fees

Common Use Cases for Self-Hosted Lago

• Usage-based SaaS billing: meter API calls, GB processed, or LLM tokens, then aggregate into monthly invoices.
• AI/LLM startup metering: track per-token usage per customer, bill with credit wallets or postpaid tiers.
• Credit and wallet products: sell prepaid credits, deduct on usage events, top-up via Stripe.
• Marketplace fee infrastructure: replace homegrown invoicing scripts with a queryable subscription engine.

Dependencies for Lago on Railway

• Postgres — getlago/postgres-partman:15.0-alpine (pg_partman required)
• Redis — Railway-managed (Sidekiq queues + Rails cache)
• API — getlago/api:v1.45.2 (./scripts/start.api.sh, preDeploy ./scripts/migrate.sh)
• Worker — getlago/api:v1.45.2 (./scripts/start.worker.sh)
• Clock — getlago/api:v1.45.2 (./scripts/start.clock.sh)
• Front — getlago/front:v1.45.2 (nginx-served React SPA)

Environment Variables Reference for Self-Hosting Lago

Deployment Dependencies for Lago

• GitHub: getlago/lago, getlago/lago-api, getlago/lago-front
• Docker Hub: getlago/api, getlago/front, getlago/postgres-partman
• Docs: docs.getlago.com

Hardware Requirements for Self-Hosting Lago on Railway

The Clock service is small (memory-light). API and Worker are the variable parts under load.

Self-Hosting Lago on Railway

The fastest path is this template — click Deploy, set the bootstrap admin email + password under the API service variables, and ship. Behind the scenes Railway provisions Postgres + Redis, runs ./scripts/migrate.sh as a preDeployCommand on the API, and brings up API/Worker/Clock/Front in parallel.

For a manual self-host (outside Railway) the official quickstart is:

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

To enable PDF invoices on Railway, add a getlago/lago-gotenberg:7.8.2 service for headless rendering, set LAGO_DISABLE_PDF_GENERATION=false on API/Worker/Front, configure an S3-compatible bucket (MinIO works), and set LAGO_USE_AWS_S3=true with LAGO_AWS_S3_ACCESS_KEY_ID, LAGO_AWS_S3_SECRET_ACCESS_KEY, LAGO_AWS_S3_BUCKET, and LAGO_AWS_S3_ENDPOINT. PDFs need S3 because Railway volumes cannot be shared between API and Worker.

How Much Does Lago Cost to Self-Host?

Lago is open-source under the AGPL-3.0 license — the self-hosted edition is free forever. You only pay Railway's usage-based infrastructure cost (CPU + RAM + bandwidth + volume). The hosted Lago Cloud product is the paid alternative if you do not want to operate the stack yourself.

FAQ

What is Lago and why self-host it? Lago is an open-source metering and usage-based billing platform — the alternative to Stripe Billing, Chargebee, and Recurly. Self-hosting Lago means full data sovereignty, no per-event vendor cost, and the ability to fork pricing logic for your business model.

Why does the template ship a custom Postgres image instead of the Railway-managed one? Lago partitions its events table with pg_partman. That extension is not installed on Railway's managed Postgres. The getlago/postgres-partman image is the upstream-maintained Postgres-with-partman build, deployed here as a Docker-image service.

Why are Worker and Clock separate services? Sidekiq workers handle event aggregation and invoice creation; the Clock process fires recurring jobs (subscription renewals, dunning). Separating them from the API protects the request-serving thread pool from being starved by long-running billing jobs.

Why are PDF invoices disabled by default on this Railway template? PDF rendering writes files to disk via Rails ActiveStorage; the worker generates PDFs and the API serves them. Railway volumes are 1:1, so a single volume cannot be shared across both services. The template disables PDFs by default and documents how to enable them with S3-compatible storage (MinIO works).

Can I use Lago's GraphQL API right after deploy? Yes — POST https://${{API.RAILWAY_PUBLIC_DOMAIN}}/graphql with the bootstrap admin email + password runs the loginUser mutation and returns a JWT. REST /api/v1/events, /api/v1/customers, /api/v1/subscriptions accept Bearer-token auth with LAGO_ORG_API_KEY.

Lago vs Stripe Billing vs Chargebee

Lago is the right choice for AI/SaaS companies that want usage-based pricing without paying revenue-percentage fees to a billing vendor.