Instalar en Windows (sin Docker Desktop)

En Windows no estás obligado a usar Docker Desktop. Es lo más fácil, pero tiene dos cosas a considerar: es un instalador con asistente/GUI, y su licencia es paga para empresas medianas o grandes (gratis solo para uso personal y empresas con menos de 250 empleados y menos de US$10M de facturación anual).

Si querés evitar ambas cosas, la alternativa estándar es Docker Engine dentro de WSL2, todo por línea de comandos.

Por qué siempre hay una capa Linux: las imágenes de Heskala son contenedores Linux. En Windows eso corre siempre sobre WSL2 (o una VM Linux). Docker Desktop también usa WSL2 internamente — con esta guía simplemente te salteás el Desktop y su licencia.

Opción recomendada: Docker Engine en WSL2

1. Instalar WSL2 + Ubuntu

Preflight (sin esto wsl --install puede fallar silenciosamente):

Windows 10 build 19041+ o Windows 11. En Windows 10 <19041 el kernel de WSL2 viene por Windows Update.
Virtualización habilitada en BIOS/UEFI (VT-x en Intel, AMD-V en AMD). Sin esto, wsl --install falla.
4 GB de RAM libres (WSL2 reserva ~2 GB por default; el stack de Heskala ocupa otros ~2 GB encima).

En PowerShell como administrador, ejecutá estos comandos uno por uno (copiá, pegá, esperá el prompt de vuelta antes de seguir):

# 1) Bajá WSL a la última versión (recomendado por Microsoft; corrige bugs en systemd)
wsl --update

# 2) Fijá WSL2 como default ANTES del install (si quedó WSL1 de una migración vieja)
wsl --set-default-version 2

# 3) (Opcional) Listá las distros disponibles (si querés ver Debian, openSUSE, etc.)
wsl --list --online

# 4) Instalá Ubuntu. En Win11 / Win10 2004+ alcanza con el default; en máquinas
# viejas pasale el nombre exacto, p.ej.: wsl --install -d Ubuntu-22.04
wsl --install

Reiniciá cuando lo pida, creá el usuario de Ubuntu (nombre + contraseña), y verificá. Un comando por bloque:

# 5) Versión de WSL (tiene que decir 2.x)
wsl --version

# 6) Versión por distro (la columna "Version" tiene que decir 2)
wsl --list --verbose

Si wsl --list --verbose muestra WSL1, migrá con wsl --set-version Ubuntu 2 (tarda varios minutos).

2. Instalar Docker Engine dentro de Ubuntu

Abrí Ubuntu desde el menú inicio. El primer comando con sudo te va a pedir la contraseña que pusiste en el paso 1.

Ejecutá cada bloque por separado (no los pegues todos juntos: el primero puede pedirte password y los siguientes se perderían en el stdin):

# 1) Verificá que curl esté (Ubuntu lo trae de base; distros minimal pueden no)
which curl

Si el comando anterior no devuelve nada, instalalo:

sudo apt-get update && sudo apt-get install -y curl

# 2a) Opción preferida: script oficial de Docker (última versión)
curl -fsSL https://get.docker.com | sh

Si esto falla (proxy corporativo, error de GPG, conflicto de paquetes, etc.), usá el paquete oficial de Ubuntu. Es más viejo pero está testeado con tu versión de distro:

# 2b) Fallback: Docker desde los repos de Ubuntu
sudo apt-get update
sudo apt-get install -y docker.io

Verificá que quedó instalado antes de seguir:

docker --version

# 3) Para usar docker sin sudo el resto de la sesión
sudo usermod -aG docker $USER

Cerrá y reabrí Ubuntu para que tome el grupo docker.

3. Habilitar systemd (para que Docker arranque como servicio)

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

Después, en PowerShell: wsl --shutdown. Reabrí Ubuntu y habilitá Docker. Dos bloques separados:

# Habilita Docker para que arranque como servicio en cada boot
sudo systemctl enable --now docker

# Verificá que el daemon responde (tiene que listar Server + Client)
docker version

3.5 Sanity check antes de instalar Heskala

Confirmá que docker compose está disponible y funciona. Cada bloque es una verificación independiente — ejecutá uno, mirá el resultado, y si está OK seguí con el siguiente. Si alguno falla, no sigas: revisá la sección Diagnóstico al final.

1) ¿Existe el binario de docker?

command -v docker

Tiene que devolver una ruta (ej. /usr/bin/docker). Si devuelve vacío, el install de Docker no quedó aplicado al PATH: reinstalá con el paso 2.

2) ¿El daemon está corriendo y responde?

docker info

Las primeras líneas tienen que decir Server Version: 20.10+ y NO tiene que aparecer permission denied ni Cannot connect to the Docker daemon. Si aparece permission denied, te falta el paso 3 (usermod) o no re-abriste Ubuntu.

3) ¿Está el plugin docker compose v2?

docker compose version

⚠️ Cuidado con la sintaxis: docker compose -v y docker compose --version NO funcionan. Compose v2 solo expone la versión como subcomando explícito (version). Si te equivocás, el CLI tira el help largo en lugar de la versión, y parece que no hay plugin cuando sí lo hay.

Tiene que decir Docker Compose version v2.x.x (el v2 es importante).

Si en cambio te aparece cualquiera de estos mensajes, no tenés el plugin v2 instalado:

docker: 'compose' is not a docker command

"docker compose" is not a docker command (unknown command)

Esto pasa en dos casos:

Caso A: tenés Docker Engine pero sin el plugin (común en instalaciones viejas o en algunas distros que separan los paquetes).
Caso B: tenés el binario viejo standalone docker-compose con guion (versión 1.x), que es un binario distinto y no se invoca como docker compose.

Distinguí uno del otro:

command -v docker-compose

Si devuelve una ruta (ej. /usr/bin/docker-compose), tenés el binario viejo standalone v1. Desinstalalo primero (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 de abajo.

Después, instalá el plugin v2:

sudo apt-get update && sudo apt-get install -y docker-compose-plugin

# Verificá
docker compose version

Tiene que decir ahora Docker Compose version v2.x.x.

4) ¿El usuario puede correr contenedores sin sudo?

docker run --rm hello-world

Tiene que bajar la imagen, ejecutarla y mostrar Hello from Docker!. Si falla con permission denied, volvé a hacer el paso 3 y re-abrí la terminal.

4. Instalar Heskala

Ya con Docker funcionando dentro de WSL, seguí el quickstart normal (el install.sh corre igual dentro de Ubuntu):

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

Accedés desde el navegador de Windows a http://localhost:3000 (WSL2 publica los puertos en localhost).

Arranque automático tras un reinicio / corte de energía

Es el punto más importante en una PC de mostrador. Necesitás dos cosas:

Que los contenedores tengan restart: unless-stopped — ya viene así en el docker-compose.yml de Heskala (backend, frontend y dashboard). Con systemd habilitado + systemctl enable docker, apenas WSL arranca, Docker y el stack se levantan solos.
Que WSL2 arranque con Windows — WSL no arranca solo en el boot. Creá una tarea programada (Task Scheduler) que lo dispare al iniciar sesión:
- Programa/script: wsl
- Argumentos: -d Ubuntu -u root docker compose -f /home/<usuario>/heskala-onprem/docker-compose.yml up -d
- Disparador: Al iniciar sesión (y activá “Ejecutar con los privilegios más altos”).
Si el install.sh quedó bajo un usuario no-root (caso default en ~/heskala-onprem), reemplazá <usuario> por ese usuario, o cambiá el default user de Ubuntu a root (comando oficial de Microsoft) con: ubuntu config --default-user root. Si no, docker compose falla por permisos del socket.

Para que no dependa de que alguien inicie sesión a mano, configurá auto-login del usuario de Windows (así al encender, la sesión arranca sola y con ella la tarea).

Verificá el ciclo completo sin cortar la luz: reiniciá la máquina y, sin tocar nada, abrí http://localhost:3000.

Diagnóstico rápido

Comandos útiles de la doc oficial de Microsoft cuando algo no anda. Un comando por bloque, ejecutá solo el que aplique al síntoma que tengas.

Desde PowerShell:

# Versión de WSL, kernel, default distro
wsl --status

# Distros instaladas + estado + WSL1/WSL2 (la columna "Version" tiene que decir 2)
wsl --list --verbose

# IP de la VM de WSL2 (si localhost no carga, probá esta)
wsl hostname -I

# Reinicia la VM (útil tras tocar .wslconfig o systemd)
wsl --shutdown

Desde Ubuntu:

# ¿Docker arrancó como servicio?
sudo systemctl status docker

# Plugin "docker compose" v2 (NO "docker-compose" con guion)
docker compose version

# ¿systemd=true está aplicado?
cat /etc/wsl.conf

# Logs del backend de Heskala
docker compose logs backend

Síntomas comunes:

http://localhost:3000 no carga → probá con la IP de wsl hostname -I (algunos firewalls de Windows filtran el port-forwarding de WSL2).
wsl --list --verbose muestra WSL1 → migrá con wsl --set-version Ubuntu 2 (tarda varios minutos, no cortar).
systemctl: command not found → systemd no quedó habilitado. Verificá /etc/wsl.conf y re-ejecutá wsl --shutdown.
docker: permission denied → falta sudo usermod -aG docker $USER o no re-abriste Ubuntu tras hacerlo.
Puertos ocupados tras reinicio → WSL2 los mapea dinámicamente; wsl --shutdown los libera.
wsl --install falla con error de virtualización → habilitar VT-x/AMD-V en BIOS/UEFI y volver a intentar.

Otras alternativas

Opción	Sin licencia paga	Asistente/GUI	Nota
Docker Engine en WSL2	✅	No (CLI)	Recomendada para on-prem
Rancher Desktop	✅ (open source)	Sí	Reemplazo de Docker Desktop; usa WSL2 igual
Podman (+ podman-compose)	✅	CLI/GUI	Motor distinto; compatibilidad con `docker-compose.yml` no es 100%
Docker Desktop	Depende del tamaño	Sí	Lo más simple; licencia paga para empresas grandes

Recomendación

Para un cliente típico en Windows que corre Heskala como instalación local: WSL2 + Docker Engine — evita la licencia y el asistente, y con systemd + una tarea programada + restart: unless-stopped queda con arranque automático tras un corte de energía. Si el cliente prefiere algo con interfaz y no le pesa la licencia (empresa chica), Docker Desktop sigue siendo la vía más rápida.