Skip to content
Klutch.sh Docs

Deploying a Lago App

Introduction

Lago is an open-source metering and billing platform built with Elixir and Phoenix. Deploying Lago with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for invoices and exports—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production best practices.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Lago code/config (GitHub is the only supported git source)
  • Docker familiarity and Elixir/Phoenix basics
  • PostgreSQL and Redis credentials
  • Storage for exports, logs, and attachments

For onboarding, see the Quick Start.

Architecture and ports

  • Lago serves HTTP on port 4000; set the internal container port to 4000.
  • PostgreSQL and Redis should run as separate Klutch.sh TCP apps, exposed on port 8000 and connected internally on 5432 and 6379.
  • Persistent storage is recommended for uploads/exports and logs.

Repository layout

lago/
├── config/                 # Runtime configuration
├── priv/static/            # Static assets
├── uploads/                # Exports and attachments (mount as volume)
├── Dockerfile              # Must be at repo root for auto-detection
├── mix.exs
├── mix.lock
└── .env.example            # Template only; no secrets

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Install dependencies and run locally before pushing to GitHub:

Terminal window
mix deps.get
mix ecto.setup
mix phx.server

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
mix ecto.migrate
exec mix phx.server

Make it executable with chmod +x start.sh.

Dockerfile for Lago (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM getlago/lago:latest


WORKDIR /app


# Optional: copy custom configs or assets
COPY config /app/config


EXPOSE 4000
CMD ["./bin/server"]

Notes:

  • Pin the image tag (e.g., getlago/lago:0.51.0) for reproducible builds.
  • If you build from source, add an Elixir build stage and create a release; then copy it into a minimal runtime image.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • PORT=4000
  • DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db>
  • REDIS_URL=redis://<user>:<password>@<host>:<port>
  • SECRET_KEY_BASE=<secure-value>
  • LAGO_ENCRYPTION_KEY=<secure-32-byte>
  • LAGO_HOST=https://example-app.klutch.sh
  • MIX_ENV=prod

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_ELIXIR_VERSION=1.15
  • NIXPACKS_ERLANG_VERSION=26
  • NIXPACKS_BUILD_CMD=mix deps.get && MIX_ENV=prod mix assets.deploy && MIX_ENV=prod mix release
  • NIXPACKS_START_CMD=./bin/server

These keep Lago compatible with Nixpacks defaults when a Dockerfile is absent.

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /app/uploads — invoices, exports, and attachments.
  • /app/log — optional logs if you persist them locally.

Ensure these paths are writable inside the container.

Deploy Lago on Klutch.sh (Dockerfile workflow)

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose HTTP traffic for Lago.
  3. Set the internal port to 4000.
  4. Add the environment variables above (database/Redis URLs, secrets, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /app/uploads (and /app/log if used), choosing sizes that fit your storage needs.
  6. Deploy. Your Lago instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample API call

Create a customer via the Lago API (replace placeholders):

Terminal window
curl -X POST "https://example-app.klutch.sh/api/v1/customers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{"customer": {"external_id": "cust_123", "name": "ACME", "email": "billing@acme.test"}}'

Health checks and production tips

  • Probe /health (or a lightweight route) through your reverse proxy for uptime checks.
  • Enforce HTTPS at the edge; forward HTTP to port 4000 internally.
  • Keep image and dependency versions pinned; upgrade intentionally with DB migrations.
  • Monitor disk usage on /app/uploads and /app/log; resize volumes before they fill.
  • Back up PostgreSQL and uploaded assets regularly; do not rely on container filesystems for durability.

Lago on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage for billing artifacts, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and port 4000 configured, you can run reliable metering and billing without extra YAML or workflow overhead.