Instalar Kill Bill con Docker

Sigue la guía de los stacks de Docker para instalar Kill Bill con nuestro stack y ten en cuenta lo propio de esta plataforma. El detalle completo está en el README del repositorio.

Recursos

El stack necesita unos 3,5 GB de disco para las imágenes y 2,5 GB de RAM, porque Kill Bill y Kaui (su interfaz de administración) son dos aplicaciones Java. En reposo usa alrededor de 1 GiB en Kill Bill, 900 MiB en Kaui, 120 MiB en MariaDB y 12 MiB en Caddy. El primer arranque tarda cerca de un minuto.

Variables obligatorias

Para las contraseñas y la clave y el secreto del tenant, la plantilla sugiere openssl rand -hex 24.

Configuración inicial

En el primer arranque, setup crea el tenant con KILLBILL_API_KEY, KILLBILL_API_SECRET y el nombre de KILLBILL_TENANT_NAME (por defecto default). En cada arranque aplica, si cambiaron:

• KILLBILL_NOTIFICATION_URL: la URL a la que Kill Bill envía los eventos del tenant (factura creada, pago exitoso o fallido, etc.), por ejemplo BillMySales.
• Los textos en español de las facturas y correos para las cuentas con el idioma de KILLBILL_INVOICE_LOCALE (por defecto es_CL), con los datos de tu empresa en KILLBILL_COMPANY_NAME, KILLBILL_COMPANY_ADDRESS, KILLBILL_COMPANY_CITY y KILLBILL_COMPANY_COUNTRY.
• La configuración de correo (SMTP_*) y los eventos que se notifican por correo, en KILLBILL_EMAIL_EVENTS.

Kill Bill parte vacío: crea los planes, cuentas y suscripciones en Kaui o por la API. Para Chile usa la moneda CLP, la zona horaria America/Santiago y el idioma es_CL en cada cuenta.

Acceso

Cuando setup termina, Kaui queda disponible en tu dominio con el usuario admin y la contraseña de KILLBILL_ADMIN_PASSWORD, con el tenant ya abierto. La API está en /1.0/kb (autenticación básica con el mismo usuario, más las cabeceras con la clave y el secreto del tenant) y su documentación en /api.html.

Actualizaciones

Kill Bill se actualiza cambiando KILLBILL_VERSION (y KAUI_VERSION y EMAIL_NOTIFICATIONS_VERSION) en el .env y ejecutando:

docker compose up -d --build

Respalda antes. La imagen de Kill Bill se reconstruye con la nueva versión y el servicio migrate aplica las migraciones del esquema antes de que Kill Bill arranque. No se puede volver a una versión anterior. Para recibir las actualizaciones de la imagen base, reconstruye periódicamente con docker compose build --pull.

Restaurar un respaldo

Los respaldos incluyen las bases de datos de Kill Bill y de Kaui, y la clave de cifrado de Kaui. Kill Bill mantiene cachés, así que detenlo antes de restaurar:

docker compose stop killbill kaui
docker compose run --rm --no-deps backup restore <fecha>
docker compose up -d

Notas

• El plugin de correos solo admite SMTPS (SMTP_SECURE=ssl, el valor por defecto, puerto 465) o SMTP sin cifrado (SMTP_SECURE=none); no admite STARTTLS en el puerto 587. Sin SMTP_HOST no se envían correos.
• Si BillMySales envía los documentos tributarios a tus clientes, deja KILLBILL_EMAIL_EVENTS vacío para mantener solo las notificaciones a KILLBILL_NOTIFICATION_URL. La factura HTML de Kill Bill no es un documento tributario chileno.

Siguiente paso

Con Kill Bill funcionando, configúralo como origen de datos en BillMySales siguiendo la configuración inicial.