s
saulo
## Context
First of all, congratulations to the Lago team — it’s one of the most robust and transparent open-source billing platforms available today.
However, deploying Lago
self-hosted
is still complex and time-consuming, especially for users who want to run it on modern
PaaS platforms
— both
self-hosted
and
managed cloud solutions
.
I’ve personally tried to deploy Lago multiple times, even with step-by-step help from ChatGPT, and
still couldn’t get it running properly
.
Most of the issues were related to environment variables, RSA key formatting, and networking between containers (
api
,
front
,
worker
,
clock
,
pdf
,
postgres
,
redis
).
Today, many developers use platforms like:
### 🧩 PaaS Self-Hosted
### ☁️ PaaS Hosted (Managed)
These tools have become the modern standard for developers who want
“self-hosted Heroku-like”
experiences — a simple, visual way to deploy Docker-based applications in production environments.
Unfortunately, **Lago currently doesn’t provide an official
docker-compose.yml
or manifest optimized for these deployers**, which makes installation difficult even for experienced users.
---
## The problem
  • The current documentation focuses on local Docker setup and manual orchestration.
  • There’s no
    verified YAML definition
    for external PaaS or automated deployers.
  • Lago’s multi-service stack —
    api
    ,
    front
    ,
    worker
    ,
    clock
    ,
    pdf
    ,
    postgres
    , and
    redis
    — requires precise networking and environment configuration.
  • Variables like
    LAGO_RSA_PRIVATE_KEY
    (multiline PEM) and
    LAGO_API_URL
    are especially error-prone when set inside UI-based deployers.
  • Common issues include:
- API container crashing due to RSA key parsing errors;
- Worker and clock services restarting endlessly;
- Frontend failing to connect to the backend;
- Health checks failing even when containers are technically running.
---
## Why it matters
An **official, deployer-friendly
docker-compose.yml
** would:
  • Enable
    one-click deployment
    on platforms like Coolify, Dokku, CapRover, and Railway;
  • Reduce onboarding friction and YAML misconfigurations;
  • Make Lago more accessible to small SaaS teams, indie devs, and startups that use PaaS tools;
  • Increase adoption among self-hosted users who prefer visual or low-code deployers;
  • Strengthen Lago’s ecosystem as the
    open-source alternative to Stripe Billing
    that anyone can run in production.
---
## Suggested improvements
  1. **Provide an official
    docker-compose.yml
    ** optimized for external deployers (not just local development);
  2. Include an example
    .env
    with:
- Proper variable formatting;
- Comments explaining multi-line secrets (e.g.,
LAGO_RSA_PRIVATE_KEY
);
- URL guidance for internal vs. external routing;
  1. Add short documentation or notes about deploying Lago in self-hosted PaaS platforms;
  2. Optionally, verify the setup on at least one environment (Coolify, Dokku, or Railway).
---
## Closing thoughts
Lago is an amazing open-source project that deserves a smoother deployment experience.
Offering a **ready-to-use YAML and
.env
example** compatible with self-hosted and cloud PaaS environments would dramatically lower the barrier to entry — helping more developers successfully self-host their billing systems.
Thank you for considering this request and for building such an impactful open-source project.