Instalar Heskala on-premise

Cómo instalar y correr Heskala on-premise: bajá el bundle desde GitHub Releases, ejecutá el instalador y en pocos minutos tenés tu ERP corriendo 100% en tu infraestructura.

Qué es on-prem

Heskala en modo on-prem corre 100% en tu infraestructura: backend de Convex self-hosted, base SQLite y frontend servido como estático. La activación se hace con una licencia firmada (token ECDSA) que define qué módulos incluidos, cuántos usuarios y cuántas sucursales tenés.

Requisitos

• Docker 20.10+ (con docker compose v2)
• 2 GB de RAM disponibles
• 10 GB de disco para los datos
• Linux, macOS o Windows con WSL2 — en Windows, si querés evitar Docker Desktop, mirá Instalar en Windows (sin Docker Desktop)
• Conexión a internet (para bajar el bundle y las imágenes, y para activar y validar la licencia contra Heskala Cloud). La licencia se ata a tu instalación en la activación: una licencia = una instalación (ver Licencia de un solo uso más abajo).

No necesitás acceso al código fuente ni a ninguna cuenta de GitHub. El bundle se descarga desde este sitio y las imágenes ghcr.io/heskala/frontend y ghcr.io/heskala/convex-deployer desde GHCR (ambas públicas).

Instalación express (un solo comando)

Si solo querés levantarlo y empezar:

curl -fsSL https://docs.heskala.com/install.sh | bash

Esta URL es estable: siempre instala la última versión publicada (lee downloads/latest.txt y baja el bundle correspondiente). No hace falta cambiar el comando entre releases. El bundle se hostea en este sitio (público) porque el repo de GitHub es privado; el one-liner funciona para cualquiera, sin cuenta ni token.

El script:

• Verifica los prerequisitos: Docker corriendo, el plugin docker compose v2 (el viejo docker-compose con guion no sirve) y la versión del engine (20.10+)
• Ofrece habilitar Docker en el boot (systemd) para que el stack vuelva solo tras un reinicio
• Crea ~/heskala-onprem y copia el compose desde el bundle
• Genera un INSTANCE_SECRET random
• Te pregunta el INSTANCE_NAME (default: heskala-onprem)
• Levanta los 4 servicios y espera al backend healthy
• Genera el admin key y lo guarda en .admin-key (chmod 600)
• Arranca el deployer, que sube las funciones y setea las env vars necesarias
• Instala la CLI heskala para gestionar tu instalación (ver Administrar la instalación)
• Imprime las URLs y los próximos pasos

Para personalizar (directorio, RESEND_API_KEY, etc.):

# Directorio custom
curl -fsSL https://docs.heskala.com/install.sh | bash -s -- /opt/heskala

# Con Resend habilitado
curl -fsSL https://docs.heskala.com/install.sh | RESEND_API_KEY=re_xxx bash

# Nombre de instancia custom
curl -fsSL https://docs.heskala.com/install.sh | HESKALA_INSTANCE=mi-empresa bash

# Fijar una versión específica (en vez de la última)
curl -fsSL https://docs.heskala.com/install.sh | HESKALA_VERSION=0.9.0 bash

Si elegís un directorio protegido (ej. /opt/heskala, propiedad de root), el instalador lo crea con sudo y te devuelve la propiedad automáticamente (puede pedirte la contraseña). No necesitás pre-crearlo a mano.

Modo desatendido y flags (automatización)

Si ya hay una instalación, el instalador muestra un menú (Actualizar / Reinstalar / Cancelar). Para correrlo sin interacción (CI, scripts, agents), usá flags:

Flag	Equivale a	Para qué
-d, --dir PATH	HESKALA_DIR	Directorio de instalación
-a, --action install|update	HESKALA_ACTION	Salta el menú y elige la acción
--instance NAME	HESKALA_INSTANCE	Nombre de instancia (salta el prompt)
--version TAG	HESKALA_VERSION	Tag de imágenes a usar
-y, --yes	—	No pregunta nada (modo desatendido)
-h, --help	—	Ayuda

# Actualizar desatendido (conserva datos)
bash install.sh --dir /opt/heskala --action update

# Reinstalar desde cero SIN prompts (⚠️  BORRA los datos)
bash install.sh -d /opt/heskala -a install -y

Sin TTY (p. ej. curl … | bash) el default es Actualizar si ya existe una instalación. La reinstalación destructiva queda bloqueada salvo que pases -y/--yes explícito, para no borrar datos por accidente.

¿Ya lo tenés instalado y querés pasar a una versión nueva sin perder datos? Mirá Actualizar a una versión nueva.

Para ver qué versiones están disponibles para descargar: https://docs.heskala.com/downloads/

Configuración: correo y URL pública

Todo se configura por variables de entorno en el .env (o pasándolas al install.sh). Las de correo y URL son las que más se ajustan:

Variable	Para qué	Default
SITE_URL	URL pública de tu instalación. Se usa en los links de los correos (invitaciones, reset de contraseña, etc.).	https://erp.heskala.com
RESEND_API_KEY	API key de Resend para enviar correos. Sin ella, los flujos de email quedan deshabilitados (el resto funciona igual).	—
RESEND_FROM_EMAIL	Dirección del remitente. Debe usar un dominio verificado en tu cuenta de Resend; si no, Resend rechaza el envío.	no-reply@erp.heskala.com
RESEND_FROM_NAME	Nombre visible del remitente.	Heskala

# En el .env de tu instalación:
SITE_URL=https://erp.micliente.com
RESEND_API_KEY=re_xxxxxxxx
RESEND_FROM_EMAIL=no-reply@micliente.com
RESEND_FROM_NAME=Mi Empresa

⚠️ Si cambiás RESEND_API_KEY a tu propia cuenta pero no seteás RESEND_FROM_EMAIL, Resend intentará enviar desde no-reply@erp.heskala.com —un dominio que tu cuenta no tiene verificado— y fallará. Seteá siempre tu propio remitente con un dominio verificado. Del mismo modo, seteá SITE_URL para que los links de los correos no apunten a erp.heskala.com.

Arranque automático (reinicio / corte de energía)

Los servicios vuelven solos cuando la máquina se enciende de nuevo: en el docker-compose.yml, backend, frontend y dashboard usan restart: unless-stopped, así que Docker los relanza tras un reinicio o un corte de luz. El deployer no se relanza (es de una sola corrida) y no hace falta: las funciones y las env vars ya quedaron persistidas en el volumen data.

Requisito: el daemon de Docker debe arrancar en el boot (si no, no hay quién levante los contenedores). En Linux con systemd, el propio instalador detecta si Docker no está habilitado al boot y te ofrece activarlo (systemctl enable docker). Si lo omitiste o preferís hacerlo a mano:

• Linux (servidor, systemd):

  sudo systemctl enable --now docker

  (normalmente ya viene habilitado; el comando lo asegura).
• Docker Desktop (macOS / Windows): Settings → General → activá “Start Docker Desktop when you sign in”. En una PC de mostrador que se apaga con la luz, además conviene el auto-login del usuario, para que al encender la sesión inicie sola y con ella Docker.

Para probarlo sin cortar la energía:

sudo reboot            # o apagá/encendé la máquina
# al volver, sin tocar nada:
cd ~/heskala-onprem && docker compose ps   # backend/frontend/dashboard → Up

Si querés que arranquen siempre (incluso si alguien los paró a mano), cambiá unless-stopped por always en el docker-compose.yml. unless-stopped es el recomendado: vuelven tras un reinicio pero respetan un docker compose stop intencional.

Actualizar a una versión nueva (sin perder datos)

Tus datos viven en un volumen Docker con nombre (data, montado en /convex/data del backend) — es la base de Convex. Está separado de las imágenes, así que actualizar el sistema no toca tus datos.

Opción A — con el instalador (recomendada): corré el mismo bootstrap estable apuntando a tu directorio existente. Baja la última versión, detecta la instalación y te ofrece un menú; elegí Actualizar (conserva tus datos):

curl -fsSL https://docs.heskala.com/install.sh | bash -s -- /opt/heskala

Opción B — manual:

cd ~/heskala-onprem      # tu directorio de instalación
docker compose pull       # trae las imágenes nuevas
docker compose up -d       # recrea los contenedores, conserva el volumen `data`

En ambos casos el deployer vuelve a correr, sube las funciones nuevas al mismo backend y se apaga. El volumen data no se toca.

⚠️ Lo único que borra tus datos es docker compose down -v (con -v) o un docker volume rm. Un pull / up -d / down (sin -v) no los borra.

Para automatizar el upgrade sin el menú: bash install.sh --dir /opt/heskala --action update (ver Modo desatendido y flags).

Backup antes de actualizar (recomendado)

Como es una base local (SQLite), respaldá el volumen antes de un upgrade grande. Para una foto consistente, pará el backend mientras copiás:

cd ~/heskala-onprem            # tu directorio de instalación
# El nombre real del volumen lo ves con: docker volume ls | grep data
docker compose stop backend    # evita copiar la DB con escrituras a medias
docker run --rm -v heskala-onprem_data:/data -v "$PWD:/backup" \
  alpine tar czf /backup/heskala-data-$(date +%F).tgz --exclude='*.sock' -C / data
docker compose start backend

--exclude='*.sock' evita el warning socket ignored (tar no puede archivar los sockets de runtime del backend; no son datos y se regeneran solos). El backup queda completo igual. Verificá con: tar tzf heskala-data-$(date +%F).tgz | head.

Dos cosas a tener en cuenta

• Fijar la versión: por defecto las imágenes usan el tag latest (traés lo último con docker compose pull). Para quedarte en una versión concreta, seteá HESKALA_VERSION y FRONTEND_VERSION en tu .env.
• Migraciones de datos: los cambios de estructura compatibles se aplican solos al actualizar. Si una versión necesita una migración de datos (backfill), las notas de esa release te lo indican y se corre a mano: docker compose exec deployer npx convex run migrations/<archivo>:<funcion>. Si las notas no mencionan ninguna, no hay que correr nada.

Quickstart con Docker (Plan C, manual)

Si preferís hacerlo paso a paso o querés entender qué hace cada cosa:

# 1. Bajá y descomprimí el bundle de la última versión (deriva de latest.txt)
VERSION=$(curl -fsSL https://docs.heskala.com/downloads/latest.txt)
curl -fsSL "https://docs.heskala.com/downloads/heskala-onprem-${VERSION}.tar.gz" \
  -o "heskala-onprem-${VERSION}.tar.gz"
tar -xzf "heskala-onprem-${VERSION}.tar.gz"
cd "heskala-onprem-${VERSION}"
cp .env.example .env
# Editá .env (INSTANCE_NAME, INSTANCE_SECRET, RESEND_API_KEY, etc.)

# 2. Generar el admin key (lo necesita el deployer para subir funciones)
docker compose up -d backend dashboard
docker compose exec backend ./generate_admin_key.sh
# Anotá el admin key, pegalo en .env como CONVEX_SELF_HOSTED_ADMIN_KEY

# 3. Levantar todo (backend, dashboard, deployer, frontend)
docker compose up -d
# El deployer corre una vez, sube las funciones y setea env vars, después termina.

# 4. Abrí http://localhost:3000
# El frontend se sirve desde el contenedor `frontend` (nginx),
# que internamente habla con el contenedor `backend` (Convex).

El compose levanta 4 servicios:

Servicio	Imagen	Puerto host	Función
backend	ghcr.io/get-convex/convex-backend	3210	Convex API (queries, mutations, auth, DB)
dashboard	ghcr.io/get-convex/convex-dashboard	6791	Panel admin interno (DB, logs, env vars)
frontend	ghcr.io/heskala/frontend	3000	App Heskala (UI del usuario final)
deployer	ghcr.io/heskala/convex-deployer	—	Deploya las funciones de Convex y setea env vars (corre una vez)

El usuario navega a http://localhost:3000. El frontend (nginx) hace proxy de /api/* (queries, mutations, auth), /.well-known/* (JWKS de Convex Auth), /license/* y /download/* al backend internamente, así no hace falta exponer el puerto 3210. El bundle del frontend usa window.location.origin, no una URL hardcodeada al backend.

Obtener tu token de licencia

Antes de llegar al dashboard necesitás un token de licencia firmado (es un JWT ECDSA que el backend valida contra su clave pública embebida). El token define el tier, qué módulos se muestran en el sidebar, y los límites de seats y sucursales.

Camino 1: Pedilo desde el formulario público (recomendado)

Andá a https://docs.heskala.com/solicitar-licencia/, completá el form con tus datos (nombre, correo, empresa, edición, cantidad de usuarios) y listo. Te llega el token firmado al mail en pocas horas (lo revisa Serlis y lo aprueba).

La licencia es de un solo uso: una vez que la activás en tu instalación on-prem, queda asociada a tu empresa. No se puede re-usar en otro servidor.

Camino 2: Pedirlo por mail

Si preferís no usar el formulario, mandanos un mail a licencias@heskala.com con:

• Nombre y razón social
• Email de contacto
• Edición (onprem)
• Cantidad de usuarios
• Tipo (lifetime o subscription anual)

Camino 3: Compilar desde código fuente (dev / test)

Si tenés el código fuente y la clave privada, podés generar tokens vos mismo:

# Starter, 2 usuarios, 1 sucursal, lifetime
LICENSE_TEST_PRIVATE_KEY="$(cat /tmp/prod-private.txt)" \
  npx tsx scripts/issue-test-license.ts \
    --tier starter --seats 2 --cust "Mi Empresa" --type lifetime

# Pro, 5 usuarios, 10 sucursales, 1 año
LICENSE_TEST_PRIVATE_KEY="$(cat /tmp/prod-private.txt)" \
  npx tsx scripts/issue-test-license.ts \
    --tier pro --seats 5 --cust "Mi Empresa" --type annual --days 365

# All (todos los módulos), sin límite de sucursales, 3 usuarios, lifetime
LICENSE_TEST_PRIVATE_KEY="$(cat /tmp/prod-private.txt)" \
  npx tsx scripts/issue-test-license.ts \
    --tier all --seats 3 --cust "Mi Empresa" --type lifetime

El script imprime el token a stdout. Copialo desde un archivo (no del terminal) para evitar caracteres invisibles:

npx tsx scripts/issue-test-license.ts --tier starter --seats 2 \
  --cust "Mi Empresa" --type lifetime > /tmp/licencia.txt
cat /tmp/licencia.txt | pbcopy   # macOS
# xclip -selection clipboard < /tmp/licencia.txt   # Linux

La LICENSE_TEST_PRIVATE_KEY tiene que corresponder a la clave pública embebida en el frontend (lib/licensing/public-key.ts). Si el token lo firmás con una clave distinta, el backend lo rechaza con firma_no_valida.

Después de obtener el token

El token es un string largo que empieza con lic_. Pegalo en la pantalla de /setup de tu instalación on-prem. Si te aparece firma_no_valida, mirá “Problemas comunes” más abajo (casi siempre es un caracter invisible en el portapapeles).

El servicio deployer

La imagen ghcr.io/get-convex/convex-backend es una imagen runtime: viene sin tus funciones pre-cargadas, sin env vars, sin JWT keys. En SaaS, Convex Cloud deploya todo automáticamente; en self-hosted, hay que hacerlo manualmente.

El deployer resuelve esto: es un sidecar que:

1. Espera a que backend esté healthy
2. Lee el CONVEX_SELF_HOSTED_ADMIN_KEY de .env
3. Corre npx convex deploy para subir todas las funciones
4. Genera un par de claves RSA con jose y las setea como JWT_PRIVATE_KEY y JWKS (necesarias para Convex Auth)
5. Setea EDITION=onprem, LICENSE_PUBLIC_KEY (baked en la imagen del deployer, debe coincidir con la del frontend) y otras env vars críticas
6. Termina (restart: "no")

Después de que el deployer completa, el backend ya tiene todo lo necesario para que el frontend se conecte y arranque la primera activación.

Setup atómico

El primer acceso con base vacía te lleva directo a /setup. En un solo submit:

1. Se crea la cuenta del administrador.
2. Se aprovisiona la empresa, la branch principal, el rol admin con full-access y la subscription con los módulos y límites del token.
3. Redirección a /dashboard.

No hay wizard de pasos en on-prem: el tier, los módulos y los límites ya vienen firmados en la licencia — no hay nada que el usuario tenga que elegir.

Licencia de un solo uso

Tu licencia on-prem queda atada a esta instalación en la activación (/setup o el primer heartbeat contra Heskala Cloud): cada instalación genera un identificador propio y el central lo asocia al lid de tu licencia. A partir de ahí:

• Una licencia = una instalación: si intentás activar el mismo token en otro servidor, el central lo rechaza (activated_on_other_server) y la app se bloquea. No podés levantar varias instalaciones con un solo token.
• Perpetua: las licencias on-prem no caducan; el vínculo tampoco vence.
• Migración a otro servidor: si necesitás mover tu instalación (servidor nuevo, base recreada, etc.), su identificador cambia y el central rechazaría la re-activación. Escribinos a licencias@heskala.com y liberamos el vínculo para que puedas activar en el nuevo servidor.

La firma criptográfica del token se sigue validando localmente, pero el vínculo (unicidad) se confirma contra Heskala Cloud — por eso tu instalación necesita poder alcanzarlo para activar y validar.

Tier system

El token de licencia define tres campos clave:

Campo	Significado
mods	Lista de módulos habilitados (clientes, ventas, facturas, etc.)
seats	Máximo de usuarios (0 = ilimitado)
mb	Máximo de sucursales (0 o ausente = ilimitado)

Tres tiers disponibles:

Tier	Módulos	seats	mb (sucursales)
starter	47 módulos (sistema + comercial + fiscal completo)	configurable	1
pro	47 módulos (igual que starter)	configurable	10
all	todos los disponibles en onprem (~64)	configurable	sin límite

Starter y Pro comparten los mismos módulos: ambos incluyen todo el fiscal (facturación, exoneraciones, anulaciones, notas crédito/débito, correlativos SAR). La diferencia entre ellos son los límites de usuarios y sucursales, no los features.

Para los ejemplos de cómo emitir un token con cada tier, mirá Obtener tu token de licencia más arriba.

Qué verificar

Una vez en el dashboard:

• Sidebar: solo aparecen los módulos habilitados en tu licencia.
• URL a un módulo fuera del tier: redirige a “módulo no incluido”.
• Usuarios: invitá hasta el límite de seats; el siguiente queda bloqueado.
• Sucursales: solo se pueden crear hasta mb branches.
• Sin suscripción en la UI: el panel de Suscripción no aparece en on-prem — la licencia se gestiona fuera del producto.

Caveats

• Código propietario excluido de las imágenes: las imágenes ghcr.io/heskala/frontend y ghcr.io/heskala/convex-deployer se construyen con la lógica de negocio de los módulos premium (operaciones, reportes) y la emisión de licencias removida antes de compilar. Tu servidor corre el producto, pero no recibe ese código fuente.
• Unicidad enforced contra el central: la licencia firmada se valida al boot y en cada heartbeat, que va contra Heskala Cloud. En la activación el central ata la licencia a tu instalación (fingerprint) y rechaza el mismo token en otro servidor (activated_on_other_server). Así, una licencia = una instalación (ver Licencia de un solo uso).
• Honor system en los datos de runtime: la firma no protege los valores de tu propia base (módulos habilitados, límites). Un usuario con acceso root al servidor puede modificarlos directamente. Endurecerlo (que el central sobrescriba el estado autoritativo de la subscription) está en el roadmap; el binding de arriba ya cierra el caso “un token en varios servidores”.
• Plan C (v0.6.0+): la imagen del frontend en ghcr.io/heskala/frontend es pública y se rebuilda en cada release tag. El docker-compose.yml del bundle ya la apunta al tag del release, así que con docker compose pull && docker compose up -d actualizás.
• Multi-arch (v0.7.0+): la imagen se publica como manifest list con variantes para linux/amd64 y linux/arm64. El pull es nativo en Mac M1/M2/M3/M4, servidores Linux amd64, AWS Graviton, Oracle Ampere y Raspberry Pi — sin emulación.

Problemas comunes

”firma_no_valida” al activar la licencia

Si el servidor responde firma_no_valida aunque tu token “se ve” bien, es muy probable que tenga un char invisible o modificado (zero-width space, BOM, soft-hyphen, etc.). El cliente ya limpia esos chars al pegar, pero a veces el clipboard introduce uno antes. Soluciones:

• Si el token lo recibiste por mail/chat, pegalo primero en un editor plano (TextEdit, VS Code) y de ahí al input, para que no arrastre formato ni caracteres invisibles.
• Si persiste, pedile a Heskala que te reenvíe el token (puede haberse cortado o alterado al copiarlo).

install.sh aborta con “Falta el plugin ‘docker compose’ v2”

El instalador exige el plugin v2 (docker compose, sin guion). Si aborta con ese mensaje, tenés el binario viejo standalone v1 (docker-compose con guion), que el stack no soporta.

Diagnosticá qué tenés instalado:

docker compose version

⚠️ docker compose -v y docker compose --version NO funcionan en Compose v2 (tiran el help en lugar de la versión). Usá docker compose version (subcomando explícito).

Tres escenarios posibles:

1. Dice Docker Compose version v2.x.x → todo bien, el problema es otro.
2. Dice docker: 'compose' is not a docker command (o variantes) → no hay plugin v2. Distinguí si tenés el binario viejo:
3. Dice command not found → ni siquiera el comando docker está en PATH.

Para distinguir el caso 2 (sin plugin):

command -v docker-compose

• Si devuelve una ruta → tenés el binario viejo standalone v1. Desinstalalo antes (entra en conflicto con el plugin v2):

sudo apt-get remove -y docker-compose

• Si devuelve vacío → no hay plugin ni binario viejo. Saltá al install.

Cómo se ve el error real en el install.sh:

xx  Falta el plugin 'docker compose' v2. Instalá Docker Compose v2
    (Docker 20.10+ ya lo incluye). El viejo 'docker-compose' (con guion)
    no sirve.

Solución, en una sola línea (instala el plugin oficial del repo de Docker, o el paquete de Ubuntu como fallback):

# Opción A (preferida, requiere el repo de Docker configurado)
sudo apt-get update && sudo apt-get install -y docker-compose-plugin

# Opción B (fallback, desde los repos de Ubuntu)
sudo apt-get install -y docker.io

# Verificá que ahora tenés v2
docker compose version

Tiene que decir Docker Compose version v2.x.x. Si dice v1.x.x, reinstalá Docker desde el instructivo de Windows (WSL2) o seguí la guía oficial de Docker para Ubuntu.

Esto es el mismo problema que el paso 3.5 del instructivo de Windows evita antes de instalar Heskala. Si seguiste esa guía, no deberías llegar acá.

docker compose pull falla al bajar frontend o deployer

Si el pull de ghcr.io/heskala/frontend o ghcr.io/heskala/convex-deployer falla con denied / unauthorized / manifest unknown, es porque ese paquete de GHCR quedó privado (GHCR publica los paquetes privados por defecto). Ambas imágenes deben estar en visibilidad Public:

1. Entrá a https://github.com/orgs/heskala/packages/container/<frontend|convex-deployer>/settings
2. Danger Zone → Change visibility → Public (una por imagen).

Verificá desde una máquina sin login:

docker logout ghcr.io
docker pull ghcr.io/heskala/frontend:latest
docker pull ghcr.io/heskala/convex-deployer:latest

Una vez públicas, las versiones que publiques después siguen siendo públicas (no hay que repetirlo por release).

El frontend se queda cargando y no llega al dashboard

• Confirmá que los servicios estén arriba: docker compose ps (backend healthy, frontend running).
• El deployer corre una vez en la primera instalación y sube las funciones al backend. Revisá que haya terminado bien: docker compose logs deployer. Si ves errores o HTTP actions not enabled, volvé a correrlo: docker compose up -d deployer.
• Revisá los logs del backend: docker compose logs -f backend.

El sidebar muestra módulos que no deberían estar

Si cambiaste el tier de la licencia y el sidebar sigue mostrando los módulos del tier anterior, el token quedó cacheado en el localStorage del browser. Limpiá:

1. DevTools (F12) → Application → Local Storage → http://localhost:3000
2. Borrá todas las keys que empiezan con heskala.license.
3. Hard refresh (Cmd+Shift+R)
4. Pegá el nuevo token

Cambié el token pero el backend no lo reconoce

Cada token está firmado para una instalación/versión. Si actualizaste a una versión nueva y el token deja de validar (firma_no_valida), puede ser que esa versión haya rotado la clave de licencia: pedile a Heskala un token nuevo para tu instalación. Antes de pegar el nuevo, limpiá el viejo del localStorage (ver arriba).

Soporte

Para reportar problemas o pedir nuevas features del flujo on-prem, contactanos por los canales habituales.