---
title: "Deploy Lago"
description: "Usage-based billing software that meters usage and sends invoices"
category: "Other"
url: https://railway.com/deploy/lago-billing-platform
---

# Deploy Lago

Usage-based billing software that meters usage and sends invoices

**[Deploy Lago on Railway](https://railway.com/template/lago-billing-platform)**

- **Creator:** A3A
- **Category:** Other
- **Total deploys:** 1

## Template content

### lago-events-worker https://raw.githubusercontent.com/getlago/lago-front/main/public/favicon-prod.svg

- **Source:** https://github.com/gridalpha/lago-railway
- **Health check:** /

### lago-api https://raw.githubusercontent.com/getlago/lago-front/main/public/favicon-prod.svg

- **Source:** https://github.com/gridalpha/lago-railway
- **Health check:** /health
- **Public domain:** Yes

### Redis https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/redis.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### lago-worker https://raw.githubusercontent.com/getlago/lago-front/main/public/favicon-prod.svg

- **Source:** https://github.com/gridalpha/lago-railway
- **Health check:** /

### lago-front https://raw.githubusercontent.com/getlago/lago-front/main/public/favicon-prod.svg

- **Image:** getlago/front:v1.51.0
- **Health check:** /
- **Public domain:** Yes

### lago-clock https://raw.githubusercontent.com/getlago/lago-front/main/public/favicon-prod.svg

- **Source:** https://github.com/gridalpha/lago-railway

### lago-pdf https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/gotenberg.png

- **Image:** getlago/lago-gotenberg:8.15
- **Start command:** `/usr/bin/tini -s -- gotenberg --api-port-from-env=PORT --api-timeout=180s --chromium-auto-start=true`
- **Health check:** /health

### lago-postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Source:** https://github.com/gridalpha/lago-railway
- **Start command:** `/bin/sh -c 'MEM=$(cat /sys/fs/cgroup/memory.max 2>/dev/null || echo max); case "$MEM" in ""|max|*[!0-9]*) MEM=2147483648;; esac; SB=$((MEM/4/1048576)); EC=$((MEM*3/4/1048576)); echo "sizing shared_buffers=${SB}MB effective_cache_size=${EC}MB from cgroup"; exec docker-entrypoint.sh postgres -c data_directory=/data/pgdata -c shared_buffers=${SB}MB -c effective_cache_size=${EC}MB -c maintenance_work_mem=256MB -c work_mem=16MB -c max_connections=200 -c shared_preload_libraries=pg_partman_bgw -c pg_partman_bgw.interval=3600 -c pg_partman_bgw.role=lago -c pg_partman_bgw.dbname=lago'`

## Buckets

- **lago-storage**

## Documentation

# 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.

![Diagram of the Lago API, workers and datastores on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1787421558/lago-architecture.png)

## 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.

![Lago subscription usage totalling 262,500 metered API tokens](https://res.cloudinary.com/rroe4rtk/image/upload/v1787421561/lago-subscription-usage.png)

![Finalized Lago invoice for Acme Corp's Pro subscription](https://res.cloudinary.com/rroe4rtk/image/upload/v1787421563/lago-finalized-invoice.png)

![Lago customer page showing Acme Corp's active Pro subscription](https://res.cloudinary.com/rroe4rtk/image/upload/v1787421568/lago-customer-subscription.png)

## 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

| Variable | Purpose |
|---|---|
| `LAGO_ORG_NAME` | Organization created on first boot |
| `LAGO_ORG_USER_EMAIL` | First admin's login email |
| `LAGO_ORG_USER_PASSWORD` | First admin's password |
| `LAGO_DISABLE_SIGNUP` | Keeps public registration closed |
| `LAGO_API_URL` | Public API URL, used for callbacks |
| `LAGO_FRONT_URL` | Dashboard origin the API allows |
| `SIDEKIQ_EVENTS` | Routes ingestion to the event worker |
| `LAGO_SMTP_ADDRESS` | Optional SMTP host for emailing invoices |

### Deployment Dependencies

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

## Hardware Requirements for Self-Hosting Lago

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 vCPU across all services | 4+ vCPU |
| RAM | 4 GB total | 8 GB or more |
| Storage | 10 GB for PostgreSQL | 20 GB+, growing with event volume |
| Runtime | Ruby 4 / Rails 8, PostgreSQL 14+, Redis 6+ | PostgreSQL 17, Redis 8 |

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.


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/lago-billing-platform