Instalar Lago con Docker
Sigue la guía de los stacks de Docker para instalar Lago con nuestro stack y ten en cuenta lo propio de esta plataforma. El detalle completo está en el README del repositorio.
Recursos
Este stack necesita unos 3 GB de disco para las imágenes (1,8 GB solo Gotenberg, que genera los PDF) y 1,5 GB de RAM. En reposo usa alrededor de 1,35 GiB en total.
El stack construye su propia imagen de la base de datos (PostgreSQL con pg_partman), lo que toma unos 35 segundos. Basta con docker compose up -d: la construye en el primer arranque y cada vez que cambia su etiqueta.
Variables obligatorias
| Variable | Qué debe contener |
|---|---|
LAGO_URL |
URL pública de la plataforma, por ejemplo https://billing.example.com. En ella quedan la aplicación y la API. |
SITE_ADDRESS |
El dominio de la plataforma, por ejemplo billing.example.com. |
SECRET_KEY_BASE |
Secreto de Rails. Genéralo con openssl rand -hex 64. |
LAGO_ENCRYPTION_PRIMARY_KEY, LAGO_ENCRYPTION_DETERMINISTIC_KEY y LAGO_ENCRYPTION_KEY_DERIVATION_SALT |
Claves de cifrado de la base de datos. Genera cada una con openssl rand -hex 32. |
DB_PASSWORD |
Contraseña de la base de datos. |
LAGO_ADMIN_EMAIL y LAGO_ADMIN_PASSWORD |
Correo y contraseña del administrador. El administrador se crea si no existe un usuario con ese correo, y la contraseña solo se aplica al crearlo; si cambias el correo después, se agrega otro administrador. |
SMTP_HOST |
Recomendada: el stack arranca sin ella, pero la plataforma no podrá enviar correos. Servidor SMTP. Completa también SMTP_PORT (por defecto 587), SMTP_USER, SMTP_PASSWORD y SMTP_FROM según tu proveedor. |
Las tres claves LAGO_ENCRYPTION_* están en el .env, no en los respaldos. Sin ellas, los campos cifrados de una base de datos restaurada no se pueden leer.
Configuración inicial de la organización
La organización se crea configurada para Chile (país CL, moneda CLP, ciudad Santiago, documentos en español y un impuesto IVA de 19% aplicado por defecto). Si operas en otro país, cambia LAGO_ORG_NAME, LAGO_COUNTRY, LAGO_CURRENCY, LAGO_CITY, LAGO_DOCUMENT_LOCALE, LAGO_TAX_RATE y LAGO_TAX_NAME antes del primer arranque: estos valores solo se aplican en la instalación inicial y después se modifican desde la aplicación.
Acceso
Cuando setup termina, la aplicación queda disponible en tu dominio con el correo de LAGO_ADMIN_EMAIL. La API REST está en /api/v1 y usa una clave de la organización (cabecera Authorization: Bearer <clave>), que encuentras en Developers > API keys. Si quieres una clave fija, defínela en LAGO_API_KEY.
Actualizaciones
Lago se actualiza cambiando LAGO_VERSION en el .env y ejecutando docker compose up -d. Respalda antes y revisa las notas de versión de Lago. Se descargan las nuevas imágenes y setup ejecuta las migraciones antes de que arranque la API.
docker compose up -d construye la imagen de la base de datos cada vez que cambia su etiqueta (POSTGRES_VERSION, PARTMAN_VERSION). Si cambias PARTMAN_VERSION, indica en PARTMAN_SHA256 el SHA-256 del archivo de esa versión, o déjalo vacío para no verificarlo. Para las actualizaciones menores de PostgreSQL, reconstruye la imagen con docker compose build --pull db y luego ejecuta docker compose up -d. Una nueva versión mayor de PostgreSQL requiere un volcado y una restauración.
Restaurar un respaldo
Los respaldos incluyen la base de datos, los archivos (PDF y archivos subidos) y la clave RSA que firma los webhooks. Para restaurar uno:
docker compose stop api worker clock
docker compose run --rm --no-deps backup restore <fecha>
docker compose exec redis redis-cli FLUSHALL
docker compose up -d
Notas
- En la edición gratuita la zona horaria es siempre UTC (un periodo de facturación termina a medianoche UTC) y Lago no envía por correo facturas, notas de crédito ni recibos. Estas funciones requieren una licencia premium en
LAGO_LICENSE. - Lago usa STARTTLS cuando el servidor lo ofrece (puerto 587) y no admite SMTPS (puerto 465). Sin
SMTP_HOSTno se envían correos.
Siguiente paso
Con Lago funcionando, configúralo como origen de datos en BillMySales siguiendo la configuración inicial.