docker.recipes

Lago

intermediate

Open-source metering and usage-based billing.

Overview

Lago is an open-source metering and usage-based billing platform designed to help businesses implement sophisticated pricing models beyond traditional subscription fees. Developed to address the complexity of modern SaaS billing requirements, Lago enables companies to track customer usage across multiple dimensions and automatically generate accurate invoices based on consumption patterns, subscription tiers, or hybrid models combining both approaches. This Docker configuration combines Lago's API and frontend components with PostgreSQL for reliable billing data storage and Redis for high-performance session management and background job processing. PostgreSQL's ACID compliance ensures billing accuracy and data integrity - critical requirements when handling financial transactions and customer invoicing. Redis accelerates the platform by caching frequently accessed pricing rules, managing user sessions, and queuing billing calculations that need to process large volumes of usage events. This stack targets SaaS companies, API providers, and usage-based service businesses that need to move beyond simple monthly subscriptions. Development teams building platforms with pay-per-use models, tiered pricing, or complex billing rules will find Lago particularly valuable for replacing expensive third-party billing solutions with a self-hosted alternative that offers complete control over pricing logic and customer data.

Key Features

  • Real-time usage metering with billable metrics tracking API calls, storage consumption, and custom events
  • Advanced pricing models including graduated tiers, package deals, percentage-based fees, and volume discounts
  • PostgreSQL-backed invoice generation with automated tax calculations and multi-currency support
  • Redis-powered background processing for high-volume usage aggregation and billing calculations
  • Webhook system for real-time notifications on invoice creation, payment events, and subscription changes
  • Customer portal integration allowing end-users to view usage analytics and billing history
  • Subscription lifecycle management with proration, upgrades, downgrades, and custom billing cycles
  • Multi-tenant architecture supporting usage isolation and billing segmentation across customer organizations

Common Use Cases

  • 1API-first companies billing customers based on request volume, bandwidth usage, or compute resources consumed
  • 2Cloud storage providers implementing tiered pricing with different rates for storage, bandwidth, and API operations
  • 3SaaS platforms combining monthly subscriptions with overage charges for premium features or usage limits
  • 4Development teams building internal billing systems for multi-product companies with complex pricing structures
  • 5Telecommunications and IoT service providers tracking device usage, data consumption, and service utilization
  • 6Marketplace platforms charging transaction fees, listing fees, and usage-based commission structures
  • 7Enterprise software vendors implementing seat-based licensing with additional usage-based feature charges

Prerequisites

  • Minimum 2GB RAM recommended for PostgreSQL billing data processing and Redis caching operations
  • Available ports 3000 (Lago API), 8080 (web interface), 5432 (PostgreSQL), and 6379 (Redis)
  • Understanding of billing concepts like metering, pricing plans, and invoice generation workflows
  • Environment variables configured for database credentials and Lago's secret key authentication
  • Knowledge of webhook integrations for connecting billing events to payment processors or accounting systems
  • Familiarity with usage-based billing models and how to define billable metrics for your specific use case

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  lago-api: 
3    image: getlago/api:latest
4    container_name: lago-api
5    restart: unless-stopped
6    environment: 
7      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
8      REDIS_URL: redis://redis:6379
9      SECRET_KEY_BASE: ${SECRET_KEY}
10    ports: 
11      - "3000:3000"
12    depends_on: 
13      - postgres
14      - redis
15    networks: 
16      - lago
17
18  lago-front: 
19    image: getlago/front:latest
20    container_name: lago-front
21    environment: 
22      API_URL: http://lago-api:3000
23    ports: 
24      - "8080:80"
25    depends_on: 
26      - lago-api
27    networks: 
28      - lago
29
30  postgres: 
31    image: postgres:16-alpine
32    container_name: lago-postgres
33    environment: 
34      POSTGRES_DB: ${DB_NAME}
35      POSTGRES_USER: ${DB_USER}
36      POSTGRES_PASSWORD: ${DB_PASSWORD}
37    volumes: 
38      - postgres_data:/var/lib/postgresql/data
39    networks: 
40      - lago
41
42  redis: 
43    image: redis:alpine
44    container_name: lago-redis
45    networks: 
46      - lago
47
48volumes: 
49  postgres_data: 
50
51networks: 
52  lago: 
53    driver: bridge

.env Template

.env
1DB_NAME=lago
2DB_USER=lago
3DB_PASSWORD=changeme
4SECRET_KEY=your-secret-key

Usage Notes

  1. 1Docs: https://docs.getlago.com/
  2. 2UI at http://localhost:8080, API at http://localhost:3000
  3. 3Create billable metrics for metering (API calls, storage, etc)
  4. 4Define pricing plans: flat fees, graduated, package, percentage
  5. 5Supports usage-based, subscription, and hybrid billing models
  6. 6Webhook events for invoice, payment, subscription lifecycle

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

lago-api
lago-api:
  image: getlago/api:latest
  container_name: lago-api
  restart: unless-stopped
  environment:
    DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
    REDIS_URL: redis://redis:6379
    SECRET_KEY_BASE: ${SECRET_KEY}
  ports:
    - "3000:3000"
  depends_on:
    - postgres
    - redis
  networks:
    - lago
lago-front
lago-front:
  image: getlago/front:latest
  container_name: lago-front
  environment:
    API_URL: http://lago-api:3000
  ports:
    - "8080:80"
  depends_on:
    - lago-api
  networks:
    - lago
postgres
postgres:
  image: postgres:16-alpine
  container_name: lago-postgres
  environment:
    POSTGRES_DB: ${DB_NAME}
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PASSWORD: ${DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - lago
redis
redis:
  image: redis:alpine
  container_name: lago-redis
  networks:
    - lago

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  lago-api:
5    image: getlago/api:latest
6    container_name: lago-api
7    restart: unless-stopped
8    environment:
9      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
10      REDIS_URL: redis://redis:6379
11      SECRET_KEY_BASE: ${SECRET_KEY}
12    ports:
13      - "3000:3000"
14    depends_on:
15      - postgres
16      - redis
17    networks:
18      - lago
19
20  lago-front:
21    image: getlago/front:latest
22    container_name: lago-front
23    environment:
24      API_URL: http://lago-api:3000
25    ports:
26      - "8080:80"
27    depends_on:
28      - lago-api
29    networks:
30      - lago
31
32  postgres:
33    image: postgres:16-alpine
34    container_name: lago-postgres
35    environment:
36      POSTGRES_DB: ${DB_NAME}
37      POSTGRES_USER: ${DB_USER}
38      POSTGRES_PASSWORD: ${DB_PASSWORD}
39    volumes:
40      - postgres_data:/var/lib/postgresql/data
41    networks:
42      - lago
43
44  redis:
45    image: redis:alpine
46    container_name: lago-redis
47    networks:
48      - lago
49
50volumes:
51  postgres_data:
52
53networks:
54  lago:
55    driver: bridge
56EOF
57
58# 2. Create the .env file
59cat > .env << 'EOF'
60DB_NAME=lago
61DB_USER=lago
62DB_PASSWORD=changeme
63SECRET_KEY=your-secret-key
64EOF
65
66# 3. Start the services
67docker compose up -d
68
69# 4. View logs
70docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/lago/run | bash

Troubleshooting

  • Lago API failing to connect to PostgreSQL: Verify DATABASE_URL format and ensure PostgreSQL container is fully started before lago-api
  • Usage events not processing correctly: Check Redis connectivity and ensure REDIS_URL matches the redis service network configuration
  • Frontend showing 'API connection failed': Confirm lago-front can reach lago-api container and API_URL environment variable is correctly set
  • Database migration errors on startup: Ensure PostgreSQL has sufficient disk space and proper permissions for the postgres_data volume
  • Webhook delivery failures: Verify your external webhook endpoints are accessible from the Docker network and return proper HTTP status codes
  • High memory usage during billing calculations: Monitor Redis memory consumption and consider increasing container limits during peak billing cycles

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

lagopostgresredis

Tags

#lago#billing#metering#subscriptions

Category

E-Commerce & Business

Related Recipes

Ad Space