--- title: "Self-hosted billing: how to set it up" url: https://getlago.com/blog/self-hosted-billing description: "How to set up self-hosted billing on your own infrastructure with full data control: components, Docker and Helm deployment, operating checklist." authors: ["Anh-Tho Chuong"] tags: ["Engineering", "Infrastructure"] published: 2026-07-01 updated: 2026-10-08 reading_time_minutes: 5 --- # Self-hosted billing: how to set it up *Last updated: 2026-10-08* To set up a self-hosted billing system with full data control, run every component (API, workers, database, cache and event store) inside your own network, then own its upgrades, backups and access. With Lago's free and open-source product, that means Docker Compose to get started and the official Helm charts for production on Kubernetes. ### What self-hosted billing means in practice Self-hosted billing is a billing platform your team deploys and operates. Usage events, customer records, invoices and API keys live in databases you run, and nothing leaves your environment unless you send it. A default Lago install with [Docker Compose](https://getlago.com/docs/guide/lago-self-hosted/docker) runs seven containers: the front-end, the API, an asynchronous worker, a clock worker for scheduled jobs, PostgreSQL for application data, Redis as the job queue, and a PDF service built on Gotenberg. You can swap the bundled PostgreSQL and Redis for your own servers. The [code is public](https://github.com/getlago/lago), so your security team can read what each component does before you deploy it. ### The core components Every usage-based billing system does the same five jobs. This is where each one lives in Lago. - **Event ingestion with deduplication.** Your product sends usage events through the REST API, in batches, or through Kafka or Redpanda for high volume. Each event carries a `transaction_id`, and Lago uses it to [deduplicate](https://getlago.com/docs/guide/events/ingesting-usage): if the same event arrives twice, it's billed once. On the ClickHouse pipeline, uniqueness is checked on `transaction_id` and `timestamp` together. - **Aggregation.** Billable metrics define how raw events become a billable quantity, such as a count, a sum or a unique count over the billing period. Aggregation runs on the event store: PostgreSQL by default, or ClickHouse for high volumes. - **Pricing.** Plans attach charges to billable metrics, alongside subscription fees, so one invoice can combine a base fee with usage. - **Invoicing.** Lago generates invoices at the end of each billing period and renders PDFs through the PDF service. [Credit notes](https://getlago.com/docs/guide/invoicing/credit-notes/overview) are a premium feature. - **Payments.** Lago keeps metering and pricing independent from payment collection. You [connect a payment provider](https://getlago.com/docs/guide/payments/payment-providers) to collect what Lago invoices. ### Deployment options Lago officially supports two paths, listed in the [self-hosted overview](https://getlago.com/docs/guide/lago-self-hosted/overview). Check the [compatibility matrix](https://getlago.com/docs/guide/lago-self-hosted/compatibility-matrix) before you provision anything. For new installs it recommends PostgreSQL 15+, Redis 7.x or Valkey 7.2+, and Kubernetes 1.26+ for Helm, with the `pg_partman` extension installed on PostgreSQL. #### Docker Compose: the quickstart Docker Compose suits evaluation, local development and smaller production setups. The following is taken from the [Lago Docker documentation](https://getlago.com/docs/guide/lago-self-hosted/docker) and shown for illustration. Follow the docs for the current version. ```bash # Get the code git clone https://github.com/getlago/lago.git # Go to Lago folder cd lago # Fetch all tags git fetch --tags # Get the latest tag and checkout git checkout $(git describe --tags --abbrev=0) # Set up environment configuration echo "LAGO_RSA_PRIVATE_KEY=\"`openssl genrsa 2048 | base64 | tr -d '\n'`\"" >> .env source .env # Start all the components docker compose up ``` The UI is then at `http://localhost`. After you sign up and create your organization, the API is exposed at `http://localhost:3000`. The docs recommend pinning a tagged release rather than the `latest` tag. #### Kubernetes with Helm: production at scale The [official Helm charts](https://getlago.com/docs/guide/lago-self-hosted/kubernetes) need Kubernetes 1.26 or later, Helm 3.8 or later, and a PostgreSQL database and Redis instance the cluster can reach. The charts deploy neither, and they don't deploy object storage either. Point them at managed services or instances you run separately. ```bash helm repo add lago https://charts.getlago.com helm repo update helm install lago lago/lago -f values.yaml ``` A default install creates four Deployments (API, front-end, one worker for every queue, and the clock) plus a migration Job. From there you can split queues such as billing, events, webhooks and PDF into dedicated workers, each sized and scaled on its own, so a slow billing run can't starve webhook delivery. The [chart repository](https://github.com/getlago/lago-helm-charts) documents every value. ### Infrastructure and operating checklist Defaults are for getting started. Work through this list before your first real invoice. - **PostgreSQL.** Run a supported version with `pg_partman`. Keep `DATABASE_POOL` multiplied by your API, worker and clock instances comfortably below `max_connections`. Set statement, lock and idle-transaction timeouts, which are unset by default, and enable SSL if your server requires it. - **Redis.** Lago uses Redis as the Sidekiq job queue and as an application cache, configurable separately. Redis Sentinel is supported for high availability on each. - **Event store.** PostgreSQL needs no extra infrastructure and is validated up to about 10,000 events per second. ClickHouse, running on a Kafka or Redpanda pipeline, is the [optional event store](https://getlago.com/blog/using-clickhouse-to-scale-your-events-engine) for higher volumes. The store is set per organization, and self-hosted ClickHouse and Redpanda are yours to administer. - **Throughput planning.** The docs list about 1,000 events per second for single REST calls, about 10,000 for batch calls, and higher sustained rates through Kafka or Redpanda with ClickHouse. Size for your [expected peak](https://getlago.com/docs/guide/events/usage-performances), plus headroom for growth. - **Object storage.** Configure S3, an S3-compatible endpoint or Google Cloud Storage. On Kubernetes, without object storage, generated files live in the container filesystem and are lost when a pod restarts. - **Secrets.** Replace the default database password, `SECRET_KEY_BASE`, the RSA key and the three encryption keys. Keep them out of version control. Changing an encryption key after the fact makes previously encrypted data unreadable. - **TLS and email.** Enable SSL on the front-end and configure SMTP so your instance can send email. - **Upgrades.** Lago ships updates every one to two weeks. [Updating a Docker install](https://getlago.com/docs/guide/lago-self-hosted/update-instance) means checking out the new tag and restarting, after any mandatory bridge releases. On Helm, `helm upgrade` runs the migration Job first. Moving from chart 1.x to 2.x is a new install, not an upgrade. - **Monitoring.** Wire error tracking (the Docker guide documents Sentry variables) and watch billing signals, not only CPU and memory: ingestion rate, invoice generation and webhook delivery. More in our post on [billing observability](https://getlago.com/blog/billing-observability). - **Backups.** Backups and restores are your responsibility. Schedule them, then rehearse a restore before month end does it for you. - **Access control.** Disable public sign-up with `LAGO_DISABLE_SIGNUP` once your organization exists, and restrict which networks can reach the API and the UI. - **API keys.** You can [reveal and rotate API keys](https://getlago.com/docs/guide/security/api-keys) in the open-source product. Creating additional keys and scheduling rotations are premium, and per-key permissions are an enterprise add-on. ### Test the hard parts before go-live Billing fails at the edges. Test them explicitly: - **Dates:** time zones, calendar month lengths, leap years, billing cycle alignment and mid-cycle proration. - **Usage:** duplicate events, late or corrected events, and tier thresholds that trigger at the right volume. - **Payments:** idempotent retries, failed-payment sequences and tax across jurisdictions. - **Load:** your peak event rate, replayed against a staging instance. If you're replacing an existing system, run both in parallel for at least one billing cycle and compare invoices line by line. Our [billing system migration guide](https://getlago.com/blog/billing-system-migration) covers the cutover. ### Licensing and what's premium Lago's repository is public under [AGPL-3.0](https://getlago.com/blog/open-source-licensing-and-why-lago-chose-agplv3). Review the license against how you plan to deploy and distribute Lago. The open-source product covers customers, plans, subscriptions, usage metering, invoicing, the REST API and webhooks. Some capabilities belong to Lago Premium, available on Lago Cloud or self-hosted, including credit notes, [role-based access control](https://getlago.com/docs/guide/security/rbac) and [SSO](https://getlago.com/docs/guide/security/sso) as add-ons, and [activity logs](https://getlago.com/docs/guide/security/audit-logs). The [pricing and packaging summary](https://getlago.com/docs/pricing) lists what each option includes. Check the docs for the exact release you plan to deploy. ### Should you self-host at all? Self-hosting is worth the operating work when billing data has to stay in your environment, for regulatory, contractual or security reasons, or when you need to modify the engine. If none of those apply, managed cloud usually gets you to your first invoice with less work. If you start on one option, moving to another later is a configuration change. Our guide to [self-hosted vs cloud billing](https://getlago.com/blog/self-hosted-vs-cloud-billing) walks through the decision. ### Get the full guide For the cost drivers, the CFO's view and a decision framework to take to your security and finance teams, download [**Self-Hosted vs Cloud Billing: The Complete Guide**](https://getlago.com/academy/self-hosted-vs-cloud?utm_source=blog&utm_medium=cta&utm_campaign=self-hosted-billing). Ready to deploy? Start with the [self-hosting docs](https://getlago.com/docs/guide/lago-self-hosted/overview), or [book a demo](https://getlago.com/book-a-demo) to talk through self-hosted premium.