Windmill en VPS: workflows TypeScript/Python sin dependencias

Por qué Windmill en lugar de n8n o Make en 2026

Beneficios concretos para equipos DevOps y agencias

• TypeScript y Python nativos — los scripts se ejecutan en un worker Node.js o Python sin transpilación ni capas intermedias; las dependencias npm/pip se resuelven automáticamente en la primera ejecución.
• Editor web con ejecución directa — escribe, prueba y relanza un script desde el navegador en segundos, sin hacer push de un commit ni reiniciar ningún servicio.
• Multi-tenancy integrado — un único despliegue soporta múltiples workspaces aislados, ideal para una agencia que gestiona varios clientes o un equipo con entornos dev/staging/prod.
• Cron jobs y webhooks sin plugins — programar un job con 0 9 * * 1-5 o exponer un endpoint webhook es una operación nativa, no un add-on.
• Variables secretas cifradas — los secretos se cifran con AES-256 en base de datos y nunca se exponen en logs; cada workspace tiene su propio ámbito de secretos.
• Sin vendor lock-in — todos los scripts, flows y recursos son exportables en JSON/YAML e importables en cualquier otro despliegue de Windmill.

Requisitos mínimos en cifras

Configuración mínima y recomendada

• Mínimo absoluto — 2 vCPU, 4 GB RAM, 20 GB SSD; adecuado para un workspace individual con 1 worker y jobs ocasionales.
• Equipo pequeño (recomendado) — 4 vCPU, 8 GB RAM, 40 GB SSD; soporta 3 workers concurrentes y PostgreSQL en el mismo host sin presión de memoria.
• Equipo o multi-cliente — 8 vCPU, 16 GB RAM, 80 GB SSD; soporta 6 a 8 workers y múltiples workspaces activos.
• Sistema operativo — Ubuntu 22.04 LTS o Debian 12; Docker Engine 24+ y Docker Compose v2 requeridos.
• Red — una IPv4 dedicada y un nombre de dominio para el certificado TLS; Windmill expone el puerto 8000 por defecto detrás de un reverse proxy.

Despliegue con Docker Compose en 7 pasos

1. 01

   Instalar Docker y Docker Compose v2

   En Ubuntu 22.04 o Debian 12: curl -fsSL https://get.docker.com | sh && docker compose version. Verifica que el comando devuelva Docker Compose version v2.x.x (sin guion). Si tu sistema aún tiene docker-compose (v1), desinstálalo: apt remove docker-compose.

2. 02

   Obtener el docker-compose.yml oficial

   Crea un directorio dedicado y descarga la configuración de referencia: mkdir -p /opt/windmill && cd /opt/windmill && curl -fsSL https://raw.githubusercontent.com/windmill-labs/windmill/main/docker-compose.yml -o docker-compose.yml. Este archivo declara cuatro servicios: db (PostgreSQL 16), windmill_server, windmill_worker y lsp (servidor de completado de código).

3. 03

   Crear el archivo .env

   Windmill requiere dos variables obligatorias. Genera una clave aleatoria: openssl rand -hex 32. Luego crea /opt/windmill/.env con: WM_BASE_URL=https://windmill.tu-dominio.com y WINDMILL_SECRET_KEY=<clave-generada>. Nunca hagas commit de este archivo.

4. 04

   Ajustar el número de workers

   Por defecto docker-compose.yml inicia 1 réplica de windmill_worker. Para iniciar 3: docker compose up -d --scale windmill_worker=3. En un VPS con 4 vCPU / 8 GB, 2 o 3 workers es el equilibrio óptimo.

5. 05

   Configurar Nginx como reverse proxy con TLS

   Instala Nginx y Certbot: apt install -y nginx certbot python3-certbot-nginx. Crea /etc/nginx/sites-available/windmill con un bloque server escuchando en el puerto 80, proxy_pass http://127.0.0.1:8000; y las cabeceras para WebSocket. Obtén el certificado: certbot --nginx -d windmill.tu-dominio.com.

6. 06

   Iniciar la stack y crear el workspace inicial

   Lanza la stack: cd /opt/windmill && docker compose up -d. Espera 30 segundos a que PostgreSQL esté listo y abre https://windmill.tu-dominio.com. La interfaz te pide crear un workspace y definir la cuenta de administrador.

7. 07

   Activar el reinicio automático y verificar logs

   En docker-compose.yml asegúrate de que cada servicio tenga restart: unless-stopped. Verifica los logs del servidor: docker compose logs -f windmill_server. La línea Windmill server started on port 8000 confirma que la instancia funciona.

Configuración: workspace, variables secretas y crons

Ajustes esenciales tras la instalación

• Workspace y permisos — en Settings → Workspace define la zona horaria (usada para crons) y activa Auto-approve executions solo si todos los miembros son de confianza.
• Variables y recursos — Variables almacena claves escalares cifradas con AES-256. Resources almacena objetos estructurados con esquema JSON (conexiones de base de datos, credenciales OAuth).
• Schedules (crons) — en el editor de un script, haz clic en Add schedule. La sintaxis aceptada es el formato cron estándar de 5 campos. La zona horaria del workspace se aplica automáticamente.
• Webhooks — cada script expone un endpoint de la forma /api/w/<workspace>/jobs/run/p/<path>. Autentica las llamadas entrantes con un token generado en Settings → Tokens.
• Git Sync — en Settings → Git Sync conecta un repositorio Git para sincronizar automáticamente todos los scripts, flows y recursos en cada modificación.

Ejemplo de workflow Python completo

Script Python: importación API → filtro → PostgreSQL

• Declaración de dependencias — las líneas # requirements: al inicio del script indican a Windmill qué paquetes pip instalar en el sandbox aislado.
• Firma de la función principal — Windmill siempre llama a def main(...). Los parámetros se inyectan desde la UI, el cron o el cuerpo del webhook.
• Llamada HTTP con httpx — import httpx; resp = httpx.get(api_url, timeout=10); resp.raise_for_status(); data = resp.json(). Windmill captura las excepciones no manejadas y las muestra en el log de ejecución.
• Filtrado e inserción — rows = [r for r in data if r.get('active')]; conn = psycopg2.connect(**db); cur.executemany('INSERT INTO items ...', rows); conn.commit(). El recurso db se pasa como dict Python.
• Valor de retorno — return {'inserted': len(rows), 'source': api_url}. El valor retornado se muestra en la UI y es accesible a los pasos siguientes de un Flow.

Resolución de problemas — errores frecuentes

5 errores reales y sus correcciones

• connection refused al arrancar el servidor — el contenedor windmill_server arranca antes de que PostgreSQL esté listo. Añade un healthcheck al servicio db y una cláusula depends_on: db: condition: service_healthy.
• Workers que permanecen IDLE indefinidamente — causa clásica: DATABASE_URL apunta a localhost en vez del nombre del servicio Docker (db). El valor correcto: postgresql://windmill:windmill@db/windmill.
• Scripts Python que fallan con ModuleNotFoundError — Windmill resuelve las dependencias pip en la primera ejecución. Si el worker no tiene acceso a internet, la instalación falla silenciosamente. Abre el puerto 443 saliente para pypi.org.
• Webhook devuelve 403 Forbidden — el script está en modo Require approval. Desactívalo en el editor o usa un token de servicio con el rol executor.
• Cron que no se dispara a la hora prevista — la zona horaria del workspace es UTC por defecto. Verifica el ajuste en Settings → Workspace → Timezone y reinicia: docker compose restart windmill_server.

Hacia la producción: checklist final

Puntos de validación antes de ir a producción

• TLS válido y HSTS — verifica que https://windmill.tu-dominio.com responde sin advertencias y añade Strict-Transport-Security: max-age=31536000.
• Backups probados — haz un dump de PostgreSQL, restáuralo en un contenedor de prueba y verifica que la interfaz conecta.
• Monitorización de workers — la página Admin → Workers muestra el estado en tiempo real. Configura una alerta si el número de workers activos cae por debajo de 1.
• Rotación de secretos — si pierdes WINDMILL_SECRET_KEY, los secretos cifrados en base de datos son irrecuperables. Guarda la clave en un gestor de secretos separado del VPS.
• Versión fijada en docker-compose.yml — reemplaza :latest por :1.830.0 para evitar actualizaciones automáticas no controladas.
• Git Sync activado — conecta un repositorio privado para versionar todos tus scripts y flows.

Windmill vs n8n vs Temporal

Desplace la tabla