--- title: "Instalación con Docker" description: "Instalar Kill Bill con Docker" type: "docs" category: "doc" tags: [] authors: [Anonymous] date: "2026-09-25" last_update: "2026-09-25" time_minutes: 4 draft: false unlisted: false url: "https://www.billmysales.com/docs/datasources/killbill/docker" --- # Instalar Kill Bill con Docker Sigue la [guía de los stacks de Docker](https://www.billmysales.com/docs/stacks) para instalar Kill Bill con nuestro [stack](https://github.com/BillMySales/billmysales-docker-killbill) 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 | Variable | Qué debe contener | |---|---| | `KILLBILL_URL` | URL pública de la plataforma, por ejemplo `https://billing.example.com`. En ella quedan Kaui y la API. | | `SITE_ADDRESS` | El dominio de la plataforma, por ejemplo `billing.example.com`. | | `DB_ROOT_PASSWORD` y `DB_PASSWORD` | Contraseñas de la base de datos. | | `KILLBILL_ADMIN_PASSWORD` | Contraseña del usuario `admin`, para Kaui y la API. | | `KILLBILL_API_KEY` y `KILLBILL_API_SECRET` | Clave y secreto del tenant (cabeceras `X-Killbill-ApiKey` y `X-Killbill-ApiSecret`). El secreto no se puede cambiar una vez creado el tenant. | | `KAUI_SECRET_KEY_BASE` | Secreto de sesión de Kaui. Genéralo con `openssl rand -hex 64`. | | `SMTP_HOST` | **Recomendada:** el stack arranca sin ella, pero la plataforma no podrá enviar correos. Servidor SMTP. Completa también `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASSWORD` y `SMTP_FROM` según tu proveedor. | 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: ```shell 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: ```shell docker compose stop killbill kaui docker compose run --rm --no-deps backup restore 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](https://www.billmysales.com/docs/datasources/killbill/configuracion-inicial). --- Última actualización el 25/09/2026